Digital PDFs

AA-D028B-TE

March 1980

331 pages

Original

13MB

Document:	VAX/VMS I/O User’s Guide
Order Number:	AA-D028B-TE
Revision:	000
Pages:	331
Original Filename:

OCR Text

VAX/VMS
1/0 User's Guide
Order No. AA-00288-TE

March 1980

This document contains the information necessary to interface directly with the
110 device drivers supplied as part of the VAX/VMS operating system. Several
examples of programming techniques are included. This document does not
contain information on 1/0 operations using VAX-11 Record Management Services.

VAX/VMS
1/0 User's Guide
Order No. AA-00288-TE

SUPERSESSION/UPDATE INFORMATION:

This revised document supersedes
the VAX/VMS 1/0 User's Guide
(Order No. AA-D028A-TE)

OPERATING SYSTEM AND VERSION:

VAX/VMS V02

SOFTWARE VERSION:

VAX/VMS V02

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

digital equipment corporation · maynard, massachusetts

First Printing, August 1978
Revised, March 1980
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 only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

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

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
CO MT EX
DDT
DEC COMM
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

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

CONTENTS

Page
PREFACE
CHAPTER

xv
1

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

1-1

1.1
1.2
1. 3
1.4
1. 4 .1
1. 4. 2
1. 4. 3
1. 4. 4
1. 4. 5
1. 4. 6
1. 4. 7
1. 4. 8
1. 4. 9
1.4.10
1.4.11
1. 5
1.6
1. 6 .1
1. 6. 2
1. 6. 3
1. 7
1. 7 .1
1. 7. 2
1.8
1. 8 .1
i.8.2
1.8. 3
1. 8. 4
1.8. 5
1. 8. 6
1.8.6.1
1.8.6.2
1.8.6.3
1.8.6.4
1.8.6.5
1.8.6.6
1.8.6.7
1.8. 7

OVERVIEW OF VAX/VMS I/O
VAX/VMS I/O DEVICES
SUMMARY OF I/O SYSTEM SERVICES
QUOTAS, PRIVILEGES, AND PROTECTION
Buffered I/O Quota
Buffered I/O Byte Count Quota
Direct I/O Quota
·
AST Quota
Physical I/O Privilege (PHY IO)
Logical I/O Privilege (LOG IO)
Mount Privilege
Volume Protection
Device Protection
System Privilege (SYSPRV)
Bypass Privilege (BYPASS)
SUMMARY OF VAX/VMS QIO OPERATIONS
PHYSICAL, LOGICAL, AND VIRTUAL ~/O
Physical I/O Operations
Logical I/O Operations
Virtual I/O Operations
I/O FUNCTION ENCODING
Function Codes
Function Modifiers
ISSUING I/O REQUESTS
Channel Assignments
Device Allocation
I/O Function Requests
$QIO Macro Format
$QIOW Macro Format
$QIO and $QIOW Arguments
Event Flag Number Argument
Channel Number Argument
Function Argument
I/O Status Block Argument
AST Address Argument
AST Parameter Argument
Device/Function-Dependent Arguments
$INPUT and $OUTPUT Macro Format and
Arguments
Status Returns for System Services
I/O COMPLETION
Event Flags
I/O Status Block
Asynchronous System Traps
DEVICE INFORMATION

1-1
1-1
1-2
1-3
1-4
1-4
1-4
1-4
1-4
1-5
1-5
1-5
1-6
1-6
1-6
1-6
1-7
1-7
1-7
1-10
1-12
1-12
1-12
1-13
1-13
1-14
1-14

1.8 .8
1.9
1. 9 .1
1. 9. 2
1. 9. 3
1.10

iii

1-15
1-10
1-Hi
1-17
1-17
1-17
1-18
1-18
1-18

1-18
1-19
1-20
1-21
1-22
1-22
1-23
1-24

CONTENTS

Page
CHAPTER

TERMINAL DRIVER

2-1

2.1
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.3
2.4
2.4.1
2.4.1.1

2-1
2-1
2-2
2-2
2-2
2-3
2-4
2-5
2-9
2-9
2-10
2-13
2-14

2.4.4
2.5
2.6

SUPPORTED TERMINAL DEVICES
TERMINAL DRIVER FEATURES AND CAPABILITIES
Type-ahead
Line Terminators
Special Operating Modes
Escape Sequences
Terminal/Mailbox Interaction
Control Characters and Special Keys
Dial-Up
Duplex Modes
DEVICE INFORMATION
TERMINAL FUNCTION CODES
Read
Function Modifier Codes for Read QIO
Functions
Read Function Terminators
Write
Function Modifier Codes for Write QIO
Functions
Write Function Carriage Control
Set Mode
Hang-Up Function Modifier
Enable CTRL/C AST and Enable CTRL/Y
AST Function Modifiers
Sense Mode
I/O STATUS BLOCK
PROGRAMMING EXAMPLE

DISK DRIVERS

3-1

3.1
3 .1.1
3 .1. 2
3 .1. 3
3 .1. 4
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.3
3.4
3.4.1
3.4.2
3.4.3
3.4.3.1
3.4.3.2
3.4.4

SUPPORTED DISK DEVICES
RM03 Pack Disk
RP05 and RP06 Pack Disks
RK06 and RK07 Cartridge Disks
RXOl Console Disk
DRIVER FEATURES AND CAPABILITIES
Data Check
Overlapped Seeks
Error Recovery
Logical to Physical Translation (RXOl)
DEVICE INFORMATION
DISK FUNCTION CODES
Read
Write
Set Mode
Set Mode
Set Characteristic
Sense Mode
Pack Acknowledge
I/O STATUS BLOCK
PROGRAMMING EXAMPLE

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

2.4.1.2
2.4.2
2.4.2.1
2.4.2.2
2.4.3
2.4.3.1
2.4.3.2

CHAPTER

3.4.5
3.5
3.6

2-15
2-10
2-17
2-18
2-18
2-22
2-23
2-23
2-24
2-25
2-27

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

3-5
3-7
3-11
3-12
3-13
3-13
3-13
3-14
3-14
3-14
3-18

CONTENTS

Page
CHAPTER

CHAPTER

MAGNETIC TAPE DRIVER

4-1

4.1
4 .1.1
4 .1. 2
4 .1. 3
4.2
4.2.1
4.2.2
4.2.3
4.3
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6
4.4.7
4.4.8
4.4.9
4.4.9.1
4.4.9.2
4.5
4.6

SUPPORTED MAGNETIC TAPE DEVICES
TE16 Magnetic Tape Drive
TSll Magnetic Tape Subsystem
TU45 and TU77 Magnetic Tape System
DRIVER FEATURES AND CAPABILITIES
Master Adapters and Slave Formatters
Data Check
Error Recovery
DEVICE INFORMATION
MAGNETIC TAPE FUNCTION CODES
Read
Write
Rewind
Skip File
Skip Record
Write End-of-File
Rewind Of fl i ne
Sense Tape Mode
Set Mode
Set Mode
Set Characteristic
I/O STATUS BLOCK
PROGRAMMING EXAMPLE

4-1
4-1
4-2
4-2
4-2
4-2
4-3
4-3
4-4
4-5
4-9
4-10
4-11
4-11
4-12
4-12
4-12
4-12
4-13
4-13
4-14
4-15
4-18

LINE PRINTER DRIVER

5-1

5.1
5 .1.1
5 .1. 2
5.2
5.2.l
5.2.2
5.3
5.4
5.4.1
5.4.1.1
5.4.2
5.4.3
5.5
5.6

SUPPORTED LINE PRINTER DEVICES
LPll Line Printer Interface
LAll DECprinter I
DRIVER FEATURES AND CAPABILITIES
Output Character Formatting
Error Recovery
DEVICE INFORMATION
LINE PRINTER FUNCTION CODES
Write
Write Function Carriage Control
Sense Printer Mode
Set Mode
I/O STATUS BLOCK
PROGRAMMING EXAMPLE

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

CARD READER DRIVER

6-1

6.1
6.2
6.2.1
6.2.2
6.2.2.1
6.2.2.2
6.2.3
6.3
6.4
6.4.1
6.4.2
6.4.3

SUPPORTED CARD READER DEVICE
DRIVER FEATURES AND CAPABILITIES
Read Modes
Special Card Punch Combinations
End-of-File Condition
Set Translation Mode
Error Recovery
DEVICE INFORMATION
CARD READER FUNCTION CODES
Read
Sense Card Reader Mode
Set Mode

6-1
6-1
6-1

n-2

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

n-7

CONTENTS

Page

CHAPTER

6.4.3.1
6.4.3.2
6.5

Set Mode
Set Characteristic
I/O STATUS BLOCK

n-7
6-8
6-8

MAILBOX DRIVER

7-1

7.1
7 .1.1
7 .1. 2
7 .1. 3
7.2
7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.4
7.5

MAILBOX OPERATIONS
Creating Mailboxes
Deleting Mailboxes
Mailbox Message Format
DEVICE INFORMATION
MAILBOX FUNCTION CODES
Read
Write
Write End-of-File Message
Set Attention AST
I/O STATUS BLOCK
PROGRAMMING EXAMPLE

7-1
7-2
7-3
7-3
7-4
7-5
7-5
7-n
7-7
7-7
7-9
7-10

DMCll SYNCHRONOUS COMMUNICATIONS LINE
INTERFACE DRIVER

8-1

8.1
8 .1.1

CHAPTER

8.2
8.2.1
8.2.2
8.2.3
8.3
8.4
8.4.1
8.4.2
8.4.3
8.4.3.1
8.4.3.2
8.4.3.3
8.4.3.4
8.5

SUPPORTED DMCll SYNCHRONOUS LINE INTERFACES
DIGITAL Data Communications Message
Protocol
DRIVER FEATURES AND CAPABILITIES
Mailbox Usage
Quotas
Power Failure
DEVICE INFORMATION
DMCll FUNCTION CODES
Read
Write
Set Mode
Set Mode and Set Characteristics
Enable Attention AST
Set Mode and Shut Down Unit
Set Mode and Start Unit
I/O STATUS BLOCK

8-1
8-2
8-2
8-3
8-3
8-3
8-n
8-6
8-7
8-7
8-7
8-8
8-9
8-9
8-10

QIO INTERFACE TO FILE SYSTEM ACPS

9-1

9.1
9.2
9.2.1
9.2.2
9.3
9.3.1
9.3.2
9.3.3
9.3.4
9.3.5
9.3.6
9.3.7
9.3.7.1
9.4

FILE INFORMATION BLOCK
ATTRIBUTE CONTROL BLOCK
ACP QIO Record Attributes Area
ACP QIO Attributes Statistics Block
ACP FUNCTIONS AND ENCODING
Create File
Access File
Deaccess File
Modify File
Delete File
Mount
ACP Control
Disk Quotas
I/O STATUS BLOCK

9-1
9-14
9-17
9-19
9-19
9-21
9-22
9-24
9-24
9-25
9-26
9-2fl
9-27
9-31

8-1

CONTENTS

Page
CHAPTER

LABORATORY PERIPHERAL ACCELERATOR DRIVER

10.1
10.1.1
10.1.2
10. 2
10. 3
10.4
10.4.1
10.4.2
10.4.3
10.4.4
10.4.5
10.4.6
10.5
10.5.1
10.5.1.1
10.5.1.2
10.5.2

SUPPORTED DEVICE
10-1
LPAll-K Modes of Operation
10-1
Errors
10-2
SUPPORTING SOFTWARE
10-3
DEVICE INFORMATION
10-4
LPAll-K I/O FUNCTION CODES
10-7
Load Microcode
10-7
Start Microprocessor
10-8
Initialize LPAll-K
10-8
Set Clock
10-9
Start Data Transfer Request
10-10
LPAll-K Data Transfer Stop Command
10-12
HIGH LEVEL LANGUAGE INTERFACE
10-13
High-level Language Support Routines
10-13
Buff er Queue Control
10-14
Subroutine Argument Usage
10-14
LPA$ADSWP - Initiate Synchronous A/D
Sampling Sweep
10-18
LPA$DASWP - Initiate Synchronous D/A Sweep 10-19
LPA$DISWP - Initiate Synchronous Digital
Input Sweep
10-20
LPA$DOSWP - Initiate Synchronous Digital
Output Sweep
10-21
LPA$LAMSKS - Set LPAll-K and NUM Buffer
10-22
LPA$SETADC - Set Channel Information For
Sweeps
10-22
LPA$SETIBF - Set IBUF Array For Sweeps
10-23
LPA$STPSWP - Stop In-progress Sweep
10-24
LPA$CLOCKA - Clock A Control
10-24
LPA$CLOCKB - Clock B Control
10-25
LPA$XRATE - Compute Clock Rate and Preset
Value
10-26
LPA$IBFSTS - Return Buffer Status
10-27
LPA$IGTBUF - Return Buffer Number
10-27
LPA$INXTBF - Set Next Buffer to Use
10-28
LPA$IWTBUF - Return Next Buffer or Wait
10-29
LPA$RLSBUF - Release Data Buff er
10-30
LPA$RMVBUF - Remove Buffer ~rom Device
Queue
10-30
LPA$CVADF - Convert A/D Input to Floating
Point
10-31
LPA$FLT16 - Convert Unsigned 16-bit Integer
to Floating Point
10-31
LPA$LOADMC - Load Microcode and Initialize
LPAll-K
10-32
I/O STATUS BLOCK
10-32
LOADING LPAll-K MICROCODE
10-36
Microcode Loader Process
10-36
Operator Process
10-37
RSX-llM VERSION 3.1 AND VAX/VMS DIFFERENCES 10-37
Alignment and Length
10-37
Status Returns
10-38
Sweep Routines
10-38
General
10-38

10.5.3
10.5.4
10.5.5
10.5.6
10.5.7
10.5.8
10.5.9
10.5.10
10.5.11
10.5.12
10.5.13
10.5.14
10.5.15

io.5.in
10.5.17
10.5.18
10.5.19
10.5.20
10.5.21
10.6
10. 7
10.7.1
10.7.2
10 .8
10.8.1
10.8.2
10.8.3
10.8.4

vii

10-1

CONTENTS

Page
10.9
10.9.l
10.9.2
10.9.3
CHAPTER

PROGRAMMING EXAMPLES
LPAll-K High Level Language Program
(Program A)
LPAll-K High-level Language Program
(Program B)
LPAll-K QIO Functions Program
(Program C)

10-45

DR32 INTERFACE DRIVER

11-1

11.l
SUPPORTED DEVICE
11.l.l
DR32 Device Interconnect
11. 2
DR32 FEATURES AND CAPABILITIES
11.2.l
Command and Data Chaining
11. 2. 2
Far End DR-device Initiated Transfers
11.2.3
Power Failure
11. 2. 4
Interrupts
11.3
DEVICE INFORMATION
11.4
PROGRAMMING INTERFACE
11.4.l
DR32 - Application Program Interface
11.4.2
Queue Processing
11.4.2.l
Initiating Command Sequences
11.4.2.2
Device-Initiated Command Sequences
11.4.3
Command Packets
11.4.3.l
Length of Device Message Field
11.4.3.2
Length of Log Area Field
11.4.3.3
Device Control Code Field
11.4.3.4
Control Select Field
11.4.3.5
Suppress Length Error Field
11.4.3.6
Interrupt Control Field
11.4.3.7
Byte Count Field
11.4.3.8
Virtual Address of Buffer Field
11.4.3.9
Residual Memory Byte Count Field
11.4.3.10
Residual DD! Byte Count Field
11.4.3.11
DR32 Status Longword (DSL)
11.4.3.12
Device Message Field
11.4.3.13
Log Area Field
11.4.4
DR32 Microcode Loader
11.4.5
DR32 I/O Function Codes
11.4.5.l
Load Microcode
11.4.5.2
Start Data Transfer
11.4.6
High-level Language Interface
11.4.6.l
XF$SETUP
11.4.6.2
XF$STARTDEV
11.4.6.3
XF$FREESET
11.4.6.4
XF$PKTBLD
11.4.6.5
XF$GETPKT
11.4.n.n
XF$CLEANUP
11.4.7
User Program - DR32 Synchronization
11.4.7.l
Event Flags
11.4.7.2
AST Routines
11.4.7.3
Action Routines
11.5
I/O STATUS BLOCK
11.6
PROGRAMMING HINTS
11.6.1
Command Packet Pre-fetch
11.6.2
Action Routines
11.6.3
Error Checking
11.6.4
Queue Retry Macro

viii

10-38
10-39
10-40

11-1
11-1
11-2
11-3
11-3
11-3
11-3
11-4
11-5
11-5
11-6
11-7
11-7
11-8
11-9
11-10
11-10
11-14
11-14
11-15
11-15
11-15
11-Hi
11-H
11-17
11-18
11-19
11-19
11-20
11-20
11-21
11-23
11-24
11-20
11-28
11-29
11-32
11-33
11-34
11-34
11-34
11-35
11-36
11-40
11-40
11-41
11-41
11-41

CONTENTS

Page
Diagnostic Functions
The NOP Command Packet
Interrupt Control Field
PROGRAMMING EXAMPLES
DR32 High-level Language Program
(Program A)
DR32 Queue I/O Functions Program
(Program B)

11-41
11-42
11-42
11-43

DUPll INTERFACE DRIVER

12-1

12.1
12.1.l
12.1.1.1
12.1.1.2
12.2
12.3
12.3.1
12.3.2
12.3.3
12.3.4
12.4

SUPPORTED DEVICE
Driver Operating Modes
BSC Mode
Binary Mode
DEVICE INFORMATION
DUPll FUNCTION CODES
Read
Write
Set Mode
Sense Mode
I/O STATUS BLOCK

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

I/O FUNCTION CODES

A-1

TERMINAL DRIVER
DISK DRIVERS
MAGNETIC TAPE DRIVERS
LINE PRINTER DRIVER
CARD READER DRIVER
MAILBOX DRIVER
DMCll DRIVER
ACP INTERFACE DRIVER
LPAll-K DRIVER
DR32 DRIVER
DUPll DRIVER

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

11.6.5
11.6.6
11. 6. 7
11. 7
11.7.1
11.7.2
CHAPTER

APPENDIX A
A. l
A.2
A.3
A.4
A.5
A.6
A.7
A.8
A.9
A.10
A.11

INDEX

11-43
11-49

Index-1

FIGURES
FIGURE

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

Physical I/O Access Checks
Logical I/O Access Checks
Physical, Logical, and Virtual I/O
I/O Function Format
Function Modifier Format
System Service Status Return
I/O Status Block Format
CALL Instruction Argument List
Buff er Format for $GETCHN and $GETDEV System
Services
Terminal Mailbox Message Format
Terminal Information
Short and Long Forms of Terminator Mask
Quadwords

1-8
1-9
1-11
1-12
1-13
1-20
1-22
1-23
1-25
2-5
2-10
2-17

CONTENTS
FIGURES (Cont. )

Page
FIGURE

2-4
2-5

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

4-2
4-3

4-4
4-5

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

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

P4 Carriage Control Specifier
Write Function Carriage Control
(Prefix and Postfix Coding)
Set Mode Characteristic Buffer
Sense Mode Characteristics Buffer
Sense Mode Characteristics Buffer
(Type-ahead)
IOSB Contents - Read Function
IOSB Contents - Write Function
IOSB Contents - Set Mode, Set
Characteristics, Sense Mode, and Sense
Characteristics Functions
Disk Information
Starting Physical Address
Physical Cylinder Number Format
Set Mode Characteristics Buffer
Set Characteristic Buffer
IOSB Content
IOSB Content - Sense Mode
Magnetic Tape Information
IO$ SKIPFILE Argument
IO$-SKIPRECORD Argument
Set-Mode Characteristics Buffer
Set Characteristic Buffer
IOSB Content
Printer Information
P4 Carriage Control Specifier
Write Function Carriage Control
(Prefix and Postfix Coding)
Set Mode Characteristics Buffer
Set Characteristic Characteristics Buffer
IOSB Contents - Write Function
IOSB Contents - Set Mode Function
Card Reader Information
Binary and Packed Column Storage
Set Mode Characteristics Buffer
Set Characteristic Buffer
IOSB Contents
Multiple Mailbox Channels
Typical Mailbox Message Format
Mailbox Information
Read Mailbox
Write Mailbox
Write Attention AST (Read Unsolicited Data)
Read Attention AST
IOSB Contents - Read Function
IOSB Contents - Write Function
Mailbox Message Format
DMCll Information
Pl Characteristics Block
IOSB Content
ACP QIO Interface
File Information Block Format
Typical Short File Information Block
Attribute Control Block Format
ACP QIO Record Attributes Area
ACP QIO Attributes Statistics Block
x

2-19
2-21
2-22
2-25
2-25
2-25
2-26
2-26
3-6
3-11
3-11
3-13
3-14
3-15
3-15

4-4
4-11
4-12
4-13

4-14
4-15
5-3
5-5
5-7

5-8
5-8
5-9
5-9
6-4
6-6
6-7
6-8
6-9
7-3
7-4
7-4
7-6
7-7
7-8
7-9
7-9
7-10
8-3
8-3
8-8
8-10
9-1
9-2
9-2
9-15
9-18
9-19

CONTENTS
FIGURES (Cont.)

Page
FIGURE

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

ACP Device/Function-Dependent Arguments
ACP Device/Function Argument Descriptor
Format
Quota File Transfer Block
IOSB Contents - ACP QIO Functions
Relationship of Supporting Software to
LPAll-K
LPAll-K Information
Data Transfer Command Table
Buff er Queue Control
I/O Functions IOSB Content
Basic DR32 Configuration
DR32 Information
Command Block (Queue Headers)
DR32 Command Packet Queue Flow
DR32 Command Packet
Data Transfer Command Table
ACTION Routine Synchronization
I/O Functions IOSB Content
3780 Message Block Example
3780 Message Block Example (Modified)
Nontransparent 2780 Message Block Example
Nontransparent 2780 Message Block Example
(Modified)
Transparent 2780 Message Block Example
(Modified)
DUPll Information
Set Mode Pl Buff er
IOSB Content
IOSB Content - Sense ·Mode

9-20
9-21
9-28
9-32
10-4
10-5
10-11
10-15
10-32
11-2
11-4
11-n
11-8
11-9
11-21
11-35
11-30
12-2
12-3
12-3
12-3
12-3
12-4
12-7
12-8
12-9

TABLES
TABLE

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

Read and Write I/O Functions
Device/Function-Independent Arguments
$INPUT and $OUTPUT Arguments
$QIO, $QIOW, $INPUT, and $OUTPUT System
Services Status Returns
$GETCHN and $GETDEV Arguments
$GETCHN and $GETDEV Status Returns
Terminal Control Characters
Special Terminal Keys
Terminal Device-Independent Characteristics
Terminal Characteristics
Read QIO Function Modifiers
Write QIO Function Modifiers
Write Function Carriage Control (FORTRAN:
Byte 0 not equal to 0)
Write Function Carriage Control
(P4 byte 0 = 0)
Terminal QIO Status Returns
Disk Devices
Disk Device Characteristics

1-12
1-ln
1-19
1-21
1-24
l-2n
2-6
2-8
2-11
2-12
2-15
2-18
2-19
2-20
2-20
3-1
3-6

CONTENTS
TABLES (Cont.)

Page
TABLE

3-3
3-4

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

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

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

9-4
9-5
9-6

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

10-7
10-8
10-9

10-10

Disk I/O Functions
Status Returns for Disk Devices
Magnetic Tape Devices
Magnetic Tape Device-Independent
Characteristics
Device-Dependent Information for Tape
Devices
Magnetic Tape I/O Functions
Set Mode and Set Characteristic Magnetic
Tape Characteristics
Status Returns for Tape Devices
Printer Device-Independent Characteristics
Printer Device-Dependent Characteristics
Write Function Carriage Control (FORTRAN:
Byte 0 not equal to 0)
Write Function Carriage Control
(P4 byte 0
equal to 0)
Line Printer QIO Status Returns
Card Reader Device-Independent
Characteristics
Device-Dependent Information for Card
Readers
Card Reader I/O Functions
Set Mode and Set Characteristic Card Reader
Characteristics
Status Returns for Card Reader
Mailbox Read and Write Operations
Mailbox Characteristics
Mailbox QIO Status Returns
Supported DMCll Options
DMCll Device Characteristics
DMCll Device Types
DMCll Unit Characteristics
DMCll Unit and Line Status
Error Summary Bits
Status Returns for DMCll
Contents of the File Information Block
FIB Argument Usage in ACP QIO Functions
Attribute Control Block Fields
ACP QIO Attributes
ACP Record Attributes Values
Disk Quota and Lock/Unlock Bits
ACP QIO Status Returns
Minimum and Maximum Conf iqurations per
LPAll-K
Device-independent Characteristics
Device-Dependent Characteristics
VAX-11 Procedures for the LPAll-K
Subroutine Argument Usage
LPA$IGTBUF Call - IBUFNO and IOSB Contents
LPA$IWTBUF Call - IBUFNO and IOSB Contents
LPAll-K Status Returns for I/O Functions
Program A Variables
Program B Variables

xii

3-8
3-15
4-1

4-4
4-5
4-6
4-13
4-15
5-3
5-4
5-n
5-6
5-9

n-4
6-5
6-5

6-8
6-9

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

9-10
9-15
9-10
9-18
9-29
9-32
10-2
10-5

10-fi
10-13
10-15
10-28
10-29
10-33
10-39
10-41

CONTENTS
TABLES

(Cont.)

Page
TABLE

11-1
11-2
11-3
11-4
11-5
11-6
12-1
12-2
12-3

12-4

Device-Independent Characteristics
Device Control Code Descriptions
DR32 Status Longword (DSL) Status Bits
VAX-11 Procedures for the DR32
DR32 Status Returns
Device-Dependent IOSB Returns for I/O
Functions
Device-Independent Characteristics
DUPll I/O Functions
DUPll Status Returns
Device-Dependent Status Returns

xiii

11-4
11-11
11-17
11-24
ll-3fl

11-38
12-5

12-11
12-9
12-9

PREFACE

MANUAL OBJECTIVES
This manual provides users of the VAX/VMS operating system with the
information necessary to interface directly with the I/O device
drivers supplied as part of the operating system.
It is not the
objective of this manual to provide the reader with information on all
aspects of VAX/VMS input/output (I/O) operations.

INTENDED AUDIENCE
This manual is intended for system programmers who want to take
advantage of the time and/or space savings that result from direct use
of the I/O devices. Users of VAX/VMS who do not require such detailed
knowledge of I/O drivers can use the device-independent services
described in the VAX-11 Record Management Services Reference Manual
Readers are expected to have some experience with either VAX-11
FORTRAN or VAX-11 MACRO assembly language.

STRUCTURE OF THIS DOCUMENT
This manual is organized into thirteen chapters and one
follows:

appendix,

1
• Chapter
overviews

contains introductory information.
It provides
of VAX/VMS I/O operations; I/O system services;
and I/O quotas, privileges, and protection.
This chapter
describes I/O function encoding and how to make I/O requests.
It also describes how to obtain information on the different
devices.

2 through 8 and 10 through 12 describe the use of all
• Chapters
the I/O device drivers supported by VAX/VMS:

- Chapter 2 deals with the terminal driver
- Chapter 3 deals with disk drivers
- Chapter 4 deals with magnetic tape drivers
- Chapter 5 deals with the line printer driver

- Chapter n deals with the card reader driver
- Chapter 7 deals with the mailbox driver
xv

- Chapter 8 deals with the DMCll driver
- Chapter 10 deals with the LPAll-K driver
- Chapter 11 deals with the DR-32 driver

- Chapter 12 deals with the DUPll driver

•

Chapter 9 describes the Queue I/O (QIO)
interface
system ancillary control processes (ACPs).

•

The appendix summarizes the QIO function codes, arguments, and
function modifiers used by the different device drivers.

file

ASSOCIATED DOCUMENTS

The following documents may also be useful:
•

VAX/-11 Information Directory and Index - contains a
list of all VAX-11 documents

•

VAX/VMS Sys tem___s_~_E.~.!-~e-~···-~e f e rence Manual

•

VAX-11 Linker Reference Manual

•

VAX-11 Software Handbook

•

PDP-11

VAX-11 FORTRAN User's Guide

VAX-11 MACRO User's Guide

•

VAX-11 Record Management

•

LPAll-K Laborat:.?!X_~-~.E!PE.C:: . ~-~-~-·~-~<:~lerator user's Guide

•

DECnet-VAX User's Guide

•

VAX/VMS 2780/3780 Protocol Emulator User's Guide

Periphe~?ls

complete

H~ndboo~

~e!vices

Reference Manual

CONVENTIONS USED IN THIS MANUAL

The following conventions are used in this manual.
Convention
[]

Meaning
Brackets in QIO requests
For example:

enclose

optional

arguments.

IO$ CR EAT E P 1 , [ P 2 ] , [ P 3 ] , [ P 4 ] , [ P 5 ]

Horizontal ellipses indicate that
arguments not pertinent to the
omitted. For example:
(that is, 8, 16, 24, ••• ).

xvi

characters or QIO
example have been

Meaning

Convention

Vertical ellipses in coding examples indicate that
lines of code not pertinent to the example are omitted.
For example:
TTCHAN:

.BLKW 1

$ASSIGN_S DEVNAM=TTNAME,CHAN=TTCHAN
Hyphens in coding examples indicate
arguments to the QIO request are
following 1 ine {s). For example:
$QIO_S

FUNC=#IO$_WRITEPBLK,CHAN=W"TTCHAN1,EFN=#l ,Pl=W"ASTMSG ,P2=#ASTMSGSIZE

Angle brackets enclose keys on the
For example:

that additional
provided on the

; FUN CT ION IS
;WRITE PHYSICAL
;TO TTCHAN 1
;EVENT FLAG 1
;Pl
BUFFER
;P2 = BUFFER SIZE
terminal

keyboard.

<O> <20-2F> ••• <40-7E>
numbers

Unless otherwise noted, all numbers in the text are
assumed to be decimal. Nondecimal radixes -- binary,
octal, or hexadecimal -- are explicitly indicated in
coding examples.

xvii

CHAPTER 1
INTRODUCTION TO VAX/VMS INPUT/OUTPUT

VAX/VMS supports a variety of input and output (I/O) devices,
including
disks, terminals, magnetic tapes, card readers, line
printers, synchronous line interfaces, real-time I/O devices, and
software mailboxes. This manual describes the capabilities of VAX/VMS
device drivers and their programming interface, and gives several
simple
programming
examples
that use I/O drivers to perform
input/output operations.

1.1

OVERVIEW OF VAX/VMS I/O

Input/output operations under VAX/VMS are designed to be as deviceand function-independent as possible.
User processes issue I/O
requests to software channels, which form paths of communication with
a
particular
device.
Each
process
can
establish its own
correspondence between physical devices and channels.
I/O requests
are queued when they are issued and processed according to the
relative priority of the process that issued them. I/O requests can
be handled indirectly by the VAX-11 Record Management Services (RMS)
or they can interface directly to the VAX/VMS I/O system.
(VAX-11 RMS
is described in the VAX-11 Record Management Services Reference
Manual.)
To access the I/O services described in this manual, users issue
system service requests.
In certain system service requests, a
function code included in the request defines the particular operation
to be performed. For example, Queue I/O (QIO) system service requests
can specify such operations as reading and writing blocks of data.
QIO requests can also specify a number of device-specific input/output
operations, for example, converting lowercase characters to uppercase
in terminal read operations or rewinding magnetic tape.

1.2

VAX/VMS I/O DEVICES

This manual describes VAX/VMS support for the following devices:
•

Terminals,
using
the
DZll
Asynchronous
Multiplexer, and the VAX-11/780 console

1-1

Serial

Line

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
•

Disk devices:
- RM03 Pack Disk
- RPOS and RP06 Pack Disks
- RK06 and RK07 Cartridge Disks
- RXOl Floppy Disk

•

Magnetic tape devices:
- TE16 Magnetic Tape
- TU45 and TU77 Magnetic Tape Systems
- TSll Magnetic Tape

•

Line printers:
- LPll Line Printer Interface
- LAll DECprinter

•

CRll Card Reader

•

DMCll Synchronous Line Interface

•

Mailboxes -- virtual devices used for interprocess transfer of
information

•

LPAll-K Laboratory Peripheral Accelerator

•

DR32 Interface

•

DUPll Synchronous Line Interface

Chapters 2 through 8 and lD through 12 describe in detail the
f~r these I/O devices and the I/O operations they perform.

1.3

drivers

SUMMARY OF I/O SYSTEM SERVICES

The following system services allow the direct use
system's I/O resources:

the

•

Assign I/O Channel

($ASSIGN)

•

Deassign I/O Channel

•

Queue I/O Request ($QIO)

•

Queue I/O Request and Wait for Event Flag (SQIOW)

•

Allocate Device ($ALLOC)

•

Deallocate Device ($DALLOC)

•

Get Channel Information ($GETCHN)

•

Get Device Information (SGETDEV)

•

Cancel I/O on Channel

($DASSGN)

($CANCEL)

1-2

operating

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
•

Create Mailbox and Assign Channel ($CREMBX)

•

Delete Mailbox ($DELMBX)

•

Wait for Single Event Flag ($WAITFR)

Wait for Logical AND of Event Flags ($WFLAND)

•

Wait for Logical OR of Event Flags ($WFLOR)

Set AST Enable ($SETAST)

•

Set Resource Wait Mode ($SETRWM)

This manual describes the use of system services for I/O operations.
It also describes other system services used with I/O operations such
as asynchronous system traps (ASTs) and event flag services.
Section
1.8 describes the QIO request system service; ASTs and event flags,
and $GETCHN are described in Sections 1.9 and 1.10, respectively.
Section 1.8.7 describes the use of the $INPUT and $OUTPUT macros,
which perform functions similar to the $QIOW system service.
See the VAX/VMS System Services Reference Manual for
detailed
information on all these system services and examples of their use.
The VAX/VMS System Services Reference Manual also contains information
on physical and logical device-naming conventions.

1.4

QUOTAS, PRIVILEGES, AND PROTECTION

To preserve the integrity of the system, VAX/VMS I/O operations are
performed under the constraints of quotas, privileges, and protection.
Quotas establish a limit on the number and type of I/O operations that
a process can perform concurrently. They ensure that all users have
an equitable share of system resources a~d usage.
Privileges are granted to a user to allow the performance of certain
I/O-related operations, for example, create a mailbox and perform
logical I/O to a file-structured device.
Restrictions on user
privilege protect the integrity and performance of both the operating
system and· the services provided other users.
Protection is used to control access to files and devices.
Device
protection is provided in much the same way as file protection:
shareable and nonshareable devices are protected by protection masks.
The Set Resource Wait Mode ($SETRWM) system service allows a process
to select either of two modes when an attempt to exceed a quota
occurs. In the enabled (default) mode, the process waits until the
required resource is available before continuing. In the disabled
mode, the process is notified immediately by a system service status
return that an attempt to exceed a quota has occurred. Waiting for
resources is transparent to the process when resource wait mode is
enabled;
no explicit action is taken by the process when a wait is
necessary.
The different types of I/O-related quotas, privileges, and
are described in the following paragraphs.

1-3

protection

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
1.4.l

Buffered I/O Quota

The buffered I/O quota specifies the maximum number of concurrent
buffered I/O operations a process can have active. In a buffered I/O
operation, the user's data is buffered in system dynamic memory.
The
driver deals with the system buffer and not the user buffer. Buffered
I/O is used for terminal, line printer, card reader, network, mailbox,
and console medium {RXOl) transfers. The user's buffer does not have
to be locked in memory for a buffered I/O operation.
The buffered I/O quota value is established in the user authorization
file by the system manager or by the process's creator. Resource wait
mode is entered if enabled by the Set Resource Wait Mode system
service and an attempt to exceed the buffered I/O quota is made.

1.4.2

Buffered I/O Byte Count Quota

The buffered I/O byte count quota specifies the maximum amount of
buff er space that can be consumed from system dynamic memory for
buffering I/O requests. All buffered I/O requests require system
dynamic memory in which the actual I/O operation takes place.
The buffered I/O byte count quota is established in the user
authorization file by the system manager or by the process's creator.
Resource wait mode is entered if enabled by the Set Resource Wait Mode
system service and an attempt to exceed the buffered I/O byte count
quota is made.

1.4.3

Direct I/O Quota

The direct I/O quota specifies the maximum number of concurrent direct
{that is, unbuffered), I/O operations that a process can have active.
In a direct I/O operation, data is moved directly to or from the user
buffer.
Direct I/O is used for disk, magnetic tape, DMA real-time
devices, and non-network DMCll transfers. For direct I/O, the user's
buffer must be locked in memory during the transfer.
The direct I/O quota value is established in the user authorization
file by the system manager or by the process's creator. Resource wait
mode is entered if enabled by the Set Resource Wait Mode system
service and an attempt to exceed the direct I/O quota is made.

1.4.4

AST Quota

The AST quota specifies the maximum number of asynchronous system
traps that a process can have outstanding.
The quota value is
established in the user authorization file by the system manager or by
the process's creator.
There is never an implied wait for this
resource.

1.4.5

Physical I/O Privilege (PHY_IO)

Physical I/O privilege allows a process to perform physical I/O
operations on a device. Physical I/O privilege also allows a process
to perform logical I/O operations on a device.
{Figures 1-1 and 1-2
show the use of physical I/O privilege in greater detail.)

1-4

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
1.4.6

Logical I/O Privilege {LOG_IO)

Logical I/O privilege allows a process to perform logical I/O
operations
on a device.
A process can also perform physical
operations on a device if the process has logical I/O privilege, the
volume is mounted foreign, and the volume protection mask allows
access to the device.
(Figures 1-1 and 1-2 show the use of logical
I/O privilege in greater detail.)

1.4.7

Mount Privilege

Mount privilege allows a process to use the IO$ MOUNT function to
perform mount operations on disk and magnetic tape-devices. IO$ MOUNT
is used in ACP interface operations (see Chapter 9).

1.4.8

Volume Protection

Volume protection protects the integrity of mailboxes and both foreign
and Files-11 structured volumes.
Volume protection for a foreign
volume is established when the volume is mounted.
Volume protection
for a Files-11 structured volume is established when the volume is
initialized.
(The protection can be overridden when the volume is
mounted if the process that is mounting the volume has the override
volume protection privilege.)
Mailbox protection is established
protection mask argument.

the

SCREMBX

system

service

Protection for structured volumes and mailboxes is provided by a
volume protection mask that contains four 4-bit fields. These fields
correspond to the four classes of users that are permitted to access
the volume.
(User classes are based on the volume owner's user
identification code, UIC.)
The 4-bit fields are interpreted differently for volumes that are
mounted as structured (that is, volumes serviced by an Ancillary
Control Process (ACP)) and volumes that are mounted as foreign.
The 4-bit fields have the following
structured:
15

world

group

delete

execute

format

1-5

for

volumes

mounted

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

The 4-bit fields have the following
foreign:
11

Log 1/0

Phy 1/0

format

for

volumes

mounted

and

]

*not used

Usually, volume protection is
operations.

meaningful

only

for

Device protection protects the allocation
such as terminals and card readers.

nonshareable

1.4.9

read

write

Device Protection

devices,

Protection is provided by a device protection mask similar to that of
volume
protection,
the
difference
being
that only the bit
corresponding to read access is checked and determines if the process
can allocate or assign a channel to the device.
Device protection is established with the SET PROTECTION/DEVICE DCL
operator command.
Both the protection mask and the device owner UIC
are set with this command.

1.4.10

System Privilege (SYSPRV}

System UIC privilege allows a process to be eligible for the volume or
device protection specified for the system protection class, even
though the process does not have a UIC in one of the system groups.

1.4.11

Bypass Privilege (BYPASS}

Bypass privilege allows a process
device protection.

1.5

completely

bypass

volume

and

SUMMARY OF VAX/VMS QIO OPERATIONS

VAX/VMS provides QIO operations that perform three
basic
I/O
functions:
read, write, and set mode. The read function transfers
data from a device to a user-specified buffer.
The write function
transfers data in the opposite direction -- from a user-specified
buffer to the device. For example, in a read QIO function to a
terminal device, a user-specified buffer is filled with characters
received from the terminal. In a write QIO function to the terminal,
the data in a user-specified buffer is transferred to the terminal
where it is displayed.
The set mode QIO function is used to control or describe the
characteristics and operation of a device. For example, a set mode
QIO function to a line printer can specify either uppercase or
lowercase character format. Not all QIO functions are applicable to
all types of devices. The line printer, for example, cannot perform a
read QIO function.

1-n

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
1.6

PHYSICAL, LOGICAL, AND VIRTUAL I/O

I/O data transfers can occur in any one of three device addressing
modes: physical, logical, or virtual. Any process with device access
allowed by the volume protection mask can perform logical I/O on a
device that is mounted foreign;
physical I/O requires privilege.
Virtual I/O does not require privilege; however, intervention by an
ACP to control user access may be necessary if the device is under ACP
control.
(ACP functions are described in Chapter 9.)

Physical I/O Operations

l.n.l

In physical I/O operations, data is read from and written to
actual, physically addressable units accepted by the hardware;
example, sectors on a disk or binary characters on a terminal in
PASSALL mode. This mode allows direct access to all device-level
operations.

the
for
the
I/O

Physical I/O requires that one of the following conditions be met:

• The issuing process has physical .I/O privilege (PHY- IO)
the
issuing process has logical I/O privilege
(LOG IO)
• The
device is mounted foreign, and the volume protection mask
I

allows physical access to the device
If neither of these conditions is met, the physical I/O operation is
rejected by the QIO system service with a status return of SS$ NOPRIV
(no privilege). Figure 1-1 illustrates the physical I/O access-checks
in greater detail.
The inhibit error-logging function modifier
(IOSM INHERLOG) can be
specified for all physical I/O functions.
IO$M INHERLOG inhibits the
logging of any error that occurs during the I/O operation.

Logical I/O Operations

l.n.2

In logical I/O operations, data is read from and written to logically
addressable units of the device. Logical operations can be performed
on both
block-addressable
and
record-oriented
devices.
For
block-addressable devices (for example, disks), the addressable units
are 512-byte blocks. They are numbered from 0 to n where n is the
last block on the device. For record-oriented or non-block-structured
devices (for example, terminals), logical addressable units are not
pertinent and are ignored.
Logical I/O requires that one of the
following conditions be met:
•

The issuing process has physical I/O privilege (PHY_IO)

•

The issuing process has logical I/O privilege (LOG IO)

•

The volume is mounted foreign and the volume
allows access to the device

protection

mask

If none of these conditions is met, the logical I/O operation is
rejected by the QIO system service with a status return of SS$ NOPRIV
(no privilege). Figure 1-2 illustrates the logical I/O access -checks
in greater detail.

1-7

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

START

YES

ALLOW

DENY
ACCESS

ACCESS

*Volume protection mask allows access

Figure 1-1

Physical I/O Access Checks

1-8

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

START

YES

ALLOW
ACCESS

DENY
ACCESS

*Volume protection mask allows access

Figure 1-2

Logical I/O Access Checks

1-9

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

1.6.3

Virtual I/O Operations

Virtual I/O operations can be performed on both record-oriented
(non-file-structured) and block-addressable (file-structured) devices.
For record-oriented devices
(for example, terminals), the virtual
function is the same as a logical function;
the virtual addressable
units of the devices are ignored.
For block-addressable devices (for example, disks), data is read from
and written to open files.
The addressable units in the file are
512-byte blocks. They are numbered starting at 1 and are relative to
a file rather than to a device. Block-addressable devices must be
mounted and structured and must contain a previously opened file.
Virtual I/O operations also require that the volume protection mask
allow access to the device
(a process having either physical or
logical I/O privilege can override the volume protection mask).
If
these conditions are not met, the virtual I/O operation is rejected by
the QIO system service with one of the following status returns:
Meaning

Status Return

SS$ NOPRIV

No privilege

SSS DEVNOTMOUNT

Device not mounted

SS$ DEVFOREIGN

Volume mounted foreign
(a
foreign
volume is a volume that does not
contain a standard file
structure
understood
by any of the VAX/VMS
software)

Figure 1-3 shows the relationship of physical,
I/O to the driver.

1-10

logical,

and

virtual

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

OIO
RE OU EST

YES

TRANSLATE LOGICAL
BLOCK ADDRESS
TO PHYSICAL
BLOCK ADDRESS

YES

MAP VIRTUAL BLOCK
ADDRESS TO LOGICAL
BLOCK ADDRESS
error

1/0
DRIVER

YES

GOTO
ACP

*Needed to map virtual address to logical address
WAKE ACPTO
CHANGE MAPPING
WINDOW

Figure 1-3

Physical, Logical, and Virtual I/O

1-11

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
1.7

I/O FUNCTION ENCODING

I/O functions fall into three groups that correspond to the three I/O
device addressing modes (physical, logical, and virtual) described in
Section 1.6. Depending on the device to which it is directed, an I/O
function can be expressed in one, two, or all three modes.
I/O functions are described by 16-bit, symbolically-expressed values
that specify the particular I/O operation to be performed and any
optional function modifiers. Figure 1-4 shows the format of the
16-bit function value.
15

function mod-if-ie-rs_ ___._l_ _ _
co_d_e_ _

Figure 1-4

I/O Function Format

Symbolic names for I/O function codes are defined by the $IODEF macro,
as described in the VAX/VMS System Services Reference Manual.

1.7.1

Function Codes

The low-order 6 bits of the function value are a code that specifies
the particular operation to be performed. For example, the code for
read logical block is expressed as IO$ READLBLK. Table 1-1 lists the
symbolic values for read and write I/O-functions in the three transfer
modes.
Table 1-1
Read and Write I/O Functions
Physical I/O

Logical I/O

Virtual I/O

··-

IO$ READPBLK
IO$-WRITEPBLK

IO$ READLBLK
IO$-WRITELBLK

IOS READVBLK
IO$-WRITEVBLK
..... _,p

The set mode I/O function has a symbolic value of IOS_SETMODE.
Function codes are defined for all supported devices.
Although some
of the function codes (for example, IOS READVBLK and IOS WRITEVBLK)
are used with several types of devices, most are device -dependent;
that is, they perform functions specific to particular types of
devices. For example, IO$ CREATE is a device-dependent function code;
it is used only with file-structured devices such as disks and
magnetic tapes. Chapters 2 through 8 and 10 through 12 provide
complete descriptions of the functions and function codes.

1.7.2

Function Modifiers

The high-order 10 bits of the function value are function modifiers.
These are individual bits that alter the basic operation to be
performed. For example, the function modifier IOSM NOECHO can be
specified with the function 10$ READLBLK to a termTnal. When used

1-12

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

together, the two values are written as IO$ READLBLK!IO$M NOECHO.
This means that data typed at the terminal keyboard is entered in the
user buffer but not echoed to the terminal.
Figure 1-5 shows the
format of function modifiers.

13 12·

device/function
independent

6 5
device/function
dependent

J]o
--t

Figure

1~5

Function Modifier Format

As shown, bits 13 through 15 are device/function independent bits, and
bits 6 through 12 are device/function dependent bits. Device/function
dependent bits have the same meaning, whenever possible, for different
device classes.
For example, the function modifier IOSM ACCESS is
used with both disk and magnetic tape devices to cause a file to be
accessed during a create operation. Device/function dependent bits
always have the same function within the same device class.
There
are
two
device/function
independent
modifier
bits:
IO$M INHRETRY
and
IO$M DATACHECK
(a
third bit is reserved).
IO$M-INHRETRY is u~ed to i~hibit all error recovery.
If any error
occurs,
and this modifier bit is specified, the operation is
immediately terminated and a failure status is returned in the I/O
status block (see Section 1.9.2). IO$M DATACHECK is used to compare
the data in memory with that on a disk or-magnetic tape.

1.8

ISSUING I/O REQUESTS

This section describes the entire process involved in issuing I/O
requests,
including:
assigning channels, allocating devices, and
issuing QIO requests; the $QIO, $QIOW, $INPUT, and $OUTPUT macros;
and, finally, status returns.

1.8.1

Channel Assignments

Before I/O requests can be made to a device, the user must assign a
channel to establish a link between the user process and the device.
A channel is a communication path associated with a device during
VAX/VMS I/O operations.
The process uses the channel to transfer
information to and from the device.
The Assign I/O Channel ($ASSIGN) system service is used to assign a
channel to a device. To code a call to the $ASSIGN system service,
the user must supply the name of the device (physical device name or
logical name) and the address of a ·word to receive the assigned
channel number.
The $ASSIGN system service returns the channel
number.
The process can then request an I/O operation by calling the
Queue I/O ($QIO) system service and specifying, as one of the
arguments, the channel number returned by the $ASSIGN system service.

1-13

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

In the following example, an I/O channel is assigned to the
TTB4. The channel number is returned in the word at TTCHAN •
TTNAME:
TTCHAN:

devi~e

;TERMINAL NAME DESCRIPTOR
;TERMINAL CHANNEL NUMBER

• ASCID / TTB4/
.BLKW 1-

$ASSIGN_S DEVNAM=TTNAME,CHAN=TTCHAN
If the first character in the device name
(devnam)
string is an
underline character
( ), the name is considered to be a physical
device name; otherwise: one level of logical name translation is
performed and the equivalence name, if any, is used.
The Create Mailbox and Assign Channel
($CREMBX)
system service
provides another way to assign a channel to a device. In this case,
the device is a mailbox. $CREMBX creates a mailbox and then assigns a
channel to it (see Section 7.1.1).
The QIO system service can be performed only on assigned I/O channels
and only from access modes that are equal to or more privileged than
the access mode from which the original channel assignment was made.

1.8.2

Device Allocation

A device can be allocated to a process (or subprocess) by the Allocate
Device ($ALLOC) system service. The allocated device is reserved for
the exclusive use of the requesting process, any subprocesses it
creates, and subprocesses created by any related subprocess. No other
process can allocate the device until the owning process explicitly
deallocates it.
Channels can be assigned to both allocated and nonallocated devices;
however, a process cannot assign a channel to a device that is
allocated to another process.
When a channel is assigned to a
nonallocated, nonshareable device (for example, a line printer or a
magnetic tape device) VAX/VMS implicitly allocates the device.
Access to device functions is controlled by physical and logical I/O
privileges, the volume protection mask, the device protection mask,
and the mountability of the device (a device is mountable if a MOUNT
command can be issued for it). Even though a device is allocated to a
process, the process cannot perform I/O operations on the device
unless access is allowed.

1.8.3

I/O Function Requests

After a channel has been assigned, the process can request I/O
functions by using the Queue I/O ($QIO) system service. The $QIO
system service initiates an input or output operation by queuing a
request to a specific device that is assigned to a channel.
Certain requirements must be met before a request is queued.
For
example, a valid channel number must be included in the request, the
request must not exceed relevant quotas, and sufficient dynamic memory
must be available to complete the operation. Failure to meet such
requirements is indicated by a status return (described below in
Section 1.8.8).

1-14

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

The number of pending I/O requests, the amount of buffer space, and
the number of outstanding ASTs that a process can have are controlled
by quotas.
Each I/O request causes an I/O request packet
system dynamic memory.
Additional memory
following circumstances:

to
is

•

The I/O request function is an ACP function

•

The target device is a buffered I/O device

•

The target device is a network I/O device

be allocated from
allocated under the

After an I/O request is queued, the system does not require the
issuing process to wait for the I/O operation to complete. If the
process that issued the QIO request cannot proceed until the I/O
completes, an event flag can be used to synchronize I/O completion
(see Sections 1.8.6.1 and 1.9.1). In this case, the process should
request the Wait for Single Event Flag ($WAITFR) system service at the
point where synchronization must occur: that is, where I/O completion
is required.
$WAITFR specifies an event flag for which the process is to wait.
(The $WAITFR event flag must have the same number as the event flag
used in the QIO request.) The process then waits while the I/O
operation is performed. On I/O completion, the event flag is set and
the process is allowed to resume operation.
Other ways to achieve this synchronization include the use of the
$QIOW system service and ASTs, described in Sections 1.8.5 and 1.9.3,
respectively. In addition, the I/O status block can be specified and
checked if the user wants to determine whether the I/O operation
completed without an error, regardless of whether or not the process
waits for I/O completion (see Section 1.9.2.)
The QIO system service is accompanied by up to
six
device/
function-independent
and six device/function-dependent arguments.
Section 1.8.6 below describes device/function-independent arguments.
The
device/function-dependent
arguments
(Pl
through
Pn)
are
potentially different for each device/function combination.
However,
similar functions that are performed by all devices have identical
arguments •. Furthermore, all functions performed by a particular class
of device are identical.
Device/function-dependent arguments are
described in more detail for the individual devices in Chapters 2
through 8 and 10 through 12.

1.8.4

$QIO Macro Format

The general format
arguments, is:
$QIO_S

for

the

$QIO

macro,

using

position-dependent

[efn] ,chan,func, [iosb], [astadr], [astprm] ,[pl], [p2], [p3J, [p4], [p5], [pn]

The first six arguments are device/function independent.
If keyword
arguments are used, they can be written in any order. Arguments Pl
through P6 are device/function dependent. The chan and func arguments
must be specified in each request; arguments enclosed in brackets
( []) are optional.

1-15

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
The following example illustrates a typical QIO request using
arguments:
$QIO_S

1.8.5

EFN=U ,CHAN=TTCHANl ,FUNC=#IO$ WRITEVBLK,Pl=BUFADD-;P2=#BUFSIZE

keyword

;EVENT FLAG 1
;CHANNEL
;VIRTUAL WRITE
;BUFFER ADDRESS
;BUFFER SIZE

$QIOW Macro Format

The Queue I/O Request and Wait For Event Flag ($QIOW)
system service
macro combines the $QIO and $WAITFR system services. It eliminates
any need for explicit I/O synchronization by automatically waiting
until the I/O operation is completed before returning control to the
process. Thus, $QIOW provides a simpler way to synchronize the return
to the originating process when the process cannot proceed until the
I/O operation is completed.
The $QIOW macro has the same device/function
independent
device/function dependent arguments as the $QIO macro:
$QIOW_S

1.8.6

and

[efn] ,chan,func, [iosb], [astadr], [astprm] ,[pl], [p2J, [p3J, [p4J, [p5J, [pnl

$QIO and $QIOW Arguments

Table 1-2 lists the $QIO and $QIOW
device/function-independent
arguments and their meanings. Additional information is provided in
the paragraphs following the table and in the VAX/VMS System Services
Reference Manual.
Table 1-2
Device/Function-Independent Arguments
Argument

Meaning

efn {event
flag number)

The number of the event flag that is to be
cleared when the I/O function is queued and set
when it is completed. This argument is optional
in the macro form;
if not specified,
efn
defaults to O.

chan {channel
number)

The number of the I/O channel to which the
request is directed.
The channel number is
obtained from either the $ASSIGN or $CREMBX
system service. This argument is mandatory in
the macro form.

func
The 16-bit function code and modifier value that
(function value) specifies the operation to be performed.
This
argument is mandatory in the macro form.
(continued on next page)

1-16

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
Table 1-2 (Cont.)
Device/Function-Independent Arguments
Argument

Meaning

iosb (I/O
status block)

The address of a quadword I/O status block to
receive the final I/O status.
This argument
is
optional in the macro form.

astadr (AST
address)

The entry point address of an AST routine to be
asynchronously executed when the
I/O completes.
This argument is optional in the macro form.

astprm (AST
parameter)

The 32-bit value to be passed to the AST routine
as an argument when the I/O completes.
It can be
used to assist the
routine in identifying the
particular AST.
This argument is optional in the
macro form.

1.8.6.1 Event Flag Number Argument - The event
flag number
(efn)
argument is the number of the event flag to be associated with the I/O
operation.
It is optional in a $QIO or $QIOW macro.
The specified
event
flag is cleared when the request is issued and set when the I/O
operation completes.
The specified event flag
is also set
if the
service terminates without queuing the I/O request.
If the process
requested the $QIOW system service,
execution
is
automatically suspended until
the
I/O completes.
If the process
requested the QIO system service (with no subsequent $WAITFR,
SWFLOR,
or $WFLAND macro),
process execution proceeds in parallel with the
I/O.
As the process continues to execute, it can test the event flag
at any point by using the Read Event Flags ($READEF) system service.
Event flag numbers must be in the range of 0 through 127
(however,
event flags
24
through 31
are
reserved for
system use).
If no
specific event flag is desired, the efn argument can be omitted from
the macro.
In that case, efn defaults to O.
Users should exercise care
in the use of SQIOs and $QIOWs,
for
example,
when a $QIOW is used for terminal input and a $QIO is used
for terminal output.
If no event flag is specified
in either call,
event
flag
0
is set at the completion of the output $QIO and the
waiting input SQIOW will prematurely return control to the process.

Channel Number Argument - The channel number (chan) argument
represents the channel number of the physical device to be accessed by
the I/O request.
It is required for all $QIO and SQIOW requests.
The
association between the physical device and the channel is specific to
the process issuing the I/O request.
The channel number
is obtained
from the $ASSIGN or $CREMBX system service (as described above in
Section 1.8.1).

1.8.~.2

1.8.6.3 Function Argument - The function (func) argument defines the
logical,
virtual,
or physical I/O operation to be performed when the
$QIO or $QIOW system service is requested.
It is required for all QIO
and QIOW requests.
The argument consists of a 16-bit function code

1-17

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
and function modifier.
Up to 64
function codes can be defined.
Function codes are defined for all supported device types;
most of
the codes are device dependent.
The function arguments for each I/O
driver are described in more detail in Chapters 2 through 8 and 10
through 12.

1.8.6.• 4 I/O Status Block Argument - The I/O status block
(iosb)
argument specifies the address of the I/O status block to be
associated with the I/O request.
It is optional in the QIO and QIOW
macros.
If omitted,
the
iosb value is O which indicates no iosb
address is supplied. This block is a quadword that receives the final
completion status of the I/O request.
Section 1.9.2 describes the I/O
status block in more detail.

1.8.6.5 AST Address Argument - The AST address
(astadr)
argument
specifies the entry point address of an AST routine to be executed
when the I/O operation is complete.
If omitted, the astadr value is 0
which
indicates no astadr address
is supplied.
This argument is
optional and can be used to interrupt a process to execute special
code at I/O completion.
When the I/O operation completes, the AST
service routine is CALLed at the address specified
in the astadr
argument.
The AST service routine is then executed in the access mode
from which the QIO service was called.

1.8.6.6 AST Parameter Argument - The AST parameter (astprm)
argument
is an optional,
32-bit arbitrary value that is passed to the AST
service routine when I/O completes,
to assist the routine
in
identifying the particular AST.
A typical use of the astprm argument
might be the address of a user control block.
If omitted, the astprm
value is O.

1.8.6.7 Device/Function-Dependent Arguments - Up
to
six
device/
function-dependent arguments
(Pl through P6) can be included in each
QIO request.
The arguments for terminal read function codes show a
typical use of Pl through P6:
Pl

buff er address

buffer size

timeout count (for read with timeout)

read terminator descriptor block address

prompt string buffer address

prompt string buffer size

Pl is always treated as an address.
Therefore, in the S form of the
macro,
Pl
always generates a PUSHAL instruction.
P2-through P6 are
always treated as values.
In the
S form of the macro,
these
arguments always generate PUSHL instructions.

1-18

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
Inclusion of the device/function-dependent arguments in a QIO request
depends on the physical device unit and the function specified. A
user who wants to specify only a channel, an I/O function code, and an
address for AST routine might issue the following:
$QIO_S

CHAN=XYCHAN,FUNC=#IO$ READVBLK,ASTADR=XYAST,Pl=BUFADR,P2=#BUFLEN

In this example, XYCHAN is the address of the word containing the
channel to which the request is directed;
IO$ READVBLK is the
function code; and XYAST is the AST entry point address. BUFADR and
BUFLEN are the device/function-dependent arguments for an input
buffer.
,

$INPUT and $OUTPUT Macro Format and Arguments

1.8.7

The $INPUT and $OUTPUT macros simplify the use of the $QIOW macro.
These macros generate code to perform virtual operations, using the
IO$ READVBLK and IO$ WRITEVBLK function codes (the function code is
automatically specified in the request), and wait for I/O completion.
The macro formats and arguments are:
$INPUT
$OUTPUT

chan,length,buffer, [iosb], [efn]
chan,length,buffer, [iosb], [efn]

Table 1-3 lists the $INPUT and $OUTPUT arguments and their meanings.
Table 1-3
$INPUT and $OUTPUT Arguments
Argument

Meaning

length

The length of the input or output buffer.

buff er

The address of the input or output buffer.

iosb

The address of the quadword that receives
completion
status
of the I/O operation.
argument is optional.

ef n

The number of the event flag for which the process
if not specified,
waits. This argument is optional;
efn defaults to 0.

I/O

The channel on which
performed.

the

operation

ch an

the
This

Both the iosb and efn arguments are optional;
all other arguments
must be included in each macro. Note that the order of the length and
buffer arguments is opposite that of the $QIO and $QIOW Pl and P2
arguments.
Also note that $INPUT and $OUTPUT do not have the astadr
and astprm arguments; neither of these operations can conclude in an
AST.

1-19

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

Status Returns for System Services

1.8.8

On completion of a system service call, the completion status is
returned as a longword value in register RO, shown in Figure 1-n.
(System services save the data in all registers except RO and Rl.)

c--31

RO:

-· J------=atus
16 15

--~-----

Figure 1-6

System Service Status Return

Completion status is indicated by a value in bits 0 through 15.
low-order 3 bits are encoded with the error severity level;
successful returns have an odd value:

The
all

warning
success
2
error
3
informational (nonstandard) success
4
severe error
5-7 = reserved
0

Each numeric status code has a symbolic name in the form SS$ code.
For
example,
the return might be SS$ NORMAL, which indTcates
successful completion of the system service. There are several error
conditions that can be returned. For example, SS$ IVCHAN indicates
that an invalid channel number was specified in an I/O request.
The VAX/VMS System Services Reference Manual describes the possible
returns for each system servTce. Table 1-4 lists the valid status
returns for the $QIO, $QIOW, $INPUT, and $OUTPUT system service
requests.
Status returns for system services are not the same as the I/O status
returns described in Chapters 2 through 8 and 10 through 12 for the
various I/O drivers (see Section 1.9). A system service status return
is the status of the $QIO, $QIOW, $INPUT, $OUTPUT, or other system
service call after completion of the service, that is, after the
system returns control to the user. A system service status return
does not reflect the completion (successful or unsuccessful) of the
requested I/O operation.
For example, a $QIO system service read
request to a terminal might be successful
(status
return
is
SS$ NORMAL)
but fail because of a device parity error (I/O status
return is SS$ PARITY). System service error status return codes refer
only to failures to invoke the service.
An I/O status return is the status at the completion of the I/O
operation.
It is returned in the quadword I/O status block (IOSB).
Although some of the symbolic names (for example, SS$ NORMAL and
SS$ ACCVIO) can be used in both types of status returns, they have
different meanings.

1-20

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
Table 1-4
$QIO, $QIOW, $INPUT, and $OUTPUT System Services Status Returns
Status

Meaning

SS$ NORMAL

The $QIO, $QIOW, $INPUT, or $OUTPUT request was
successfully completed;
that is, an I/O request
was placed in the appropriate device queue.

SS$ ACCVIO

The IOSB, the specified buffer, or the
list cannot be accessed by the caller.

SS$_EXQUOTA

The buffer quota, buffered I/O quota, or direct
I/O quota was exceeded and the process has
disabled resource wait mode with
the $SETRWM
system service.
(The $SETRWM system service is
described in Section 1.4.) SS$ EXQUOTA is also
set if the AST quota was exceeded.

SS$ ILLEFC

An illegal event flag number was specified.

SS$ INSFMEM

Insufficient dynamic memory is available
to
complete
the
service and the process has
disabled resource wait mode with
the $SETRWM
system service.
(The $SETRWM system service is
described in Section 1.4.)

SS$ IVCHAN

An invalid channel number was specified;
that
is,
a channel number larger than the number of
channels available.

SS$ NOPRIV

The specified channel was assigned from a more
is not
privileged access mode,
the channel
assigned, or the user does not have
the proper
privilege to access the device.

SS$ UNASEFC

A common event flag
in an
flag cluster was specified.

SS$ ABORT

A network logical link was broken.

SS$ INSFARG

Not enough
service.

SS$ ILLSER

An invalid system service was called.

1.9

arguments

argument

unassociated

were

supplied

event

the

I/O COMPLETION

Whether an I/O request completed successfully or unsuccessfully can be
denoted by one or more return conditions.
The selection of the return
conditions depends on the arguments included in the QIO macro call.
The three primary returns are:
•

Event flag - an event flag is set
operation.

•

I/O status block - if the iosb argument was specified
in the
QIO macro call,
a code
identifying the type of success or
failure is returned in bits 0 through 15 of a quadword
I/O
status block on completion of the I/O operation.
The location
of this block is indicated by the user-supplied iosb argument.

1-21

completion

I/O

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

•

1.9.1

Asynchronous system trap - if an AST address argument was
specified in the I/O request, a call to the AST service
routine occurs, at the address indicated, on completion of the
I/O operation.
(The I/O status block, if specified in the I/O
request, is updated prior to the AST call.)

Event Flags

Event flags are status posting bits used by the $QIO, $QIOW, $INPUT,
and $OUTPUT system services to indicate the completion or occurrence
of an event. The system service clears the event flag when the
operation is queued and sets it when the operation is completed.
Event flag services allow users to set or clear certain flags,
test
the current status of flags, or place a program in a wait state
pending the setting of a flag or group of flags.
See the VAX/VMS System Services Reference Manual for more
on event flags and their use.-

1.9.2

information

I/O Status Block

The completion status of an I/0 request is returned in the first
of the I/O status block (IOSB), as shown in Figure 1-7.
31

-------------

1-- -------------

16 15

transfer count

word

status

------------

------ - - device-dependent data
'------------~----~

Figure 1-7

··-·--·------------------'

........-...

I/O Status Block Format

The IOSB indicates whether the operation was successfully completed,
the amount of data transferred, and additional device-dependent
information such as the number of lines printed.
The status return
code has the same format and bit significance (bit O set indicates
success; bit 0 clear indicates error) as the system service status
code
(see Section 1.8.8).
For example, if the process attempts to
access a nonexistent disk, a status code of SS$ NONEXDRV is returned
in the I/O status block. The status returns-for the individual I/O
drivers are listed in Chapters 2 through 8 and 10 through 12.
The upper half of the first IOSB longword contains the transfer count
on completion of the I/O operation if the operation involved the
transfer of data to or from a user buffer. For example, if a read
operation is performed on a terminal, the number of bytes typed before
a carriage return is indicated here. If a magnetic tape unit is the
device and a read function is specified, the transfer count represents
the number of bytes actually transferred. The second longword of the
IOSB
can
contain
certain
device-dependent information.
This
information is supplied in more detail for each I/O driver in Chapters
2 through 8 and 10 through 12.

1-22

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
The status can be tested symbolically, by name.
For example, the
SS$ NORMAL
status
is returned if the operation was completed
successfully. The following example illustrates the examination of
the I/O status block XYIOSB to determine if an error occurred:
$QIO_S

CHAN=XYCHAN,FUNC=#IO$ WRITEVBLK,-

BLBC

RO,REQERR

;CHECK SYSTEM SERVICE
;STATUS CODE

CMPW

#SS$_NORMAL,XYIOSB

;CHECK I/O STATUS
;CODE

BNEQ

ERROR

IOSB=XYIOSB,Pl=BUFADR~P2=#BUFLEN

The status block can be omitted from a QIO request if the user wishes
to assume successful completion of the request and does not want to
know how many bytes were transferred.
If specified, the IOSB is
cleared when the QIO request is issued and then filled with the final
status at I/O completion.

1.9.3

Asynchronous System Traps

As an option, an AST routine can be specified in the QIO request if
the user wants to interrupt the normal execution of a process to
execute special code on completion of the request.
Even if the
process is blocked for a $WAITFR or $QIOW, it will be interrupted.
When the I/O operation completes, a CALL instruction is used to
transfer control to the AST service routine at the entry point address
specified in the QIO astadr argument. The address must be the address
of an entry mask.
The AST service routine is then executed at the
access mode from which the QIO request was issued. Figure 1-8 shows
the argument list for the CALL instruction.
5
astprm
RO
R1
PC
PSL

Figure 1-8

CALL Instruction Argument List

Using an AST to signal I/O completion allows the process to be
occupied with other functions during the I/O operation. The process
need not wait until some event occurs before proceeding to another
operation.
See the VAX/VMS System Services Reference
information on ASTs and their use.

1-23

Manual

for

detailed

INTRODUCTION TO VAX/VMS INPUT/OUTPUT
1.10

DEVrCE INFORMATION

Two system services can be used to obtain information about devices:
Get Channel Information ($GETCHN) and Get Device Information ($GETDEV)
system services. The information obtained includes such categories as
device characteristics, device type, error count, and operation count.
The Get Channel Information (SGETCHN) system service is used to obtain
information about a device to which an I/O channel is assigned. The
$GETCHN system service can be performed only on assigned channels and
only from access modes that are equal to, or more privileged than, the
access mode from which the original channel assignment was made.
The Get Device Information ($GETDEV) system service is used to
information about any device.

obtain

$GETCHN and $GETDEV return both primary and
secondary
device
characteristics.
Usually,
these characteristics are identical.
However, they can differ in three instances:
1.

If the
device
is
a
spooled
device,
the
primary
characteristics are those of the intermediate device and the
secondary characteristics are those of the spooled device.
See the VAX/VMS System Manager '_s Guide for information on
spooling.

If the device represents a logical link on a network, the
secondary characteristics contain information about the link.

If the device has an associated mailbox, the
primary
characteristics are those of the device and the secondary
characteristics are those of the mailbox.

The macro format for a $GETCHN request is:
$GETCHN chan, [prilen], [pribuf], [scdlen], [scdbuf]
The macro format for a $GETDEV request is:
$GETDEV devnam, [prilen], [pribuf], [scdlen], [scdbuf]
Table 1-5 lists the $GETCHN and $GETDEV arguments and their meanings.
Table 1-5
$GETCHN and $GETDEV Arguments
Argument

Meaning
---·----··••m•··-~-

· · - - - - - - -----------~

ch an

The number of the I/O channel to which a $GETCHN
request is directed (this is not an argument for
$GETDEV) •

devnam

The address of a string descriptor for the name of
the device to which $GETDEV is directed (this is
not an argument for SGETCHN).

prilen

The address of the word to receive the length
the primary characteristics.
This argument
optional.

of
is

(continued on next page)

1-24

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

Table 1-5 (Cont.)
$GETCHN and $GETDEV Arguments
Meaning

Argument
pribuf

The address of the buffer descriptor for the buffer
that
is
to
receive
the
primary
device
characteristics. An address of 0 indicates that no
buffer is specified. This argument is optional.

scdlen

The address of the word to receive the length of
This argument is
the secondary characteristics.
optional.

scdbuf

The address of the buffer descriptor for the buffer
that
is
to
receive
the
secondary
device
characteristics. An address of 0 indicates that no
buffer is specified. This argument is optional.

Figure 1-9 shows the format of the device information returned in
primary and secondary buffers.
device characteristics

buffer size

type

class

device dependent information
offset to
device name

unit number

owner process Pl D

DIB$K_LENGTH

owner process U IC

error count

volume protection
mask

operation count
offset to
volume label

disk size in blocks

Figure 1-9

Buffer Format for SGETCHN and $GETDEV System Services

1-25

the

INTRODUCTION TO VAX/VMS INPUT/OUTPUT

In Figure 1-9, offsets are the displacement from the beginning of the
buffer to the specified field. Missing fields are denoted by offsets
of O. Both device name and volume label are stored in the buffer as
counted strings.
They must be located through the use of their
respective offset values. Symbolic offsets for all fields are defined
by the $DIBDEF macro. If both a volume label and a device name are
returned, the buffer has a length of n4 bytes.
As much information as possible is returned for each of the primary
and secondary characteristics. If all the information does not fit in
the specified buffers, an appropriate status value is returned. Table
1-6 lists the status return values for the $GETCHN and $GETDEV system
services.
Table 1-fi
$GETCHN and $GETDEV Status Returns
Status

Meaning

SS$ NORMAL

The
$GETCHN
or
$GETDEV
successfully completed.

SS$ ACCVIO

The caller cannot read a buffer descriptor,
write a buffer, or access the argument list.

S~$

IVCHAN

An invalid channel number was specified in the
$GETCHN request, that is, a channel number
larger than the number of channels available;
the channel is nonexistent.

SS$ NOPRIV

The caller does not have the privilege to access
the
specified
channel
or the channel is
unassigned.

SS$ BUFFEROVF

The
$GETCHN
or
$GETDEV
system
service
successfully completed. The device information
returned overflowed the buffer(s) provided and
has been truncated.

i-20

system

service

CHAPTER 2
TERMINAL DRIVER

This chapter describes the use of the VAX/VMS terminal driver.
This
driver supports the DZ-11 Asynchronous Serial Line Multiplexer and the
console terminal.

2.1

SUPPORTED TERMINAL DEVICES

Each DZ-11 multiplexer interfaces 8 or l~ asynchronous
serial
communication lines for use with terminals. It supports programmable
baud rates; however, input and output speeds must he the same.
VAX/VMS supports the DZ-11 internal modem control.
The system console terminal
special purpose interface.

attached

the

The Remote (DECnet) Command Terminal also makes use
and capabilities listed in Section 2.2.

2.2

processor

with

features

the

TERMINAL DRIVER FEATURES AND CAPABILITIES

The VAX/VMS terminal driver provides the following capabilities:
•

Type-ahead

•

Specifiable or default line terminators

•

Special operating modes, such as NOECHO and PASSALL

•

American National Standard escape sequence detection

•

Terminal/mailbox interaction

•

Terminal control characters and special keys

•

Dial-up

•

Optional parity specification

•

Limited full-duplex operation (simultaneously active read
write requests)

2-1

and

TERMINAL DRIVER

2.2.1

Type-ahead

Input (data received) from a VAX/VMS terminal is always independent of
concurrent output (data sent)
to a terminal. This capability is
called type-ahead. Type-ahead is allowed on all terminals unless
explicitly disabled by the Set Mode characteristic, inhibit type-ahead
(TT$M_NOTYPEAHD; see Section 2.4.3).
Data typed at the terminal is retained in the type-ahead buffer until
the user program issues an I/O request for a read operation. At that
time, the data is transferred to the program buffer and echoed at the
terminal where it was typed.
Def erring the echo until the read operation is active allows the user
process to specify function code modifiers that modify the read
operation.
These modifiers can include,
for
example,
noecho
(IO$M NOECHO)
and
convert
lowercase
characters
to uppercase
(IO$M=CVTLOW) (see Section 2.4.1.1).
If a read operation is already in progress when the data is
the terminal, the data transfer and echo are immediate.

typed

The action of the driver when the type-ahead buffer fills depends on
the Set Mode characteristic TT$M HOSTSYNC (see Section 2.4.3). If
TT$M HOSTSYNC is not set, CTRL/G (BELL) is returned to inform the user
that- the type-ahead buffer is full.
If TT$M HOSTSYNC is set, the
driver stops input by sending a CTRL/S and the terminal responds by
sending no more characters.
These warning operations are begun 8
characters before the type-ahead buffer fills.
The driver sends a
CTRL/Q to restart transmission when the type-ahead buffer empties
completely.
The type-ahead buffer length is variable, with possible values in the
range from 0 through 32,7n7. The length can be set on a system-wide
basis through use of the system generation parameter TTY TYPAHDSZ.

2.2.2

Line Terminators

A line terminator is the control sequence that the user types at the
terminal to indicate the end of an input line. Optionally, the user
process can specify a particular line terminator or class
of
terminators for read operations.
Terminators are specified by an argument to the QIO request for a read
operation. By default, they can be any ASCII control character except
FF, VT, LF, TAB, or BS. If included in the request, the argument is a
user-selected group of characters (see Section 2.4.1.2).
All characters are 7-bit ASCII characters unless data is input on an
8-bit terminal (see Section 2.4.1).
(The characteristic TT$M EIGHTBIT
determines whether a terminal uses the 7-bit or 8-bit character set;
see Table 2-4.) All input characters are tested against the selected
terminator(s). The input is terminated when a match occurs or the
user's input buffer fills.

2.2.3

Special Operating Modes

The VAX/VMS terminal driver supports many special operating modes for
terminal lines.
Section 2.4.3 lists these modes. All special modes
are enabled or disabled by the Set Mode and Set Characteristics QIOs.

2-2

TERMINAL DRIVER
2.2.4

Escape Sequences

Escape sequences are strings of two or more characters, beginning with
the escape character
(decimal 27 or hexadecimal lB), that indicate
that control information follows. Many terminals send and respond to
such escape sequences to request special character sets or to indicate
the position of a cursor.
The Set Mode characteristic TT$M ESCAPE (see Section 2.4.3) is used to
specify
that VAX/VMS terminal lines can generate valid escape
sequences.
If this characteristic is set, the terminal driver
verifies the syntax of the escape sequences. The sequence is always
considered a read function terminator and is returned in the read
buffer, that is, a read buffer can contain other characters that are
not part of an escape sequence, but a complete escape sequence always
terminates a read. The return information in the read buffer and the
I/O status block includes the position and size of the terminating
escape sequence in the data record (see Section 2.5).
Any escape sequence received from a terminal is checked for correct
syntax.
If the syntax is not correct, SS$ BADESCAPE is returned as
the status of the I/O. If the escape sequence does not fit in the
user buffer, SS$ PARTESCAPE is returned. The remaining characters are
transmitted on the next read.
No syntax integrity is guaranteed
across read operations.
Escape sequences are never echoed. Valid
escape sequences are any of the following
forms
(hexadecimal
notation):
ESC <int> ••• <int> <fin>
where:
ESC

is pressing the ESC key, a byte (character) of lB

<int>

is an "intermediate character" in the range of 20 to 2F.
This
range
includes
the character "space" and 15
punctuation marks. An escape sequence can contain any
number of intermediate characters, or none.

<fin>

is a "final character" in the range of 30 to 7E.
This
range includes uppercase and lowercase letters, numbers,
and 13 punctuation marks.

There are four additional escape sequence forms:
ESC
ESC
ESC
ESC

<;>
<?>
<O>
<Y>

<20-2F> ••• <30-7E>
<20-2F> ••• <30-7E>
<20-2F> ••• <40-7E>
<20-7E> ••• <20-7E>

For example, when the IDENTIFY escape sequence, escape z, is sent to a
VT-55 terminal, the response from the terminal is ESC <C>.
(Escape
sequences are neither displayed nor echoed on the terminal.)

2-3

TERMINAL DRIVER

standard, are escape
Control sequences have

Control sequences, as defined by the ANSI
sequences which include control parameters.
the following format:
ESC [ <par> ••• <par> <int> ••• <int> <fin>
where:
ESC

is pressing the ESC key
denotes a control sequence

<par>

is a parameter specifier in the range of 30 to 3F

<int>

is an "intermediate
sequences

<fin>

is a "final character" in the range of 40 to 7E

character",

defined

for

escape

desired

column

For example, the position cursor control sequence is:
ESC [ Pl ;

Pc H

where Pl is the desired line position and Pc
position.

the

The VTlOO User Guide lists valid escape sequences for VTlOO terminals.
Section 2.2.6 describes
sequences.

2.2.5

control

character

functions

during

escape

Terminal/Mailbox Interaction

Mailboxes are virtual I/O devices used for communication between
processes.
The terminal I/O driver can use a mailbox to communicate
with a user process. Chapter 7 describes the mailbox driver.
A user program can use the $ASSIGN system service to associate a
mailbox with one or more terminals.
The terminal driver sends
messages to this mailbox when terminal-related events occur that
require the attention of the user image.

Mailboxes used in this way carry status messages, not terminal data,
from the driver to the user program.
For example, when data is
received from a terminal for which no read request is outstanding
(unsolicited data), a message is sent to the associated mailbox to
indicate data availability.
On rece1v1ng this message, the user
program must read the channel assigned to the terminal to obtain the
data. Messages are sent to mailboxes under the following conditions:
•

Unsolicited data in the type-ahead buffer.
The use of the
associated
mailbox
can
be enabled and disabled as a
subfunction of the read and write requests (see Sections 2.4.1
and 2.4.2). Thus, the user process can enter into a dialogue
with the terminal after an unsolicited data message arrives.
Then, after the dialogue is over, the user process can
reenable the unsolicited data message function on the last I/O
exchange.
The default on all terminals is enabled. Only one
message is sent between read operations.

2-4

TERMINAL DRIVER
•

Terminal hang-up. Hang-up occurs when a remote line loses the
carrier signal;
a message is sent to the mailbox. When
hang-up occurs on lines that
have
the
characteristic
TT$M_REMOTE set, the line returns to local mode.

Messages placed in the mailbox have the following content and format:
•

Message type. The codes MSG$ TRMUNSOLIC (unsolicited data)
and MSG$ TRMHANGUP
(hang-up)
identify the type of message.
Message types are identified by the $MSGDEF macro.

•

Device unit number to identify
message.

•

Counted string to specify the device name.

•

Controller name

the

terminal

that

sent

the

Figure 2-1 illustrates this format.
31

16 15
unit number

8 7

message type

controller name*

counted string

*does not include the colon(:) character

Figure 2-1

Terminal Mailbox Message Format

Interaction with a mailbox associated with a terminal occurs through
standard QIO functions and ASTs. Therefore, the process need not have
outstanding read requests to an interactive terminal to respond to the
arrival of unsolicited data. The process need only respond when the
mailbox signals the availability of unsolicited data.
Section 2.n
contains an example of mailbox programming.
The ratio of terminals to mailboxes is not always one to one.
One
user process can have many terminals associated with a single mailbox.

2.2.6

Control Characters and Special Keys

A control character is a character that controls action at the
terminal rather than passing data to a process. An ASCII control
character has a code between O and 31, plus 12n and 127 (hexadecimal 0
through lF, plus 7E and 7F), that is, all normal characters plus
DELETE and ALTMODE. Some control characters are typed at the terminal
by simultaneously pressing the CTRL key and a character key, that is,
CTRL/x. Other control characters, for example, RETURN, LINE FEED, and
ESCAPE, are typed by pressing a single key, that is, RET, LF, and ESC.
Table 2-1 lists the VAX/VMS terminal control characters (none of these
characters is interpreted in the PASSALL mode). Table 2-2 lists
special terminal keys.

2-5

TERMINAL DRIVER

Table 2-1
Terminal Control Characters
Control
Character

Meaning

CTRL/C

Gains the attention of the enabling process if the
user program has enabled a CTRL/C AST. If a CTRL/C
AST is not enabled, CTRL/C is converted to CTRL/Y
(see Section 2.4.3).
If echo is not disabled, the terminal performs a
newline (carriage return followed by a line feed),
types AC, and performs another newline.
Additional consequences of CTRL/C are:
•

The type-ahead buffer is flushed.

•

CTRL/S and CTRL/O are reset.

•

The current I/O operation (if any) is successfully
completed.
The status return is SS$ CONTROLC, or
SS$_CONTROLY if CTRL/C is converted to CTRL/Y.

TAB
(CTRL/I)

Tabs horizontally. Advances to the next tab stop on
terminals with the characteristic TT$M MECHTAB, but
the driver assumes tab stops on MODULO 8, that is,
multiples of 8, cursor positions.
On terminals
without this characteristic, enough spaces are output
to move the cursor to the next MODULO (8) position.

LF
(CTRL/J)

Performs line feed;
set.

Terminal performs a vertical tab.

filled if TT$M LFFILL is

(CTRL/K)
FF
(CTRL/L)

Performs form feed. Advances to the top of the page
on terminals with the characteristic TT$M MECHFORM.
On terminals without this characteristic, the driver
sends enough LF (filled) to move the paper to the top
of form position described by the length of the page
and the current position of the page.
The driver
then sends a carriage return to position the cursor
at the left margin.
The
Set
Mode
or
Set
Characteristics functions can be used to set page
length (see Section 2.4.3).

CTRL/O

Discards output. Action is immediate. All output is
discarded until the next read operation, the next
write operation with a IO$M CANCTRLO modifier, or the
receipt of the next CTRL/0.- If echo is not disabled,
the terminal echoes Ao, followed by a newline.
The
current write operation (if any) and write operations
performed while CTRL/O is in effect are completed
with a status return of SS$ CONTROLO.
CTRL/O, which reenables output,
CTRL/C and CTRL/Y cancel CTRL/O •

cancels

CTRL/S.

_______ ___ _______________________ -·-------··-----

...__

__.__

(continued on next page)

2-6

TERMINAL DRIVER

Table 2-1 (Cont.)
Terminal Control Characters
Control
Character
CTRL/Q

Meaning
Controls data flow;
used by terminals and the
driver. Restarts data flow to and from a terminal if
previously stopped by CTRL/S.
The action occurs
immediately with no echo.
CTRL/Q is also used to
solicit read operations.
CTRL/Q is meaningless if the line does not have the
characteristic
TT$M TTSYNC,
the
characteristic
TT$M HOSTSYNC, the characteristic TT$M READSYNC, or
is not currently stopped by CTRL/S.
-

CTRL/R

Displays current input. When CTRL/R is typed during
a read operation, a newline is echoed, and the
current contents of the input buffer is displayed.
If the current operation is a read with prompt
(IO$ READPROMPT) operation, the current prompt string
is also displayed.
CTRL/R has no effect if the
characteristic TT$M NOECHO is set.

CTRL/S

Controls data flow;
used by both terminals and the
driver.
CTRL/S stops all data flow;
the action
occurs immediat~ly with no echo. CTRL/S is also used
to stop read operations. CTRL/S is meaningful only
if the terminal has the TTSM TTSYNC, TT$M HOSTSYNC,
or TT$M READSYNC characteristTc.
-

CTRL/U

Purges current input data.
When CTRL/U is typed
before the end of a read operation, the current input
is flushed.
If echo is not disabled, the terminal
echoes ~U, followed by a newline. The prompt string
is displayed again if the current operation is a read
with prompt (IO$ READPROMPT). CTRL/U has no effect
on type-ahead buffer operations.

CTRL/X

Purges the type-ahead buff er and performs a CTRL/U
operation. Action is immediate. If a read operation
is in progress, the terminal echoes ~u, followed by a
newline.

CTRL/Y

CTRL/Y is a special interrupt or attention character
that is used to gain the attention of the command
interpreter for a logged-in process. CTRL/Y can be
enabled with an IO$M CTRLYAST function modifier to a
IO$ SETCHAR or IO$ SETMODE QIO. Physical or logical
I/0- privilege, or an access mode greater than that
held by the user, is required to enable CTRL/Y ASTs.
The command interpreter's CTRL/Y AST handler always
has precedence over a user program's CTRL/Y AST
handler.
(continued on next page)

2-7

TERMINAL DRIVER
Table 2-1 (Cont.}
Terminal Control Characters
Control
Character
CTRL/Y
(Cont.}

Meaning
Typing CTRL/Y results in an AST to an enabled process
process to signify that the user typed CTRL/Y.
The
terminal performs a newline, types AY, and performs
another newline if the AST and echo are enabled.
CTRL/Y is ignored (and not echoed} if the process is
not enabled for the AST.
Additional consequences of CTRL/Y are:

CTRL/Z

•

The type-ahead buffer is flushed.

•

CTRL/S mode is reset.

•

The current I/O operation (if any} is successfully
completed with a 0 transfer count. The status
return is SS$ CONTROLY.

Echoes AZ when CTRL/Z is typed as a read terminator.
By convention, CTRL/Z constitutes end-of-file.

'--------~----'--·------·---··-

Table 2-2
Special Terminal Keys
Control
Character

Meaning

---------------------..

------------f

ALTMODE

(Decimal 12n or hexadecimal 7E} Converts to escape on
terminals
that
do
not
have
the
lowercase
characteristic TT$M LOWER set.

DEL
(DELETE}

(Decimal 127 or hexadecimal 7F} Removes last typed
character from input stream. DEL is ignored if there
are
currently
no input characters.
Hard copy
terminals echo the deleted character enclosed in
backslashes.
For example, if the character z is
deleted, \z\ is echoed (the second backslash is
echoed after the next non-DEL character is typed}.
CRT terminals echo DEL as a backspace followed by a
space and another backspace.

ESC
(ESCAPE}

If escape sequences are recognized (the Set Mode
characteristic TT$M ESCAPE is set}, pressing ESC
signals the beginnTng of an escape sequence. On
these terminals ESC is never echoed;
however, on
terminals that do not recognize escape sequences, ESC
is echoed as a dollar sign ($} if it was used as a
read terminator or as hexadecimal lB if it was not a
read terminator.

RET
(RETURN}

If used during a read (input} operation, RET echoes a
newline. All returns are filled on terminals with
TT$M_CRFILL specified.

__________ _. ________________ ______

,___

...

___ .

2-8

TERMINAL DRIVER
2.2.7

Dial-Up

VAX/VMS supports the DZ-11 internal modem control (for example, Bell
103A, Bell 113, or equivalent) in autoanswer, full duplex mode. The
terminal driver does not support half-duplex operations on modems such
as the Bell 202. Also not supported are modems that use circuit 108/l
(connect data set to line) in place of data terminal ready.
All
United States modems and most European modems use the data terminal
signal which is supported. The terminal characteristic TT$M REMOTE
designates the line as being remote to the local computer. The driver
automatically sets TT$M REMOTE if the carrier signal changes from off
to on.
Dial-up lines are monitored periodically to detect a change in the
modem carrier signal.
The system generation parameter TTYSCANDELTA
establishes the dial-up monitoring period
(see the VAX-11 Software
Installation Guide).
If a line's carrier signal is lost, the driver waits nine monitor
periods for the carrier signal to return or none if the system
generation parameter DIALTYPE is 1.
(DIALTYPE is O by default and is
relevant to the United Kingdom only.) If the carrier signal is not
detected during this time, the line is "hungup." The hang-up action
signals the owner of the line, through a mailbox message, that the
line is no longer in use.
(No dial-in message is sent;
the
unsolicited character message is sufficient when the first available
data is received.) The line is not available for two monitor periods
after the hang-up sequence begins.
The hang-up sequence is not
reversible. If the line hangs up, all enabled CTRL/Y ASTs are
delivered;
the CTRL/Y AST P2 argument is overwritten with SS$ HANGUP.
The I/O operation in progress is cancelled and the status value
SS$ ABORT is returned in the IOSB.
When a line with the TT$M REMOTE characteristic
characteristics of the line-return to TT$M LOCAL.

2.2.8

hung

up,

the

Duplex Modes

The VAX/VMS terminal driver can execute in either half- or full-duplex
mode.
These terms describe the terminal driver software, not the
terminal communication lines. For the communication lines, the driver
supports the DZ-11 Asynchronous Serial Line Multiplexer and the
console terminal. In terminal driver software, the terms half- and
full-duplex refer to ordering algorithms used to service read and
write requests.
In half-duplex mode, all read and write requests are inserted onto one
queue.
The driver removes requests from the head of this queue and
executes them one at a time; all requests are sequentially executed
in the order they were issued.
In full-duplex mode, read requests are inserted onto one queue and
write requests onto another. The existence of two queues allows the
driver to recognize the presence of two requests -- a read and a write
at the same time.
However, the driver cannot execute a read
request and a write request simultaneously.
When it is ready to
service a request, the driver dynamically decides which request -- the
read or the write -- to process next.
In the VAX/VMS terminal driver, write requests normally have priority.
A write request can interrupt a current, but inactive, read request.
A read request is current when the terminal driver removes that

2-9

TERMINAL DRIVER

request from the head of the read queue. In a simple read operation,
the read request becomes active when the first input character is
received and echoed.
In a read with prompt operation, the read
request becomes active when the first character of the prompt is
output to the terminal. Once a read request becomes active, all write
requests will be queued until the read completes. However, during a
simple read operation many write requests can be executed before the
first input character is typed at the terminal.
When all I/O requests are issued using SQIOW calls, there can be only
one current I/O request at any time. In this case, the order in which
requests are serviced is the same for both half- and full-duplex
modes.
The type ahead buffer always buffers input data for which there is
current read request, in both half- and full-duplex modes.

2.3

DEVICE INFORMATION

The user process can obtain terminal characteristics by using the
$GETCHN
and
$GETDEV system services (see Section 1.10).
The
terminal-specific information is returned in the first three longwords
of a user-specified buffer as shown in Figure 2-2 (Figure 1-9 shows
the entire buffer).
31

24 23

16 15

8 7

device characteristics

class

page length

terminal characteristics

Figure 2-2 Terminal Information
The first longword contains device-independent data.
third longwords contain device-dependent data.

The

second

and

Table 2-3 lists the device-independent characteristics returned in the
first longword.

2-10

TERMINAL DRIVER

Table 2-3
Terminal Device-Independent Characteristics
Characteristic Namel

Meaning

DEV$M_AVL

Terminal is on line and available

DEV$M IDV

Terminal is capable of input

DEV$M_ODV

Terminal is capable of output

DEV$M SPL

Spooled

DEV$M CCL

Carriage control

DEV$M_REC

Record oriented

DEV$M TRM

Terminal device

1. Defined by the $DEVDEF macro
The first byte of the second longword returns the device class
(DC$ TERM).
The second byte returns the terminal type, for example,
DT$ VT52. The $DCDEF macro defines the symbols for terminal class and
type.
The third and fourth bytes of the second longword return the page
width. The page width can have a value in the range of 1 to 511. The
driver does not accept a value of O.
The third longword contains terminal characteristics in the first
three
bytes
and
page
length in the fourth byte.
Terminal
characteristics are normally set at system generation time to any one
of, or a combination of, the values listed in Table 2-4. The $TTDEF
macro defines symbols for terminal characteristics. Page lengtn ca~
have a value in the range of O to 255.
The Set Mode and Set Characteristics function (see Section 2.4.3) and
the Set Terminal command are used to change terminal characteristics.
The VAX/VMS Command Language User's Guide describes the Set Terminal
command.

2-11

TERMINAL DRIVER
Table 2-4
Terminal Characteristics
Value 1

Meaning

TT$M CRFILL

Terminal requires fill after RET (the fill type
can be specified by the Set Mode function P4
argument") •

TT$M EIGHTBIT

Terminal uses 8-bit
ASCII
character
set.
Terminals without this characteristic use the
7-bit ASCII code. In this case, the eighth bit
is masked out on received characters and ignored
on output characters.
The eighth
bit
is
meaningful only if TT$M_EIGHTBIT is set.

TT$M ESCAPE

Terminal generates escape sequences (see Section
2.2.4).
Escape sequences are validated for
syntax.

TT$M HALFDUP

Terminal is in half-duplex mode
2. 2. 8) •
All reads and writes
sequentially.

TT$M HOLDSCREEN

Terminal is in Holdscreen Mode.
The driver
automatically causes the terminal to enter or
exit from the mode when the mode is changed at
the terminal.
This mode is meaningful only to
the DEC VT-52 and VT-55 terminals (see the
DECscope User's Guide) and the VT-100 terminal
(see the VTlOO User Guide).

TT$M HOSTSYNC

Host/terminal
synchronization.
CTRL/Q
and
CTRL/S are used to control data flow and thus
keep the type-ahead buffer from filling.

TT$M LFFILL

Terminal requires fill after LF (the fill can be
specified by the Set Mode P4 argument).

TT$M LOWER

Terminal has lower case character set.
Unless
the
terminal
is
in the PASSALL mode or
IO$M NOFORMAT is specified, all input, output,
and -echoed lowercase characters (hexadecimal 61
to 7A) are converted to uppercase if TT$M LOWER
is not set.

TT$M MBXDSABL

Mailboxes associated with the terminal will not
receive
unsolicited
input
notification or
hang-up notification {see Section 2.2.7).
This
bit can be set by the IO$M DSABLMBX function
modifier for
reads
and
~leared
by
the
IO$M ENABLMBX function modifier for writes.

TT$M MECHFORM

Terminal has mechanical form feed.
The driver
passes form feeds directly to the terminal
instead of expanding to line feeds.

1. Prefix can be TT$M or TT$V •
TT$M
corresponds to the specific field; TT$V

(see Section
are executed

is a bit mask
is a bit number.

whose

bit

{continued on next page)

2-12

TERMINAL DRIVER

Table 2-4 (Cont.)
Terminal Characteristics
Valuel

Meaning

TT$M MECHTAB

Terminal has mechanical tabs.
In order to
accomplish correct line wrapping, MODULO (8) is
assumed.

TT$M NOBRDCST

Terminal will
messages.

TT$M NOECHO

Input characters are not echoed on this terminal
line (see Section 2.2.1).

TT$M NOTYPEAHD

Data must be solicited by a read operation.
Data is lost if received in the absence of an
outstanding read request, that is, unsolicited
data.
Disables
type-ahead capability (see
Section 2.2.1).

TT$M PASSALL

Terminal is in PASSALL mode;
all input and
output data is in binary (no data interpretation
occurs).
Data termination occurs when
the
buffer is full or the read data matches the
specified terminator.
(See Section 2.4.1 for a
comparison
with
the
read
QIO
function
!0$ _ READPBLK.)

TT$M READSYNC

Read synchronization.
The
host
explicitly
solicits all read operations by issuing a CTRL/Q
and terminates the operation· by issuing
a
CTRL/S.

TT$M REMOTE

Dial-up terminal.
Terminal returns to local
mode when a hang-up 'occurs on the terminal line
(see Section 2.2.5). This characteristic cannot
be changed;
it is only informational.

TT$M SCOPE

Terminal is a video
screen
display
(CRT
terminal), for example, the VT-52 or VT-100.

TT$M TTSYNC

Terminal/host synchronization.
Output to the
terminal is controlled by terminal-generated
CTRL/Q and CTRL/S.

TT$M WRAP

A newline should be inserted if the cursor moves
beyond the right margin. If TT$M WRAP is not
set, no newline is sent.

not

1. Prefix can be TT$M or TT$V •
TT$M
corresponds to the specific field; TT$V

2.4

receive

any

is a bit mask
is a bit number.

broadcast

whose

bit

TERMINAL FUNCTION CODES

The basic terminal I/O functions are read, write, and set mode or
characteristics (see Section 1.5). All three I/O functions can take
function modifiers.
There are two set mode or characteristics
functions:
Set
Mode
(IO$_SETMODE)
and
Set
Characteristic
(IO$_SETCHAR).

2-13

TERMINAL DRIVER

2.4.1

Read

When a read function code is issued, the user-specified buffer is
filled with characters from the associated terminal. VAX/VMS defines
four basic read functions, which are listed with their function codes
below:

•
•
•
•
•
•

IO$ READVBLK - read virtual block

IO$ READLBLK - read logical block

IO$ READ PROMPT - read with prompt
IO$ READPBLK - read physical block

IO$ TTYREADALL - read passall (virtual or logical block)

IO$ TTYREADPALL - read passall with prompt (virtual or logical
block)

Read operations are terminated if either of the
occurs:
•

The user buffer is full

•

The received character is included in a
mask (see Section 2.4.1.2)

The read function codes can take all six
arguments (Pl through Po) on QIO requests:

following

conditions

specified

terminator

device/function-dependent

•

Pl = the starting virtual address of the
receive the data read

•

P2 = the size of the buffer that is to receive the data read
in bytes.
A system generation parameter, MAXBUF, limits the
maximum size of the buffer.

•

P4 = the read terminator descriptor block address (see Section
2.4.1.2)

•

PS = the starting virtual address of the prompt buffer that is
to
be written to the terminal.
For read with prompt
operations (IO$_READPROMPT or IO$_TTYREADPALL).

•

Po = the size of the prompt buffer that is to be written to
the terminal. For read with prompt operations (IOS_READPROMPT
or IO$_TTYREADPALL).

= read with
IO$M_TIMED)

timeout,

timeout

count

buffer

(see

that

Table

2-5,

In a read with prompt operation, the P5 and Po arguments specify the
address and size of a prompt string buffer containing data to be
written to the terminal before the input data is read. In a read with
prompt operation, a write operation and a read operation are performed
on the specified terminal. The prompt string buffer is formatted like
any other write buffer, but no carriage control can be implicitly
specified.
(Carriage control specifiers are described in Section
2.4.2.2.)
During a read with prompt operation, typing CTRL/O (which is turned
off at the start of any read) stops the prompt string. If CTRL/U or
CTRL/X is typed, the entire prompt string is written out again and the

2-14

TERMINAL DRIVER
current input is ignored.
If CTRL/R is typed, the current prompt
string and input are written to the terminal.
Depending on the terminal type and the user's input, the prompt string
can be very simple or quite complex -- from single command prompts to
screen fills followed by input data.
In PASSALL mode, data received from the associated terminal is placed
in the user buffer as binary information without interpretation.
There are three ways to place the terminal driver in a temporary
PASSALL mode for the duration of a single read QIO:
1.

IO$ READPBLK -- reads a physical block without
the-data. Physical I/O privilege is required.

interpreting

IO$ TTYREADALL -- allows nonprivileged
terminal driver interpretation of data.

IO$ TTYREADPALL -- performs
the
same
function
IO$=TTYREADALL after writing a prompt string.

users

bypass
as

These functions are in contrast with the more comprehensive PASSALL
mode established by the Set Mode characteristic TTSM PASSALL. All
input and output data is in 8-bit binary format when TTSM PASSALL is
set (see Section 2.4.3).
Since IO$ READPBLK, IO$ TTYREADALL, and IO$ TTYREADPALL do not purge
the type~ahead buffer (unless requested usTng the IOSM PURGE function
modifier) the characters in the type-ahead buffer may have been
subjected to CTRL/Y/C/S/Q/O interpretation.

2.4.l.l Function Modifier Codes for Read QIO
Functions - Eight
function modifiers can be specified with IO$ READVBLK, IO$ READLBLK,
IO$ READPROMPT, IO$ READPBLK, IO$ TTYREADALL- and
IO$ TTYREADPALL.
Table
2-5
lists
these
functTon
modifiers.
IO$M CVTLOW and
IO$M NOFILTR are not meaningful to IO$_READPBLK, IOS_TTYREADALL, and
IO$ TTYREADPALL.
Table 2-5
Read QIO Function Modifiers
Code

Consequence

IO$M CVTLOW

Lowercase alphabetic characters (hexadecimal nl to
7A) are converted to uppercase when transferred to
the user buffer or echoed. Only for IO$ READLBLK,
IO$_READVBLK, and IO$_READPROMPT.
-

IO$M DSABLMBX

The mailbox is disabled for unsolicited data.

IO$M NOECHO

Characters are not echoed (that is, displayed)
as
they are entered at the keyboard. The terminal
line can also be set to a "no echo" mode by the
Set
Mode
characteristic
TT$M NOECHO,
which
inhibits all read operation echoing.
(continued on next page)

2-15

TERMINAL DRIVER

Table 2-5 (Cont.)
Read QIO Function Modifiers
Code

Consequence

IO$M NOFILTR

The terminal does not interpret CTRL/U, CTRL/R, or
DEL.
They are passed to the user. Only for
IO$_READLBLK, IO$_READVBLK, and IO$ READPROMPT.

IO$M PURGE

The type-ahead buffer is purged
operation begins.

IO$M REFRESH

If the read operation is interrupted by a write
(either a write break through or any other type of
write), display the current read data when the
read function is restarted.

IO$M TIMED

The P3 argument specifies the
maximum
time
(seconds)
that can elapse between characters
received; that is, the timeout value for the
operation.
If the read does not complete within
the specified time, a timeout error
(SS$ TIMEOUT)
is returned. All input characters received before
the read timed out are returned in the user's
buffer.

before

the

read

A read with timeout operation in which the timeout
value is 0 empties the type-ahead buffer into the
user buffer until the proper termination condition
is reached (buffer full, termination character
detected, or type-ahead buffer empty).
The read
operation then returns the count of characters
read and, if a terminator is read, SSS NORMAL;
SS$ TIMEOUT is returned if no terminator Ts read.
In either case the byte count in the IOSB always
indicates the number of characters read.
IO$M TRMNOECHO

The termination character (if any) is not echoed.
There is no formal terminator if the buffer is
filled before the terminator is typed.

'----------""------------·-------------------------------------""
2.4.1.2 Read Function Terminators - The P4 argument to a read QIO
function either specifies the terminator set for the read function or
points to the location containing the terminator set. If P4 is O, all
ASCII characters with a code in the range O through 31 (hexadecimal 0
through lF) except LF, VT, FF, TAB, and BS, are terminators.
(This is
the VAX-11 RMS standard terminator set.)
If P4 does not equal O, it contains the address of a quadword that
either specifies a terminator character bit mask or points to a
location containing that mask. The quadword has a short form and a
long
form, as shown in Figure 2-3.
In the short form, the
correspondence is between the bit number and the binary value of the
character;
the character is a terminator if the bit is set. For
example, if bit 0 is set, NULL is a terminator;
if bit 9 is set, TAB
is a terminator.
If a character is not specified, it is not a.
terminator. Since ASCII control characters are in the range O through
31, the short form can be used in most cases.

2-16

TERMINAL DRIVER

The long form allows use of a more comprehensive set of terminator
characters.
Any mask equal to or greater than 1 byte is acceptable.
For example, a mask size of 16 bytes allows all 7-bit ASCII characters
to be used as terminators; a mask size of 32 bytes allows all 8-bit
characters to be used as terminators for 8-bit terminals.
If the terminator mask is all O's, there are no specified terminators.
The read operation ends when the specified number of characters have
been transferred to the input buffer.
0

SHORT:

terminator character bit mask

16 15

(not used)

LONG:

mask size in bytes

address of mask

Figure 2-3 Short and Long Forms of Terminator Mask Quadwords

2.4.2

Write

Write operations display the contents of a user-specified buff er on
the associated terminal.
VAX/VMS defines three basic write I/O
functions, which are listed with their function codes below:
•

IO$ WRITEVBLK - write virtual block

IO$ WRITELBLK - write logical block

IO$ WRITEPBLK - write physical block

The
write
function
codes
can
device/function-dependent arguments:

take

the

following

•

Pl = the starting virtual address of the buffer that is to
written to the terminal

•

P2 = the number of bytes that are to be written to the
terminal.
A system generation parameter, MAXBUF, limits the
maximum size of the buffer.

•

P3 (ignored)

P4 = carriage control
• block
operations.

specifier except for write physical
(Write function carriage control is
described in Section 2.4.2.2.)

P3, PS, and P6 are not meaningful for terminal write operations.

2-17

TERMINAL DRIVER
In write virtual block and write logical block operations, the buffer
(Pl and P2)
is formatted for the selected terminal and includes the
carriage control information specified by P4.
All lowercase characters are converted
to
uppercase
if
the
characteristics of the selected terminal do not include TT$M LOWER
(this does not apply to write physical block operations or- when
IO$M_NOFORMAT is specified).
Unless TT$M MECHFORM is specified, multiple line feeds are generated
for form feeds.
The number of line feeds generated depends on the
current page position and the length of the page.
By producing a
carriage return after the last line feed, a form feed also moves the
cursor to the left margin. Multiple spaces are generated for tabs if
the
characteristics
of
the selected terminal do not include
TT$M MECHTAB (this does not apply to write physical block operations).
Tab -stops are every 8 characters or positions (that is, 1, 8, ln,
24, ••• ).

2.4.2.1 Function Modifier Codes for Write QIO
Functions - Four
function modifiers can be specified with IO$ WRITEVBLK, IO$ WRITELBLK,
and IO$ WRITEPBLK. Table 2-fi lists these function modifiers.
Table 2-fi
Write QIO Function Modifiers
Code

Consequence

IO$M CANCTRLO

Turns off CTRL/O (if it is in effect) before the
write.
Otherwise,
the
data
may not be
displayed.

IO$M ENABLMBX

Enables use of the mailbox associated with the
terminal for notification that unsolicited data
is available.

IO$M NOFORMAT

Allows nonprivileged users to write information
without interpretation or format;
in effect the
terminal line is in a temporary PASSALL mode.

IO$M REFRESH

If a read operation is interrupted by a write
(either a write breakthrough or any other type
of write), display the current read data when
the read function is restarted.

2.4.2.2 Write Function Carriage Control - The P4 argument is a
longword that specifies carriage control. Carriage control determines
the next printing position on the terminal. P4 is ignored in a write
physical block operation. Figure 2-4 shows the P4 longword format.
Only bytes O, 2, and 3 in the longword are used. Byte 1 is ignored.
If the low-order byte (byte 0) is not O, the contents of the longword
are interpreted as a FORTRAN carriage control specifier.
Table 2-7
lists the possible byte O values (in hexadecimal) and their meanings.

2-18

TERMINAL DRIVER

P4:

POSTFIX

PREFIX

Figure 2-4

(not used)

FORTRAN

P4 Carriage Control Specifier

Table 2-7
Write Function Carriage Control (FORTRAN: Byte 0 not equal to 0)
Byte
Value
(hexadecimal)

ASCII
Character

Meaning

(space)

Single space
carriage
control.
(Sequence:
newline, print buffer
contents, return.)

Double-space
carriage
control.
(Sequence: newline, newline, print
buffer contents, return.)

Page
eject
carriage
control.
(Sequence:
form feed, print buffer
contents, return.)

Overprint
carriage
control.
(Sequence:
print buffer contents,
return.) Allows double printing for
emphasis or special effects.

Prompt
(Sequence:
contents.)

All other
values

carriage
newline,

control.
print buffer

Same as ASCII space character:
single-space carriage control.

If the low-order byte (byte 0) is O, bytes 2 and 3 of the P4 longword
are interpreted as the prefix and postfix carriage control specifiers.
The pref ix (byte 2) specifies the carriage control before the buffer
contents are printed.
The postfix (byte 3) specifies the carriage
control after the buffer contents are printed. The sequence is:
Prefix carriage control - Print - Postfix carriage control
The prefix and postfix bytes, although interpreted separately, use the
same encoding scheme.
Table 2-8 shows this encoding scheme in
hexadecimal.

2-19

TERMINAL DRIVER
Table 2-8
Write Function Carriage Control (P4 byte 0

Prefix/Postfix Bytes
(Hexadecimal)
Bit 7

Bits 0 ...

Meaning

--~......,

carriage
control
is
No
specified, that is, NULL.

1 - 7F

Bits 0 through 6 are a count
of newlines (carriage return
followed by a line feed) •

Bit 7

Bit 6

Bit 5

Bits 0-4

Meaning

1-lF

single
ASCII
Output the
control character specified
by the configuration of bits
0 through 4 (7-bit character
set) •

1-lF

single
ASCI'I
Output the
control character specified
by the configuration of bits
which are
through
4
0
ASCII
translated
as
characters 128 through 159
( 8-bi t character set) •

Figure 2-5 shows the prefix and postfix hexadecimal coding that
produces the carriage control functions listed in Table 2-7. Prefix
and postfix coding provides an alternative way to achieve these
controls.

2-20

TERMINAL DRIVER

(Space)
P4:

Sequence:

Prefix= NL
Print
Postfix =CR

"O"

P4:

Sequence:
BO

"1"

P4:

Prefix= LF, LF
Print
Postfix= CR

Sequence:
BO

]

"+"

Prefix= FF
Print
Postfix= CR

Sequence:

P4:
BO

]

"$"

Prefix= NULL
Print
Postfix= CR

Sequence:

P4:
0

Example: Skip 24 lines before printing

Sequence:

P4:
BO

Prefix= NL
Print
Postfix= NULL

0--

---J

Prefix = 24N L
Print
Postfix:= CR

Figure 2-5 Write Function Carriage Control
(Pref ix and Postfix Coding)

In the first example, the prefix/postfix hexadecimal coding for a
single-space carriage control (newline, print buffer contents, return)
is obtained by placing the value 1 in the second {pref ix) byte and the
sum of the bit 7 value (80) and the return value (D) in the third
postfix byte:
80
+ D

(bit 7 = 1)
(return)

{postfix

2-21

return)

TERMINAL DRIVER
2.4.3

Set Mode

Set Mode operations affect the operation and characteristics of the
associated terminal line.
VAX/VMS defines two types of set mode
functions:
•

Set Mode

•

Set Characteristics

The Set Mode function affects the mode and temporary characteristics
of the associated terminal line. Set Mode is a logical I/O function
and requires no privilege. A single function code is provided:
e

IO$ SETMODE

The Set Characteristics affects the permanent characteristics of the
associated terminal line.
Set Characteristics is a physical I/O
function and requires the privilege necessary to perform physical I/O.
A single function code is provided:
•

IO$ SETCHAR

These functions take the following device/function-dependent arguments
if no function modifiers are specified:
•

address of characteristics buffer

speed specifier (bits 0 through 15 only)

•

P4
fill specifier (bits 0 through 7 = CR fill count;
through 15 = LF fill count)

•

bits 8

= parity flags

The Pl argument points to a quadword block, as shown in Figure 2-n.
With the exception of terminal characteristics, the contents of the
block are the same for both Set Mode and Set Characteristic functions.
The class portion of the block contains DC$ TERM, which is defined by
the $DCDEF macro.
Type values are defined by the $DCDEF macro, for
example, DT$ LA36. Page width can have a value in the range of 1 to
511.
Page length can have a value in the range of 0 to 255. Table
2-4 lists the values for terminal characteristics. These values are
defined by the $TTDEF macro.
The P3 argument defines the device speed, for example, TT$C BAUD 300.
If P3 is O, the baud rate is not changed. P4 contains fill ~ounti for
the carriage return and line feed characters.
Bits 0 through 7
specify the number of fill characters used after a return. Bits 8
through 15 specify the number of fill characters used after a line
feed.
31

24 23

page width

page length

Figure

16 15

8 7

_ _L _ _ ~~·=1-....----.. _ _~-~·-class----i
terminal characteristics

2-n

Set Mode Characteristic Buffer

2-22

TERMINAL DRIVER
(P4 is applicable only if TT$M CRFILL or TT$M LFFILL is specified as a
terminal characteristic for the current QIO request; see Table 2-4.)
Three parity flags can be specified in the PS argument:
TT$M ALTRPAR -

alter parity,
change parity on
terminal line if
set

TT$M PARITY

enable parity on
terminal line i f
set, disable if
clear

TT$M_ODD

parity is odd i f
set

If parity is enabled, the DZ-11 generates a parity check bit to detect
parity mismatch.
Parity errors that occur during an I/O read
operation are fatal to the operation. Parity errors that occur when
no I/O operation is in progress may result in a character loss.
The Set Mode and Set Characteristic functions can take the Enable
CTRL/C AST, Enable CTRL/Y AST, and Hang-up function modifiers that are
decribed below.

2.4.3.1 Hang-Up Function Modifier - The Hang-Up function disconnects
a terminal that is on a dial-up line.
(Dial-up lines are described in
Section 2.2.7.) Two combinations of function code and modifier are
provided:
e

IO$ SETMODE!IO$M HANGUP

•

IO$ SETCHAR!IO$M HANGUP

The Hang-up function modifier takes
returned in the I/O status block.

arguments.

SS$ NORMAL

2.4.3.2 Enable CTRL/C
AST
and
Enable
CTRL/Y
AST
Function
Modifiers - Both set mode functions can take the Enable CTRL/C AST and
Enable CTRL/Y AST function modifiers.
These function modifiers
request the terminal driver to queue an AST for the requesting process
when the user types CTRL/C or CTRL/Y. Enable CTRL/Y AST requires the
caller to have either supervisor, executive, or kernel access mode, or
logical or physical I/O privilege. Four combinations of function code
and modifier are provided:
•

IO$_SETMODE!IO$M_CTRLCAST - Enable CTRL/C AST

•

IO$_SETMODE!IO$M_CTRLYAST - Enable CTRL/Y AST

•

IO$ SETCHAR!IO$M CTRLCAST - Enable CTRL/C AST

IO$ SETCHAR!IO$M CTRLYAST - Enable CTRL/Y AST

2-23

TERMINAL DRIVER
These
function
code
modifier
pairs
device/function-dependent arguments:

take

following

the

•

Pl = address of the AST service or 0 if the corresponding
is disabled

•

AST

AST parameter

access mode
access mode)

deliver

AST

(maximized

If the respective enable is in effect, typing CTRL/C or
the attention of the enabling process (see Table 2-1).

with

caller's

CTRL/Y

gains

Enable CTRL/C and CTRL/Y AST are single (one-time) enables. After the
AST occurs, it must be explicitly re-enabled by one of the four
function code combinations described above before an AST can occur
again.
This function code is also used to disable the AST. The
function is subject to AST quotas.
The user can have more than one CTRL/C or CTRL/Y enabled.
All ASTs
are given in their order of request, that is, first in first out, when
the character is typed. For example, typing CTRL/C results in the
delivery of all CTRL/C ASTs.
If no CTRL/C enable is present, the holder of a CTRL/Y enable will
receive an AST when CTRL/C is typed; newline, AY, return is echoed.
CTRL/C enables are flushed by the Cancel I/O on Channel
($CANCEL)
system service. CTRL/Y enables are flushed only during unit run down,
that is, after the last deassignment by the Deassign I/O Channel
($DASSGN) system service.
CTRL/Y is normally used to gain the attention of the command
interpreter and thus allow the user to input special commands such as
DEBUG, STOP, CONTINUE, and so on.
Thus it is recommended that
programs run from a command interpreter not enable CTRL/Y. Also,
since ASTs are delivered on a first-in first-out basis, the command
interpreter's AST routine will get control first and possibly not
allow the program's AST to be delivered at all.
Section 2.2.6 describes other effects of CTRL/C and CTRL/Y.

Sense Mode

2.4.4

The Sense Mode functions sense the characteristics of the terminal and
return them to the caller in the I/O status block. Two function codes
are provided:
•

IO$ SENSEMODE

•

IO$ SENSECHAR

IO$ SENSEMODE returns the process-associated, that is, temporary,
characteristics
of
the terminal and IO$ SENSECHAR returns the
permanent characteristics of the terminal. IOS SENSEMODE is a logical
I/O function and requires no privilege. IO$ SENSECHAR is physical I/O
function and requires the privilege necessary to perform physical I/O.

2-24

TERMINAL DRIVER

These function
argument:

codes

take

the

following

device/function-dependent

Pl = address of a quadword characteristics buffer
The Pl argument points to a quadword block, as shown in Figure 2-7.
16 15

8 7

buffer size

type

class

terminal characteristics

-------------------------------

_______

___.

Figure 2-7 Sense Mode Characteristics Buffer
The class portion of the block contains DC$ TERM, which is defined by
the $DCDEF macro.
Type values are defined by the $DCDEF macro, for
example, DT$ LA3n.
Table 2-4 lists the
values
for
terminal
characteristics. These values are defined by the $TTDEF macro.
The Sense Mode and Sense Characteristic functions
type-ahead count function modifier IO$M TYPEAHDCNT.

can

take

the

IO$M TYPEAHDCNT returns the count of characters presently in the
type=ahead buffer and a copy of the first character in the buffer. In
this case, the Pl argument points to a characteristics buffer returned
by IO$M TYPEAHDCNT. Figure 2-8 shows the format of this buffer.
24 23

(reserved)

16 15
number of
characters in type-ahead
buffer

first
character

(reserved)

Figure 2-8

2.5

Sense Mode Characteristics Buffer (Type-ahead)

I/O STATUS BLOCK

The I/O status block formats for the read, write, set mode, and
mode I/O functions are shown in Figures 2-9, 2-10, and 2-11.
2-9 lists the status returns for these functions.

IOSB

offset to terminator

status

terminator size

terminator
+6

Figure 2-9 IOSB Contents - Read Function

2-25

sense
Table

TERMINAL DRIVER
In Figure 2-9, the offset to terminator at IOSB+2 is the count of
characters before the terminator character (see Section 2.4.1.2). The
terminator character(s) is in the buffer at the offset specified in
IOSB+2. When the buffer is full, the offset at IOSB+2 is equal to the
requested buffer size. At the same time, IOSB+4 is equal to 0.
IOSB+6 contains the size of the terminator string, usually 1.
However, in an escape sequence, IOSB+n contains the size of the
validated escape sequence (see Section 2.2.4). The sum of IOSB+2 and
IOSB+6 is the number of characters in the buffer.
24 23

16-15

byte count
line
position

status

column
position

Number of lines output
for the 1/0 function*

*o if 10$_WRITEPBLK, 10$M_NOFORMAT, or PASSALL mode

Figure 2-10 IOSB Contents - Write Function
In Figure 2-10, the line and column positions are the terminal
driver's internal computation of the cursor position after the write
function has completed.
Note that the terminal driver does not
presently track any effects that escape sequences may have on the
cursor position.

speed

parity flags

status

LF fill
count

CR fill
count

Figure 2-11 IOSB Contents - Set Mode, Set Characteristics,
Sense Mode, and Sense Characteristics Functions
Table 2-9
Terminal QIO Status Returns
....--------------------~-----·--------

-----------------------........
Meaning

Status
SS$ ABORT

The operation was canceled by the Cancel I/O
on
Channel
($CANCEL)
system
service.
Applicable only if the driver was actively
involved in a terminal operation.

SS$ BADESCAPE

Invalid escape sequence terminator begins at
the offset (IOSB+2).

SS$ CONTROLC

Read or write operation
because CTRL/C was typed.

SS$ CONTROLO

Write operation not completed because CTRL/O
was typed •

______________ ___________

...__

....__

not

~---------------

completed

--------'

(continued on next page)

2-211

TERMINAL DRIVER
Table 2-9 (Cont.)
Terminal QIO Status Returns
Meaning

Status
f--------------4---------

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

-------

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

SS$ CONTROLY

Read or Write operation
because CTRL/Y was typed.

SS$ NORMAL

Successful
completion.
The
operation
specified
in
the
QIO
was
completed
successfully. On a read or write operation,
the second word of the IOSB can be examined
to determine the number of bytes processed.
The input or output buffer contains these
bytes.

SS$ PARITY

Parity bit mismatch detected by the device
interface during a read operation. The I/O
operation stopped when the mismatch was
detected.
(Data was received up to this
is
point in the operation.) SS$ PARITY
meaningful only on terminal lines that have
parity enabled.

SS$ PARTESCAPE

Partial escape sequence was stored.
An
escape sequence was started but read-buffer
space was exhausted before the sequence was
completed. The remainder of the sequence is
available from the type-ahead buffer on the
next read unless the terminal line has the
TT$M NOTYPEAHD characteristic
(see Section

not

completed

2. 2. 4) •

SS$ TIMEOUT

Operation timeout. The specified terminal
could not perform the QIO read operation
because a timeout occurred at the termjnal,
that
is,
an
interrupt
was lost, or
IO$M TIMED was specified on a read operation
(see- Table 2-5), or a hardware timeout
occurred. IOSB+2 contains the number of
bytes
transferred
before
the
timeout
occurred.

>----------------'---·-···----·

2.6

-·----------------------------'

PROGRAMMING EXAMPLE

The following program shows examples of several I/O operations, usinq
the full duplex capabilities of the driver. The program illustrates
some important concepts concerning terminal driver
programming:
assigning an I/O channel, performing full-duplex I/O operations, and
enabling CTRL/C ASTs.
The program is designed to run with a terminal set to full-duplex
mode.
The initialization code queues a read to the terminal and
enables CTRL/C ASTs. The main loop then prints out a random message
every three seconds. When the user types a message on the terminal,
the read AST routine prints an acknowledgement message and queues
another read.
If the user types CTRL/C, the associated AST routine
cancels the I/O operation on the assigned channel and exits to the
command interpreter.

2-27

TERMINAL DRIVER

********************************************************************
TERMINAL PROGRAM

********************************************************************
.TITLE
• !DENT

FULL DUPLEX TERMINAL PROGRAMMING EXAMPLE
/02/-

DEFINE SYMBOLS
$IODEF

; DEFINE I/O FUNCTION CODES

ALLOCATE TERMINAL DESCRIPTOR AND CHANNEL NUMBER STORAGE
TT DESC:
.ASCID
DEV DESC:
PHYS NAME LEN:
.LONG
PHYS NAME ADR:
.LONG
PHYS NAME:
.BLKB
TT CHAN:
.BLKW

/SYS$INPUT/

LOGICAL NAME OF TERMINAL
TRANSLATED PHYSICAL DEVICE DESCRIPTOR

63
PHYS NAME
63
1

TT CHANNEL NUMBER STORAGE

ALLOCATE INPUT BUFFER
IN BUF:
.BLKB
20
IN BUFLEN=.-IN BUF
IN-IOSB:
.BLKQ
1

20 CHARACTER BUFFER
CALCULATE LENGTH OF BUFFER
INPUT I/O STATUS BLOCK

DEFINE CARRIAGE CONTROL SYMBOLS
CR="'XOD
LF="'XOA

CARRIAGE RETURN
LINE FEED

DEFINE ACKNOWLEDGEMENT MESSAGE
ACK MSG:
.ASCII /INPUT ACKNOWLEDGED/<CR><LF>
ACK MSGLEN=.-ACK MSG
; CALCULATE LENGTH OF MESSAGE
DEFINE OUTPUT MESSAGES
OUTPUT MESSAGES ARE ACCESSED BY INDEXING INTO A TABLE OF
LONGWORDS WITH EACH MESSAGE DESCRIBED BY A MESSAGE ADDRESS AND
MESSAGE LENGTH

2-28

TERMINAL DRIVER
ARRAY:
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG

TABLE OF MESSAGE ADDRESSES AND
LENGTHS
FIRST MESSAGE ADDRESS
FIRST MESSAGE LENGTH

10$
15$
20$
25$
30$
35$
40$
45$

DEFINE MESSAGES
10$:
.ASCII
15$=.-10$

/RED ALERT!!!

RED ALERT!!!/<CR><LF>

;

20$:
.ASCII
25$=.-20$

/ALL SYSTEMS GO/<CR><LF>

;

30$:
.ASCII
35$=.-30$

/WARNING ••••• INTRUDER ALARM/<CR><LF>

;

40$:
.ASCII
45$=.-40$

/***** SYSTEM OVERLOAD *****/<CR><LF>

STATIC QIO PACKET FOR MESSAGE OUTPUT USING QIO$_G FORM
WRITE QIO:
$QIO

FUNC=IO$_WRITEVBLK,EFN=l

QIO PACKET

TIMER STORAGE
WAITIME:
.LONG

-10*1000*1000*3,-l

.BLKQ

3 SECOND DELTA TIME

TIME:
CURRENT STORAGE TIME USED FOR
RANDOM NUMBER

********************************************************************
START PROGRAM
********************************************************************
THE FOLLOWING CODE PERFORMS INITIALIZATION FUNCTIONS. THE PROGRAM
ASSUMES THAT THE TERMINAL IS ALREADY IN FULL-DUPLEX MODE.
START:
.WORD
0
ENTRY MASK
$TRNLOG S
GET TERMINAL'S PHYSICAL DEVICE NAME
LOGNAM=TT DESC,RSLLEN=PHYS NAME LEN,RLSBUF=DEV DESC CMPB
PHYS NAME,l~XlB ; DOES NAME START WITH ESCAPE ?
5$ NO
BNEQ
SUBL
#4,PHYS_NAME_LEN
; YES, STRIP OFF FIRST 4 CHARS

2-29

TERMINAL DRIVER
ADDL

#4,PHYS_NAME_ADR

;

5$:
$ASSIGN S

10$:

BLBS
BRW
BSBW
BSBW
MOVZWL

DEVNAM=DEV DESC,CHAN=TT CHAN
; ASSIGN
TERMINAL CHANNEL
R0,10$
NO ERROR IF SET
ERROR
ERROR
ENABLE CTRLCAST
ALLOW CONTROL/C TRAPS
ENABLE-READ
QUEUE READ
TT_CHAN,WRITE_QI0+8
INSERT CHANNEL INTO STATIC
QIO PACKET

THIS LOOP OUTPUTS A MESSAGE BASED ON A RANDOM NUMBER AND THEN DELAYS
FOR 3 SECONDS
LOOP:

10$:

$GETTIM S
TIMADR=TIME
BLBS
-R0,10$
BRW
ERROR
EXTZV
#6,#2,TIME,RO
MOVQ
ARRAY[RO] ,WRITE_QI0+28

GET RANDOM TIME
NO ERROR IF SET
LOAD RANDOM BITS INTO SWITCH
LOAD MESSAGE ADDRESS
AND SIZE INTO QIO PACKET

ISSUE QIO WRITE USING PACKET DEFINED IN DATA AREA
$QIOW G WRITE QIO
BLBS R0,5$BRW
ERROR

NO ERROR IF SET

DELAY FOR 3 SECONDS BEFORE ISSUING NEXT MESSAGE
5$:
$SETIMR S

20$:

EFN=#2,DAYTIM=WAITIME

BLBS
R0,20$
BRW
ERROR
$WAITFR S
EFN=#2
BLBS
-RO,LOOP
BRW
ERROR

; TIMER SERVICE WILL
SET EVENT FLAG IN 3 SECONDS
NO ERROR IF SET
WAIT FOR EVENT FLAG
NO ERROR IF SET

ROUTINE TO ALLOW CONTROL C RECOGNITION
ENABLE CTRLCAST:
$QIOW S CHAN=TT CHAN,FUNC=#IO$ SETMODE!IO$M CTRLCAST,Pl=CTRLCAST,AST ROUTINE ADDRESS
P3=#3
USER MODE
BLBS
R0,10$
; NO ERROR IF SET
BRW
ERROR
10$:
RSB
AST ROUTINE TO EXECUTE WHEN CONTROL C IS TYPED
CTRLCAST:

2-30

TERMINAL DRIVER
.WORD
AM<R2,R3,R4,R5>
$CANCEL S
CHAN=TT CHAN

; PROCEDURE ENTRY MASK
; FLUSH ANY I/O ON QUEUE

WHEN USING FULL-DUPLEX, ASYNCHRONOUS I/O, THE USER MUST ISSUE CANCEL
ON ANY OUTSTANDING I/O. THIS MUST BE DONE TO PREVENT ANY
OUTSTANDING QUEUED READS FROM BLOCKING DCL'S PROMPT MESSAGE.
DCL
PERFORMS ITS OWN CANCEL ON ITS OWN CHANNEL, NOT ONE DEFINED BY THE
USER.
$EXIT S

EXIT TO DCL

ROUTINE TO QUEUE A READ TO THE TERMINAL
ENABLE READ:
$QIO_S

BLBS
BRW

MUST NOT BE QIOW FORM
OR READ WILL BLOCK PROCESS

CHAN=TT_CHAN,FUNC=#IO$ READVBLK,IOSB=IN IOSB ,ASTADR=READAST ,Pl=IN BUF,P2=#IN BUFLEN
R0,10$ERROR

AST ROUTINE TO EXECUTE ON
NO ERROR IF SET

THE QUEUED READ WILL NOT AFFECT WRITES UNTIL THE FIRST CHARACTER IS
TYPED.
IF NO WRITES ARE ACTIVE AT THAT TIME, THE READ BECOMES
CURRENT AND SUBSEQUENT WRITES ARE BLOCKED UNTIL THE READ COMPLETES.
IF WRITES ARE ACTIVE, TYPED CHARACTERS ARE STORED IN THE TYPE AHEAD
BUFFER UNTIL THE WRITE QUEUE EMPTIES.
10$:

RSB

AST ROUTINE TO EXECUTE ON READ COMPLETION
READAST:
.WORD
$QIO_S

AM<R2,R3,R4,R5>
CHAN=TT CHAN,FUNC=#IO WRITEVBLK,Pl=ACK MSG,P2=#ACK MSGLEN

PROCEDURE ENTRY MASK
ISSUE ACKNOWLEDGE MESSAGE

PROCESS READ MESSAGE

(User provided code to decode command inserted here)

BSBW
RET

ENABLE READ

QUEUE NEXT READ
RETURN TO MAINLINE LOOP

ERROR ROUTINE
ERROR:

2-31

TERMINAL DRIVER

$EXIT S RO
.END

EXIT WITH STATUS ERROR
RETURN

START

2-32

CHAPTER 3
DISK DRIVERS

These
This chapter describes the use of the VAX/VMS disk drivers.
in Table 3-1 and detailed in
drivers support the devices listed
Section 3.1.
Table 3-1
Disk Devices
r-

Model

Type 1

RPM

Surf aces

Cylinders

Bytes/
Track

Bytes/
Drive

r------··

RM03

Pack

3600

8 23

in' 38 4

n7,420,lnO

RP05

Pack

3600

411

11,204

87,9n0,57n

RP06

Pack

3600

815

11,264

174,423,040

RK06

Cart

2400

411

11,264

13,888,512

RK07

Cart

2400

815

11,264

27,550,480

RXOl

Flex

300

3,328

2so,25n

"·-

1. Pack = pack disk;
(floppy}

Cart

cartridge disk;

Flex

flexible diskette

All disk drivers support Files-11 Structure Level 1 and Level
2 file
structures.
Access to these file structures is through the standard
MOUNT and !NIT DCL commands followed by the RMS-32 calls described
in
the VAX-11 Record Management Services Manual.
Files in RT-11 format
can be read or written with the file exchange facility FLX.
The contents of disk bootstrap blocks are CPU- and
operating
system-dependent.
For the
LSI-11 Console on the VAX-11/780, the
standard bootstrap for the RT-11
operating system is used.
Your
software support specialist can provide more information on the RT-11
bootstrap.

3.1

SUPPORTED DISK DEVICES

The following sections provide greater detail
devices listed in Table 3-1.

3-1

each

the

disk

DISK DRIVERS
3.1.1

RM03 Pack Disk

The RM03 pack disk is a removable, moving head disk that consists of 5
data surfaces.
The RM03 is connected to the system by a MASSBUS
adapter (MBA). Up to eight drives can be connected to each MBA.

3.1.2

RPOS and RP06 Pack Disks

The RP05 and RP06 pack disks consist of 19 data surfaces and a moving
read/write head.
The RPOn pack disk has approximately twice the
capacity of the RPOS. These disks are connected to the system by an
MBA. Up to eight drives can be connected to each MBA.

3.1.3

RK06 and RK07 Cartridge Disks

The RK06 cartridge disk is a removable, random-access, bulk-storage
device with three data surfaces.
The RK07 cartridge disk is a
double-density RK06. The RK06 and RK07 are connected to the system by
an RK611 controller which interfaces to the UNIBUS adapter (UBA). Up
to eight disk drives can be connected to each RKnll.

3.1.4

RXOl Console Disk

The RXOl floppy disk uses a flexible "diskette" or "floppy" disk. The
disk is connected to the LSI console on the VAX-11/780, which the
driver accesses using the MTPR and MFPR privileged instructions.
For read or write physical block operations, the track, sector, and
cylinder parameters shown in Figure 3-2 describe a physical, 128-byte
RXOl sector. Note that the driver does not apply track-to-track skew,
cylinder offset, or sector interleaving to this physical media
address. Sector numbers are interleaved to expedite data transfers.
Section 3.2.4 describes this feature in greater detail.

3.2

DRIVER FEATURES AND CAPABILITIES

The VAX/VMS disk drivers provide the following capabilities:
•

Multiple controllers of the same type; for example, more than
one MBA or RK611 can be used on the system

•

Up to eight drives per controller (depending on the device)

•

Different types of drive on a single controller (MBA only)

•

Overlapped seeks (except RXOl)

•

Data checks on a per-request,
basis (except RXOl)

•

Full recovery from
volumes mounted

•

Extensive error recovery algorithms;
correction and offset (except RXOl)

power

per-file,

failure

3-2

for

and/or
online

per-volume
drives

with

for example, error

code

DISK DRIVERS
•

Dynamic, as well as static, bad block handling

•

Logging of device errors in a file that can be
field service personnel or customer personnel

•

Online diagnostic support for drive level diagnostics

•

Multiple block, noncontiguous, virtual I/O operations
driver level

•

Optimization of physical sector translation (RXOl only)

displayed

the

The following sections describe the data check, overlapped seek, error
recovery, and logical to physical translation capabilities in greater
detail.

3.2.l

Data Check

A data check is made after successful completion of a read or write
operation and compares the data in memory with the data on disk to
make sure they match.
Disk drivers support data checks at three levels:
•

Per request -- Users can specify the data check function
modifier
(IO$M DATACHECK) on a read logical block, write
logical block, read virtual block, write virtual block,
read
physical block, or write physical block operation.

•

Per volume -- Users can specify the characteristics "data
check all reads"· and/or "data check all writes" when the
volume is mounted. The VAX/VMS Command Language User's Guide
describes volume mounting and d1smount1ng.

•

Per file -- Users can specify the file access attributes "data
check
on read" or "data check on write." File access
attributes are specified when the file is accessed. Chapter 9
of this manual and the VAX-11 Record Management Services
Reference Manual describe file access.

Offset recovery is performed during a data check but Error Code
Correctable (ECC) correction is not (see Section 3.2.3). This means
that if a read operation is performed and an ECC correction applied,
the data check would fail even though the data in memory is correct.
In this case, the driver returns a status code indicating that the
operation was successfully completed, but that the data check could
not be performed because of an ECC correction.
Data checks on read operations are extremely rare and users can either
accept the data as is, treat the ECC correction as an error, or accept
the data but immediately move it to another area on the disk volume.

3.2.2

Overlapped Seeks

A seek operation involves moving the disk read/write heads to a
specific place on the disk without any transfer of data. All transfer
functions, including data checks, are preceded by an implicit seek
operation (except when the seek is inhibited by the physical I/O
function modifier IO$M_INHSEEK).
Except on RXOl
drives,
seek

3-3

DISK DRIVERS

operations can be overlapped. That is, when one drive performs a seek
operation, any number of other drives can also
perform
seek
operations.
During the seek operation, the controller is free to perform transfers
on other units. Thus, seek operations can also overlap data transfer
operations. For example, at any one time, seven seeks and one data
transfer could be in progress on a single controller.
This overlapping is possible because, unlike I/O transfers, seek
operations do not require the controller once they are initiated.
Therefore, seeks are initiated before I/O transfers and
other
functions that require the controller for extended periods.

Error Recovery

3.2.3

Error recovery in VAX/VMS is aimed at performing all possible
operations to successfully complete an I/O operation. Error recovery
operations fall into four categories:
•

Handling special
interrupt timeout

conditions

•

Retrying nonfatal controller and/or drive errors

•

Applying error
RXOl)

•

Offsetting read heads to try to obtain
signal (not applicable for RXOl)

correction

such

information

power

(not
a

failure

and

applicable

for

stronger

recorded

The error recovery algorithm uses a combination of these four types of
error recovery operations to complete an I/O operation.
Power failure recovery consists of waiting for mounted drives to spin
up and come on line followed by reexecution of the I/O operation that
was in progress at the time of the power failure.
Device timeout is treated as a nonfatal error. The operation that was
in progress when the timeout occurred is reexecuted up to eight times
before a timeout error is returned.
Nonfatal controller/drive errors are simply
times before a fatal error is returned.

reexecuted

eight

All normal error recovery (nonspecial conditions) can be inhibited by
specifying the inhibit retry function modifier (IO$M INHRETRY). If
any error occurs and this modifier is specified, the virtual, logical,
or physical I/O operation is immediately terminated, and a failure
status is returned. This modifier has no effect on power recovery and
timeout recovery.

3.2.4

Logical to Physical Translation (RXOl)

Logical block to physical sector translation on RXOl drives adheres to
the
standard VAX/VMS format.
For each 512-byte logical block
selected, the driver reads or writes four 128-byte physical sectors.
To minimize rotational latency, the physical sectors are interleaved.
This allows the processor time to complete a sector transfer before
the next sector in the block reaches the read/write heads. To allow

3-4

DISK DRIVERS
for track to track switch time, the next logical sector that falls on
a new track is skewed by six sectors.
(There is no interleaving or
skewing on read physical block and write physical
block
I/O
operations.) Logical blocks are allocated starting at track l; track
0 is not used.
The translation procedure, in more precise terms, is as follows:
1.

Compute an uncorrected media address using
dimensions:
Number of sectors per track = 26
Number of tracks per cylinder = 1
Number of cylinders per disk

the

following

= 77

Correct
the
computed
address
for
interleaving
and
track-to-track skew (in that order) as shown in the following
VAX-11 FORTRAN statements. !SECT is the sector address and
ICYL is the cylinder address computed in step 1:
Interleaving:
!TEMP = ISECT*2
IF (!SECT .GT. 12) !TEMP
!SECT = !TEMP

ITEMP+l

Skew:
I SECT
!SECT
3.

ISECT+{6*ICYL)
MOD (!SECT, 26)

Set the sector number in the range 1 through 26
by the hardware:

required

!SECT = !SECT+ 1
4.

Adjust the cylinder number to cylinder 1 (cylinder 0
used) :
ICYL

3.3

not

ICYL+l

DEVICE INFORMATION

Users can obtain information on all disk device characteristics by
using the $GETCHN and $GETDEV system services (see Section 1.10). The
disk-specific information is returned in the first three longwords and
in the last longword of a user-specified buffer, as shown in Figure
3-1 (Figure 1-9 shows the entire buffer).
Table 3-2 lists the
longword.

device

characteristics

3-5

returned

the

first

DISK DRIVERS
31

8 7

16 15

-------------·-···

device characteristics

& - - - - - - - - - - - - - - - - - - - - . - - - - - · - - - - ------··----!
buffer size

type

class

cylinders

tracks

sectors

t.__~-----~~-I

·----------·- ------~~

disk size in blocks

'-----------·--····-------~------·----

Figure 3-1

__________.

Disk Information

Table 3-2
Disk Device Characteristics

-·
Dynamic Bitsl
(Conditionally Set)

Meaning

DEV$M AVL

Device is on line and available

DEV$M_FOR

Foreign device

DEV$M MNT

Volume mounted

DEV$M_RCK

Perform data check all reads

DEV$M WCK

Perform data check all writes

Static Bits l
(Always Set)

Meaning
.,.. .........

DEV$M FOD

File-oriented device

DEV$M IDV

Device is capable of input

DEV$M ODV

Device is capable of output

DEV$M RND

Device is capable of random access

DEV$M SHR

Device is shareable

·--'-·-----··-1. Defined by the $DEVDEF macro.

--~,-·

3-6

__ __
._,,,,,.

DISK DRIVERS
The second longword contains information on the device class and type,
and the buffer size. The device class for disks is DC$ DISK and the
device types are:
Device Type

Disk

DT$ RM03

RM03

DT$ RP05

RP05

DT$ RPOn

RPOn

DT$ RK06

RKOn

DT$ RK07

RK07

DT$ RXOl

RXOl

The $DCDEF macro defines the device type and class names. The buffer
size is the default to be used for disk transfers (this default is
normally 512 bytes).
The third longword contains information on the number of cylinders per
disk, the number of tracks per cylinder, and the number of sectors per
track.
The last longword contains the maximum number of blocks (1 block
bytes) that can be contained on the disk.

3.4

512

DISK FUNCTION CODES

VAX/VMS disk drivers can perform logical, virtual,
functions.

and

physical

I/O

Logical and physical I/O functions allow access to volume storage and
require only that the issuing process have access to the volume.
Virtual I/O functions require intervention by an Ancillary Control
Process (ACP) and must be executed in a prescribed order. The normal
procedure is to create a file and access it.
Information is then
written to the file and the file is deaccessed.
The file is
subsequently accessed, the information is read, and the file is
deaccessed.
The file is deleted when the information it contains is
no longer useful.
Any number of blocks (up to a maximum of 64K bytes) can be read or
written by a single request. The number itself has no effect on the
applicable quotas (direct I/O, buffered I/O, and AST).
Reading or
writing 1 block or 10 blocks subtracts the same amount from the quota.
The volume to which a logical or virtual function is directed must be
mounted in order for the function to actually be executed. If it is
not mounted, either a "device not mounted" or "invalid volume" status
is returned in the I/O status block.
Table 3-3 lists the logical, virtual, and physical disk I/O functions
and their function codes. Chapter 9 describes the QIO level interface
to the disk device ACP.

3-7

DISK DRIVERS
Table 3-3
Disk I/O Functions

r---------------,..-----,_,________.,·-----·----,-----·-·--Function Code and
Typel
Function
Function
Arguments
Modifiers
t---------------+----+---------·---+-- _________,_____
IO$· CREATE Pl,[P2] ,[P3],[P4],[PS]

IO$M CREATE
IO$M-ACCESS
IO$M-DELETE

Create a directory
entry or a file

IO$ ACCESS Pl, [P2] ,[P3], [P4], [PS]

IO$M CREATE
IO$M-ACCESS

Search a directory
for a specified
file and access
the file if found

IO$ DEACCESS Pl,[P2] ,[P3], [P4], [PS]

Deaccess a file
and if specified,
write final attributes in the file
header

IO$ MODIFY Pl, [P2] ,
[P3], [P4], [PS]

Modify the file
attributes and/or
allocation

IO$ DELETE Pl,[P2] ,[P3], [P4], [PS]

IO$M DELETE

Remove a directory
entry and/or file
header

IO$_ACPCONTROL Fl,[P2], [P3], [P4], [PS]

IO$M DMOUNT

Perform miscellaneous control
functions (see
Section 9.3)

IO$ MOUNT

Informs ACP when
volume is mounted;
requires mount
privilege

IO$ READVBLK Pl,P2,P3

IO$M DATACHECK2 Read virtual block
IO$M-INHRETRY

IO$ READLBLK Pl,P2,P3

IO$M DATACHECK2 Read logical block
IO$M-INHRETRY

IO$ READPBLK Pl,P2,P3

IO$M DATACHECK2 Read physical block
IO$M-INHRETRY
IO$M-INHSEEK 2

IO$ WRITEVBLK Pl,P2,P3

IO$M DATACHECK2 Write virtual block
IO$M-INHRETRY

IO$ WRITELBLK Pl,P2,P3

IO$M DATACHECK2 Write logical block
IO$M-INHRETRY

1. V = virtual;

logical;

physical

2. Except for RXOl
(continued on next page)

3-8

DISK DRIVERS
Table 3-3 (Cont.)
Disk I/O Functions
Typel

Function Code and
Arguments

Function
Modifiers

Function

IO$ WRITEPBLK Pl,P2,P3

IO$ SETMODE Pl

Set disk characteristics for subsequent operations

IO$ SETCHAR Pl

Set disk characteristics for subsequent operations

IO$ SENSEMODE

Sense the devicedependent
characteristics
and return them in
the I/O status
block

IO$ SENSECHAR

Sense the devicedependent
characteristics
and return them in
the I/O status
block

IO$ SEARCH Pl

Search for specif ied block or
sector

IO$ PACKACK

Initialize volume
valid

IO$ SEEK Pl

Seek to specified
cylinder

Verify data
written to disk by
a previous write
QIO

IO$M DATACHECK2 Write physical
IO$M-INHRETRY
block
IO$M-INHSEEK 2

IO$ WRITECHECK Pl,P2,P3

1. V = virtual;

logical;

physical

2. Except for RXOl
The
function-dependent
arguments
for
IO$ CREATE,
IO$_DEACCESS, IO$_MODIFY, and IO$ DELETE are:
address

the

•

Pl
the
descriptor.

•

P2
the address of the file name string
descriptor
(optional).
If specified,
the name
is entered in the
directory specified by the FIB.

3-9

File

Information

IOS_ACCESS,
Block

(FIB)

DISK DRIVERS

•

P3 -- the address of the word that is to receive the length of
the resulting file name string (optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resulting file name string (optional).

the
• PS(optional).

address of a list of attribute
descriptors
If specified, the indicated attributes are read
IO$_DEACCESS,
and
(IO$ ACCESS), or written (IO$_CREATE,
IO$_MODIFY).

(See Chapter 9 for more information on these functions.)
The function-dependent arguments for
IO$_WRITEVBLK, and IO$_WRITELBLK are:

IO$_READVBLK,

IO$_READLBLK,

•

Pl -- the starting virtual address of the buffer that is to
receive the data in the case of a read operation; or, in the
case of a write operation, the virtual address of the buff er
that is to be written on the disk.

•

P2 -- the number of bytes that are to be read from the disk,
or written from memory to the disk. An even number must be
specified if the controller is an RK611, RLll or RX211.

•

P3 -- the starting virtual/logical disk address of the data to
be transferred in the case of a read operation; or, in the
case of a write operation, the disk address of the area that
is to receive the data.
In a virtual read or write, the address is expressed as a
block number within the file, that is, block 1 of the file is
virtual block 1.
(Virtual block numbers are converted to
logical block numb~rs via mapping windows set up by the file
system ACP process.)
In a logical read or write, the address is expressed as a
block number relative to the start of the disk. For example,
the first sector on the disk contains (at least the beginning
of) block O.

The function-dependent arguments for IO$_WRITECHECK, IO$_READPBLK, and
IO$ WRITEPBLK are:
•

Pl -- the starting virtual address of the buffer that is to
receive the data in the case of a read operation; or in the
case of a write operation, the starting virtual address of the
buffer that is to be written on the disk.

•

P2 -- the number of bytes that are to be read from the disk,
or written from memory to the disk. An even number must be
specified if the controller is an RK611, RLll, or RX211.

•

P3 -- the starting physical disk address of the data to be
read in the case of a read operation; or, in the case of a
write operation, the starting physical address of the disk
area that is to receive the data. The address is expressed as
sector, track, and cylinder in the format shown in Figure 3-2.

3-10

DISK DRIVERS
31

16 15

8 7

--~I-t-rack-~l

---cyl-inde_r

P3:

Figure 3-2

__
sect-or

Starting Physical Address

The function-dependent argument for IO$ SEARCH is:
•

Pl -- the physical disk address to position to.
The address
is expressed as sector, track, and cylinder in the format
shown in Figure 3-2.

The function-dependent argument for IO$ SEEK is:
•

Pl -- the physical cylinder number to position to.
address is expressed in the format shown in Figure 3-3.

1615

not used

Figure 3-3

The

cylinder

Physical Cylinder Number Format

The function-dependent argument for IO$ SETMODE and IO$ SETCHAR is:
•

3.4.1

Pl
the
descriptor

address

quadword

device

characteristics

Read

This function reads data into a specified buffer from disk starting at
a specified disk address.
VAX/VMS provides three read function codes:
•

IO$ READVBLK - read virtual block

•

IO$ READLBLK - read logical block

IO$ READPBLK - read physical block

If a read virtual block function is directed to a volume that is
mounted foreign, the function is converted to read logical block. If
'a read virtual block function is directed to a volume that is mounted
structured, the volume is handled in the normal manner for a
file-structured device.
Three function-dependent arguments are used with these codes: Pl, P2,
and P3.
These arguments were described above, in the beginning of
Section 3.4.

3-11

DISK DRIVERS
The data check function modifier (IO$M DATACHECK) can be used with all
read functions. If this modifier is specified, a data check operation
is performed after the read operation has been completed.
A data
check operation is also performed if the volume read, or the volume on
which the file resides (virtual read), has the characteristic "data
check all reads." Furthermore, a data check is performed after a
virtual read if the file has the attribute "data check on read." The
RXOl driver does not support the data check function.
The read check function and the data check function modifier to a dis•
or tape can return five error codes in the I/O status block:
SS$ NORMAL, SS$ CTRLERR, SS$ DRVERR, SS$ MEDOFL, and SS$ NONEXDRV. If
no errors are detected, the disk or tape-data is considered reliable.
The inhibit retry function modifier (IO$M INHRETRY) can be used with
all read functions. If this modifier is specified, all error recovery
attempts are inhibited.
IO$M INHRETRY
takes
precedence
over
IO$M DATACHECK.
If both are specified and an error occurs, there is
no attempt at error recovery and no data check operation is performed.
If an error does not occur, the data check operation is performed.

3.4.2

Write

This function writes data from a specified buffer to disk starting
a specified disk address.

VAX/VMS provides three write function codes:

• IO$ WRITEVBLK - write virtual block
• IO$ WRITELBLK - write logical block
• IO$ WRITEPBLK - write physical block
If a write virtual block function is directed to a volume that is
mounted foreign, the function is converted to write logical block. If
a write virtual block function is directed to a volume that is mounted
structured, the volume is handled in the normal manner for a
file-structured device.
Three function-dependent arguments are used with these codes: Pl, P2,
and P3.
These arguments were described above, in the beginning of
Section 3.4.
The data check function modifier (IO$M DATACHECK) can be used with all
write functions.
If this modifier- is specified, a data check
operation is performed after the write operation has been completed.
A data check operation is also performed if the volume written, or the
volume on which the file resides
(virtual
write),
has
the
characteristic "data check all writes." Furthermore, a data check is
performed after a virtual write if the file has the attribute "data
check on write." The RXOl driver does not support the data check
function.
The inhibit retry function modifier (IO$M INHRETRY) can be used with
all write functions.
If this modifier is specified, all error
recovery attempts are inhibited. IO$M INHRETRY takes precedence over
IO$M DATACHECK.
If both are specified and an error occurs, there is
no attempt at error recovery and no data check operation is performed.
If an error does not occur, the data check operation is performed.

3-12

DISK DRIVERS
3.4.3

Set Mode

Set mode operations affect the operation and
associated disk device.
VAX/VMS defines
functions:
•

Set Mode

•

Set Characteristic

characteristics of the
two types of set mode

3.4.3.1 Set Mode - The Set Mode function affects the operation and
characteristics of the associated disk device. Set Mode is a logical
I/O function and requires the access privilege necessary to perform
logical I/O. A single function code is provided:
IO$ SETMODE
This function takes the following
(other arguments are not valid):

device/function-dependent

argument

Pl -- the address of a characteristics buffer
The Pl argument points to a quadword block shown in Figure 3-4.
16 15

8 7

buffer size

not used

tracks

cylinders

Figure 3-4

sectors

Set Mode Characteristics Buffer

The buffer size is the default for disk transfers (this default is
normally 512 bytes).
The second longword of the buffer contains
information on the cylinder, track, and sector configuration of the
particular device;
that is, number of cylinders per mass storage
media vol~me (bits 31:16), number of tracks per cylinder (bits 15:8),
and number of sectors per track (bits 7:0).

3.4.3.2 Set Characteristic - The Set Characteristic function affects
the characteristics of the associated disk device. Set Characteristic
is a physical I/O function and requires the access privilege necessary
A single function code is
to perform physical I/O functions.
provided:
IO$ SETCHAR
This function takes the following
(other arguments are not valid):

device/function-dependent

argument

Pl -- the address of a characteristics buffer
The Pl argument points to a quadword block as shown in Figure 3-5.

3-13

DISK DRIVERS
31

16 15

buffer size

type

class

cylinders

tracks

sectors

--~

Figure 3-5

Set Characteristic Buffer

The device class for disks is DC$ DISK.
Disk types are listed in
Section 3.3. The buffer size is-the default for disk transfers (this
default is normally 512 bytes). The second longword of the buffer
contains information on the cylinder, track, and sector configuration
of the particular device; that is, number of cylinders per mass
storage media volume (bits 31:16), number of tracks per cylinder (bits
15:8), and number of sectors per track (bits 7:0).

3.4.4

Sense Mode

Sense
mode
operations
obtain
current
disk
device-dependent
characteristics and return them to the caller in the second longword
of the I/O status block (see Figure 3-7). VAX/VMS provides a single
function code:
IO$ SENSEMODE - Sense Mode
Sense Mode is a logical I/O function and requires the access privilege
necessary
to perform logical I/O.
No device/function-dependent
arguments are used with IO$ SENSEMODE.

3.4.5

Pack Acknowledge

This function sets the volume valid bit for all disk devices.
Pack
acknowledge is a physical I/O function and requires the access
privilege to perform physical I/O.
A single function code is
provided:
IO$ PACKACK
This function code takes no function-dependent arguments.
IO$ PACKACK must be the first function issued when a volume (pack,
cartridge, or diskette)
is placed in a disk drive. IO$ PACKACK is
issued automatically when the INITIALIZE or MOUNT command language
commands are issued.

3.5

I/O STATUS BLOCK

Figure 3-6 shows the I/O status block (IOSB) for all disk device QIO
functions except Sense Mode. Figure 3-7 shows the I/O status block
for Sense Mode. Table 3-4 lists the status returns for all functions
and devices.

3-14

DISK DRIVERS

16 15

byte count

status

device-dependent data

Figure 3-6

IOSB Content
87

16 15

status

cylinders

Figure 3-7

sectors

tracks

IOSB Content - Sense Mode

The byte count is the actual number of bytes transferred to or from
the
process
buffer.
Table
3-2 (in Section 3.3) lists the
device-dependent data returned in the second longword.
The second longword of the I/O status block for the Sense Mode and
Sense Characteristic functions returns information on the cylinder,
track, and sector configuration for the particular device.
Table 3-4
Status Returns for Disk Devices
Status

Meaning

SS$ NORMAL

Successful completion of the operation specified
in the QIO request. The second word of the IOSB
can be examined to determine the actual number of
bytes transferred to or from the buffer.

SS$ CTRLERR

Controller-related error.
For example, one or
more of the following conditions can cause this
error:
Late data
Error confirmation
Invalid map register
Interface timeout
Missed transfer
Programming error
Read timeout
(continued on next page)

3-15

DISK DRIVERS
Table 3-4 (Cont.)
Status Returns for Disk Devices
Status

Meaning

SS$ DATACHECK

Data check error. A mismatch between the data in
memory and the data on disk was detected during a
data check operation (see Section 3.2.1).

SS$ DRVERR

Drive-related error. For example, one or more
the following conditions can cause this error:

Driver timing error
Illegal function
Illegal register
Operation incomplete
Register modify refused
Write clock failure
SS$ FORMAT

Format error. Format specified by driver does not
correspond
to format as specified in sector
headers. Disk has been formatted for another
computer, such as DECsystem-20.

SS$ INBUFLEN

Invalid buffer length. The byte count must
even for UNIBUS disk devices, that is, RK07.

SS$ IVADDR

Invalid disk address error.
Either an invalid
starting disk address or a disk address that was
incremented causes this error. This error occurs
for physical read and write operations or as the
result of a hardware error.

SS$ MEDOFL

Medium offline.
The addressed drive currently
does not have a volume mounted and on line.

SS$ NONEXDRV

Nonexistent drive. The addressed drive does not
exist or the drive select plug has been removed.

SS$ PARITY

Parity error. For example, one or more of
following conditions can cause this error:

the

Drive parity error
ECC hard error
Header compare error
Map parity error
Header CRC error
MASSBUS control parity error
MASSBUS data parity error

,___________-+------------------------------,-----------'
(continued on next page)

3-16

DISK DRIVERS
Table 3-4 (Cont.)
Status Returns for Disk Devices
Status

Meaning
drive is currently
any operation as the

SS$ UNSAFE

Drive unsafe. The addressed
unsafe and cannot perform
result of a hardware error.

SS$ VOLINV

Volume invalid. The addressed drive has not been
mounted and therefore does not have volume valid
set, or a status change has occurred in the drive
so
that it has changed to an unknown, and
therefore, invalid state. All logical and virtual
functions will return this status until volume
valid is set.
Volume valid is set when
a
IO$ PACKACK function is executed (usually by the
MOUNT command language command) and cleared when
the volume is unloaded, the respective drive
changes to an unknown state, or the power fails.
The driver automatically sets volume valid when
the proper volume is mounted and/or power is
restored.

SS$ WASECC

Data check not performed. The function was a read
data that was completed successfully by applying
one or more ECC corrections. The specified data
check, however, was not performed.

SS$ WRITLCK

Write lock error. An attempt was made to write on
a
write
locked
drive.
Volume is hardware
protected.

3-17

DISK DRIVERS
3.6

PROGRAMMING EXAMPLE

The following program provides an example of optimizing access time to
a disk file.
The program creates a file using VAX-11 RMS, stores
information concerning the file, and closes the file.
The program
then accesses the file and reads and writes to the file using the
Queue I/O system service •
• rITLE
• fDENT

Disk Driver Proqramming ~xample
/011

oetine necessary symbols
;Uefine file Information Block Offsets
;Uefine 110 function codes
;Uefine RMS•32 Return Status Values

SFIRD~F

SIODEF
SRMSDEF

Local storage
Define number of records to be processed
;One hundred records

NUM-RECS=lOO

Allocate storaqe for necessary data structures
Allocate File Access Block
A file access block is required by RMS•32 to open and close a tile.
FAB-BLUCK:
SFAB

;

= 100,AL8
PUT •
FA
= FILE-NAME,FNA =
fNS = FILE-SIZE,•
FOP = CTG,•
MRS = 512,NA,,. = NAM-BLOCK,•
ORG = SEQ,•
RFM = FIX

; Initial tile size is to be 100 blocks
;File Access Tipe is output
;file name str ng address
;file name str ng size
;file is to be contiguous
;Maximum record size is s1i bytes
;File name olock address
;File or~anization is to be sequential
;Hecord ormat is fixed length

Allocate file information block
A file information block 1s required as an argument in the Queue l/O
system service call that accesses a tile.
flB-BLUCK:
.HLKB

F' l8$K_LENGTH

Allocate file information block descriptor
l'lB-DESCR:
.LONG
.LONG

FIBSK-LENGTH
FIB-BLOCK

iLength ot file information block
;Address of file information block

Allocate File Name Block
A file name block is required by RMS•32 to return information concerning
a file ce.q. the resultant tilename string after logical name translation
and defaults have been applied).
NAM-BLOCK:
SNAM
Allocate Record Access MlocK
A record access block is required by RMS•32 for record operations on a
t !le.
HAB-HLOCK:
SRAB

fAB : FAH-BLOCK,•
RAC
Riff ~ ~~86;o_BUFF~H,•
RSZ = 512

;file access block address
;Record access is to be sequential
;Hecord butter address
;Record buffer size

Allocate direct access butter
BLOCK-BUFFER:
.BLKB

1024

:oirect access butter is 10i4 bytes

Allocate space to store channel number returned by the Assign Channel system
service

3-18

DISK DRIVERS
DEVICE:-CHANNEL:
.BLKW
Allocate device
DEVICl::-DESCR:
10$:
20$:

.LONG
.LOt.JG

.ASCII

n&~e

string and descriptor

20$•10$
10$
/SYSSnISK/

;Length ot device name string
;Address ot device name string
;Device on which created tile will reside
;Reference label to calculate length

! Allocate file name string and define string length symbol
F lLl::-NAME:
;
•. ASCil /SYSSDISK:MYDA.TM'IL.DA'f/ ;File name string
FlLl::-SlZE=.-FILE-NAME
;file name string length

.; Allocate l/O status quadword storage

,
;

ro_sTATUS:
.BLKQ
Allocate output record butter
RJ:;CORD-BUFFER:
.BLKB

512

iRecord butter is 512 bytes

; Program starting point
,f The general logic of the program is to create a file called M¥DATAFIL.DAT
~using RMS•32t store information concerning· the file, write 100 records each
, ot wnich contains its record numoer in every byte, close the file, and then
access and read and write the file directly using the Queue 1/0 system service.
It any errors are detected the program returns to its caller with the final
error status in reqister R6•
• ENTRY

DISK-EXAMPLE,-M<R2,R3,R4,R5,R6> ;Program starting address

First create the file and open it using RMS•32
$CREATE FAB = FAB-BLOCK
BLBC
R0,20$

;First part of example
;Create and open file
;It low bit clear, creation failure

second connect the record access block to the created tile
$CONNECT RAA = RAB-BLOCK
ALBC
R0,30$

;connect the record access block
;It low bit clear, connection failure

Now write 100 records each containing its record number
;set record write loop count
Fill each byte ot the record to oe written with its record number

10$:

SURIB
MOVCS

Next write

R6,#NUM_RECS+1,R~

;Calculate record number
;Fill record butter

#0,(R6),R5,#512,Ri::CO~D-BUFFER

th~

$PUT
ALBC

SOBGTR

record into the newly created file using RMS•32
RAB : RAB-BLOCK
R0,30$
R6,10S

;Put record in file
;If low bit clear, put failure
;Any more records to write?

The file creation part of the example is almost complete. All that remains to
be done is to store the tile information returned by RMS•32 and close the tile.
MOVW
MOVW
MOVW
SCLOSE
BLBS
RET

NAM-BLOCK+NAMSW-FID,FIB-BLOCK+FIBSW-FlD 6·save file identification
NAM-BLOCK+NAMSW-fID+2,FIB-BLOCK+FIB$w_FI +2 ;Save sequence number
NAM_BLOCK+NAM$W-FlD+4,rIB-BLOCK+FIB$W_FID+4 ;save relative volume
FAB = FAB-BLLJCK
;Close tile
RO,PART-2
;lf low bit set 1 successful close
;Return with RM~ error status

3-19

DISK DRIVERS
Record stream connection or put record failure
Close file and return status
30S:

PUSHL
SC LOSE
POPL
RET

RO
RO

;save error status
;Close tile
;Retrieve error status
;Return with RMS error status

FAB : FAB-BLUCK

The second part of the example illustrates accessing the previously created
file directly using the Queue l/O system service, randomly reading and writing
various parts of the file, and then deaccessing the file.
rirst assiqn a channel to the appropriate device and access the tile
PART-~:

10$:
20s:

$ASSIGN_S DEVNAM = DEVICE-DESCR,~ ;Assign a channel to file device
CHAN : DEVICE-CHANNEL
;
BLBC
RO 20s
;If low bit clear, assignment failure
MOVL
#FfBsM_NOWRITE!flBSM-WRlTE,- ;Set tor read/W~ite access
FIB-BLUCK+FIBSL-ACCTL
;
SOIO~ s CHAN = DEVICE-CHANN~L - ;Access file on devic~ channel
- FUNC = #IOS-ACCESS!IO~M-ACCESS,- ;I/O function is access file
IOSB = IO_STATUS,-;Address Of I/O status quadword
Pl = FIB-DESCR
;Address of information block descriptor
HLBC
R0,10$
;If low bit clear, access failure
MOVZWL IO_STATUS,RO
;Get final 1/0 completion status
tlLHS
R0,30$
PVSHL
RO
$DASSGN_S CHAN :
POPL
RO
RET

DEVIC~-CHANNEL

;If low bit setf. successful l/O function
;save error sta us
;Deassign file device channel
;Retrieve error status
;Return with 1/0 error status

The tile is now ready to be read and written randomly. Since the records are
fixed length and exactly one block long, the record number corresponds to the
virtual block number ot the record in the tile. Thus a particular record can
be read or written simply by specifying its record number in the file.
The tollo~ing code reads 2 records at a time and checks to see that they contain
their respective record numbers in every byte. The records are then written back
into the tile in reverse order. This results in record 1 having the old contents
ot record 2 and record 2 the old contents ot record 1 f.etc. After the example
has been run, it is ~uggested that the file dump utili y be used to verify this
tact.
30$:

MOVZBL

;set starting record (block) number

#l,R6

! Read next 2 records into block buffer
,
sorow_s CHAN = DEVICE-CHANNEL,- ;Read next 2 records from file channel
40$:

HSBB

FUNC : #IDS-REAUVBLK,•
IOSB = ro_STATUS,Pl = ALOCK-BUffER,•
P2 : #1024,•
P3 : R6
50$

;110 function is read virtual block

;Address of l/O status quadword
;Address of l/O butter
;Size of l/O buffer
;starting virtual block of transfer
;Check I/O completion status

ChecK each record to make sure it contains the correct data
SKPC
RNEQ
AODL3
SKPC
BNEQ

R6,#512,8LOCK-8UffEH
;Skip over equal record numbers in data
60$
;rt not equal, data match failure
#1,R6,R5
;Calculate even record numoer
R5,#512,BLUCK-BUfFER+512 ;Skip over equal record numbers in data
oos
;It not equal, data match failure

Record data matches
write records in reverse order in file
SQID~-S

CHAN
FUNC
IOSB
Pl :

DEVICE-CHANNEL,•
#IOS-WRITtVBLK,•
ID-STATUS,•
LOCK-BUffER+512,•

write even numbered record in odd slot
Address of l/O status quadword
Address of even record butter
110 tunction is write virtual block

3-20

DISK DRIVERS
;Length of even record buffer
;Record number of odd record
;Check 1/0 completion status
ADDL3
;Calculate even record number
$QIOW_S CHAN = DEVICE-CHANNEL,- ;write odd numbered record in even slot
FUNC = #IO$-WRITEVBLK,• ;110 function is write virtual block
;Address of l/O status quadword
~~s~ BL~gK:~fii~~R:;Address of odd record butter
P2 = #512,;Length of odd record butter
P3 : RS
;Record number of even record
50$ BSBB
;Check 1/0 completion status
ACBB
#NUM-RECS•1,#2,R6,40$
;Any more records to be read?
P2 :

BSBB

BRB

P3 :

#512,-

50$
#1,R6,R5

70$

Check 1/0 completion status
~0$:

BLBC
ALBC

MOVZWL
RSB

low bit clear, service failure
;Get final I/O completion status

R0,70$

;It

R0,70$

!lf low bit clear, I/O function failure

IO_STATUS,RO

Record number mismatch in data
bOS:

MNEGL

;set dummy error status value

#4,RO

All records have been read, verified, and odd/even pairs inverted
70$:

PUSHL
RO
SQIOW_S CHAN : DEVICE-CHANNEL,•
FUNC : #10$-DEACC~SS
SDASSG~-S CHAN : DEVlCE-CHANN~L
POPL
RO
RET
.END
DISK-EXAMPLE

Save final status
oeaccess t Ue
1/0 function is deaccess tile
Deassiqn tile device channel
Retrieve final status

3-21

CHAPTER 4
MAGNETIC TAPE DRIVER

This chapter describes the use of the VAX/VMS magnetic tape driver.
This driver supports the devices listed in Table 4-1 and detailed in
Section 4.1.
Table 4-1
Magnetic Tape Devices

Model

No. of
Tracks

Recording
Density
{bpi)

Tape
Speed
{ips)

TE16

800 or
1600

TSll

800 or
1600

TU45

800 or
1600

TU77

800 or
1600

125

1. NRZI

4.1

non-return-to-zero-inverted;

SUPPORT~D

Max. Data Transfer Recording
Rate in Bytes Per Method
Second
36,000 {for 800
bpi); 72,000 {for
1600 bpi)
3fi,OOO {for 800
bpi); 72,000 {for
1000 bpi)
fi0,000 {for 800
bpi) 120,000
{for 1600 bpi)

NRZI or
PEl

100,000 {for 800
bpi) 200,000
{for 1600 bpi)

NRZI or
PE

phase encoded.

MAGNETIC TAPE DEVICES

The following sections describe the magnetic tape
detail.

4.1.1

NRZI or
PE

drives

greater

TE16 Magnetic Tape Drive

The TE16 magnetic tape drive holds one, 2400-foot, 9-track reel with a
capacity of 40 million characters. The drive reads data at 45 inches
per second with an average transfer time of 14 microseconds per byte
at the 1600 bpi density. Up to eight drives can be connected to each
TM03 controller.

4-1

MAGNETIC TAPE DRIVER
TSll Magnetic Tape Subsystem

4.1.2

The TSll Magnetic Tape is a phase-encoded, 9-track magnetic
subsystem that operates under microprocessor control.
The
consists of one TSll controller and one TS04 drive.

tape
TSll

TU45 and TU77 Magnetic Tape System

4.1.3

The TU45 and TU77 are phase-encoded, 9-track magnetic tape systems
with a capacity of 40 million characters. Tape density and character
format are program selectable.

4.2

DRIVER FEATURES AND CAPABILITIES

The VAX/VMS magnetic tape driver provides the following features:
•

Multiple master adapters and slave formatters

•

Different types of devices on a single MASSBUS
example, RPOS disk and TM03 tape formatter

•

Reverse read and reverse data check functions (not for TSll)

•

Data checks on a per-request,
basis (not for TSll)

•

Full recovery from power failure for online drives
volumes mounted, including repositioning by the driver

•

Extensive
error
recovery
algorithms;
for
non-return-to-zero-inverted (NRZI) error correction

•

Logging of device errors in a file that may
field service or customer personnel

•

Online diagnostic support for drive level diagnostics

per-file,

adapter;

and/or

for

per-volume
with

example,

displayed

The following sections describe master and slave controllers, and data
check and error recovery capabilities in greater detail.

4.2.1

Master Adapters and Slave Formatters

VAX/VMS supports the use of multiple master adapters of the same type
on a system. For example, more than one MASSBUS adapter (MBA) can be
used on the same system. A master adapter is a device controller
capable of performing and synchronizing data transfers between memory
and one or more slave formatters.
VAX/VMS also supports the use of multiple slave formatters per master
adapter on a system. For example, more than one TM03 Magnetic Tape
Formatter per MBA can be used on a system. A slave formatter accepts
data and/or commands from a master adapter and directs the operation
of one or more slave drives. The TM03 is a slave formatter. The TEln
Magnetic Tape Transport is a slave drive.

4-2

MAGNETIC TAPE DRIVER
Data Check

4.2.2

A data check is made after successful completion of an I/O operation
to compare the data in memory with that on the tape. After a write or
read (forward) operation, the tape drive backspaces and then performs
a write check data operation. After a read in the reverse direction,
the tape drive forward spaces and then performs a write check data
reverse operation.
With the exception of the TSll, magnetic tape
drivers support data checks at three levels:
•

Per request -- Users can specify the data check function
modifier (IO$M DATACHECK) on a read logical block, write
logical block, read virtual block, write virtual block, read
physical block, or write physical block I/O function.

•

Per volume -- Users can sp~cify the characteristics "data
check all reads" and/or "data check all writes" when the
volume is mounted. The VAX/VMS Command Language User's Guide
describes volume mounting and dismounting.

•

Per file -- Users can specify the file attributes "data check
on read" or "data check on write." File access attributes are
specified when the file is accessed. Chapter 9 of this manual
and the VAX-11 Record Management Services Reference Manual
describe file access.

Error Recovery

4.2.3

Error recovery in VAX/VMS is aimed at performing
operations to complete an I/O operation successfully.
error recovery operations fall into two categories:
•

Handling special
interrupt timeout

conditions

such

power

•

Retrying nonfatal controller and/or drive errors

all possible
Magnetic tape
failure

The error recovery algorithm uses a combination of these two types
error recovery operations.

and

Power failure recovery consists of waiting for mounted drives to be
unloaded by the operator. When the drives are reloaded, the driver
automatically spaces to the position held before the power failure.
The I/O operation that was in progress at the time of the power
failure is then re-executed. To solicit reloading of mounted drives,
device not ready messages are sent to the operator console after a
power failure.
Device timeout is treated as a fatal error with a loss of tape
position.
A tape on which a timeout has occurred must be dismounted
and rewound before the drive position can be established.
Nonfatal controller/drive errors are simply re-executed up to lfi times
before returning a fatal error. The tape is repositioned as necessary
before each retry.
All normal error recovery (nonspecial conditions) can be inhibited by
specifying the inhibit retry function modifier (IO$M INHRETRY). If
any error occurs and this modifier is specified, the- operation is
immediately terminated, and a failure status is returned. This
modifier has no effect on power failure and timeout recovery.

4-3

MAGNETIC TAPE DRIVER

Up to 16 extended interrecord gaps can be written during the error
recovery for a write operation. Except for the TSll, writing of these
gaps can be suppressed by specifying the inhibit extended interrecord
gap function modifier (IO$M_INHEXTGAP).

4.3

DEVICE INFORMATION

Users can obtain information on device characteristics by using the
$GETCHN
and
$GETDEV system servi~es (see Section 1.10).
The
information is returned in a user-specified buffer shown in Figure
4-1. Only the first three longwords of the buffer are shown in Figure
4-1 (Figure 1-8 shows the entire buffer).
8 7

16 15

device characteristics

buffer size

··················-·····ty·······P··e··

device-dependent information

Figure 4-1

Magnetic Tape Information

The device characteristics returned in the first longword
in Table 4-2.

are

listed

Table 4-2
Magnetic Tape Device-Independent Characteristics

------------'"-T"----------------------·-----Dynamic Bits 1
(Conditionally Set)

Meaning

-------------+---·--~~~----·····------···-----------t

DEV$M AVL

Device is on line and available

DEV$M FOR

Foreign volume

DEV$M MNT

Volume mounted

DEV$M RCK

Perform data check all reads

DEV$M WCK

Perform data check all writes

Static Bitsl
(Always Set)
DEV$M FOD

File-oriented device

DEV$M IDV

Device is capable of input

DEV$M ODV

Device is capable of output

DEV$M_SQD

Device is sequential access

-------------··--- --··-----------------------·-·--·-----·-·----··-..-·--.......... ..
1. Defined by the $DEVDEF macro.

4-4

MAGNETIC TAPE DRIVER

The second longword contains information on device class and type, and
the buffer size. The device class for tapes in DC$ TAPE. The device
type is DT$_TE16 for the TE16 and DT$_TS11 for the TSll.
The $DCDEF macro defines the device type and class names. The buffer
size is the default to be used for tape transfers (this default is
normally 2048 bytes).
The third longword contains device-dependent information.
Table 4-3
lists this information. The $MTDEF macro defines the values listed.
Table 4-3
Device-Dependent Information for Tape Devices
Value

Meaning

MT$M LOST

If set, the current tape position is unknown.

MT$M_HWL

If
set,
the
write-locked.

MT$M_EOT

If set, an end-of-tape (EOT)
condition
was
encountered by the last operation to move tape in
the forward direction.

MT$M EOF

If set, a tape mark was encountered
operation to move tape.

MT$M BOT

If set, a beginning-of-tape (BOT) marker was
encountered by the last operation to move tape in
the reverse direction.

MT$M PARITY

If set, all data transfers are performed with even
parity.
If
clear
(normal case), all data
transfers are performed with odd parity.
Only
NRZI recording at 800 bpi can have even parity.

MT$V DENSITY
MT$S-DENSITY

Specifies the density at which all data transfer
operations are performed. Possible density values
are:

MT$V FORMAT
MT$S=FORMAT

drive

hardware

the

MT$K_PE_ln00

Phase encoded, lnOO bpi.

MT$K_NRZI_800

Non-return-to-zero-inverted,
bpi.

last

800

Specifies the format in which all data transfers
are performed. A possible format value is:
MT$K_NORMAL11

4.4

selected

Normal PDP-11 format. Data bytes
are recorded sequentially on tape
with each byte occupying exactly
one frame.

MAGNETIC TAPE FUNCTION CODES

The VAX/VMS magnetic tape driver can
physical I/O functions.

4-5

perform

logical,

virtual,

and

MAGNETIC TAPE DRIVER
Logical and physical I/O functions to magnetic tape devices allow
sequential access to volume storage and require only that the
requesting process have direct access to the device.
Virtual I/O
functions require intervention by an ancillary control process (ACP)
and must be executed in a prescribed order. The normal procedure is
to create a file and access it. Information is then written to the
file and the file is deaccessed. The file is subsequently accessed,
the information is read, and the file is deaccessed. The file can be
written over when the information it contains is no longer useful and
the file has expired.
Any number of bytes (up to a maximum of n4K)
can be read from or
written into a single block by a single request. The number of bytes
itself has no effect on the applicable quotas
(direct I/O, buffered
I/O, and AST). Reading or writing any number of bytes subtracts the
same amount from a quota.
The volume to which a logical or virtual function is directed must be.
mounted in ord~r for the function to actually be executed. If it is
not, either a device not mounted or invalid volum~ status is returned
in the I/O status block.
Table 4-4 lists the logical, virtual, and physical magnetic tape I/O
functions and their function codes. These functions are described in
more detail in the following paragraphs. Chapter 9 describes the QIO
level interface to the magnetic tape device ACP.
Table 4-4
Magnetic Tape I/O Functions
Function Code and
Arguments

Typel

10$ CREATE Pl, [P2] ,[P3], [P4], [PS]

Function
Modifiers

Function

IO$M CREATE
IO$M-ACCESS

Create a file

IO$ ACCESS Pl,[P2] ,[P3], [P4], [PS]

IO$M CREATE
IO$M-ACCESS

Search a tape
for a specified file
and access the file
if found and
IO$M ACCESS is set.
If the file is not
found and IO$M CREATE
is set, create-a file
at end-of-tape

IO$ DEACCESS Pl,[P2] ,[P3], [P4], [PS]

Deaccess a file and,
if the file has been
written, write out
trailer records

IO$ MODIFY Pl,[P2] ,[P3], [P4], [PS]

Write user labels

1. v

virtual; L = logical; P

physical.
(continued on next page)

4-6

MA9NETIC TAPE DRIVER
Table 4-4 (Cont.)
Magnetic Tape I/O Functions
Function Code and
Arguments

Type 1

Function
Modifiers

Function

IO$ READVBLK Pl,P2

IO$ READLBLK Pl,P2

IO$ READPBLK Pl,P2

IO$M DATACHECK 2 Read physical block
IO$M-INHRETRY
IO$M-REVERSE

IO$ WRITEVBLK Pl,P2

IO$M DATACHECK2 Write virtual block
IO$ M-INHRETRY
IO$ M-INHEXTGAP

IO$ WRITELBLK Pl,P2

IO$M DATACHECK2 Write logical block
IO$ M-INHRETRY
IO$M-INHEXTGAP

IO$ WRITEPBLK Pl,P2

IO$M DATACHECK2 Write physical block
IO$M-INHRETRY
IO$M-INHEXTGAP

IO$ REWIND

IO$M INHRETRY
IO$M-NOWAIT

Reposition tape to
the beginning of
tape (BOT) marker

IO$ SKIPFILE Pl

IO$M INHRETRY

Skip past a specified
number of tape marks
in either a forward
or reverse direction

IO$ SKIPRECORD Pl

IO$M INHRETRY

Skip past a specified
number of blocks in
either a forward or
reverse direction

IO$ WRITEOF

IO$M INHRETRY
IO$M-INHEXTGAP

Write an extended
interrecord gap
followed by a tape
mark

IO$ REWINDOFF

IO$M INHRETRY
IO$M-NOWAIT

Rewind and unload the
tape on the selected
drive

1. V = virtual; L

logical; P

IO$M DATACHECK2 Read virtual block
IO$M-INHRETRY
IO$M-REVERSE
IO$M DATACHECK 2 Read logical block
IO$M-INHRETRY
IO$M-REVERSE

physical.

2. Not for TSll

(continued on next page)

4-7

MAGNETIC TAPE DRIVER
Table 4-4 (Cont.)
Magnetic Tape I/O Functions
~---------

-----. ------..------+-----------...--------------.
Type 1

Function
Modifiers

IO$ SENSEMODE

IO$M INHRETRY

IO$ SETMODE Pl

Set tape characteristics for subsequent
operations

IO$ SETCHAR Pl

Set tape characteristics for subsequent
operations

IO$ ACPCONTROL Pl,[P2] ,[P3],[P4],[PS]

IO$ MOUNT

Function Code and
Arguments

IO$M DMOUNT

Sense the tape
characteristics
and return them
in the I/O status
blOck

Perform miscellaneous
control functions
(see Section 9.3)
Informs ACP when
volume is mounted;
requires mount
privilege.

physical.

virtual; L = logical; P

The
function-dependent
arguments
IO$_DEACCESS, and IO$_MODIFY are:
address

Function

the

for

IO$_CREATE,

IO$_ ACCESS,

File

Information

Block

•

Pl
the
descriptor.

•

P2
the address of the file name string
descriptor
(optional). If specified with IO$ ACCESS, the name identifies
the file being sought. If specified with IOS_CREATE, the name
is the name of the created file.

•

P3 -- the address of the word that is to receive the length of
the resultant file name string (optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string (optional).

the
• PS(optional).

(FIB)

address of a list of attribute
descriptors
If specified with IO$ ACCESS, the attributes of
the file are returned to the user.
If specified with
IO$ CREATE, PS is the address of the attribute descriptor li~t
for-the new file. All file attributes for IO$ MODIFY are
ignored.

(See Chapter 9 for more information on these functions.)

4-8

MAGNETIC TAPE DRIVER

The function-dependent arguments for IO$ READVBLK,
IO$ READLBLK,
IO$_READPBLK, IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK are:

•

P2 -- the number of bytes that are to be read from
or written from memory to the tape.

The function-dependent argument for
is:
•

IO$ SKIPFILE

and

the

tape,

IO$ SKIPRECORD

Pl -- the number of tape marks to skip over in the case of a
skip file operation;
or, in the case of a skip record
operation, the number of blocks to skip over. If a positive
number is specified, the tape moves forward;
if a negative
number is specified, the tape moves in reverse.
(The maximum
number of tape marks or records that Pl can specify is
32,767.)

Read

4.4.1

This function reads data into a specified buffer in the
reverse direction starting at the next block position.

forward

VAX/VMS provides three read function codes:
•

IO$ READVBLK - read virtual block

•

IO$ READLBLK - read logical block

•

IO$ READPBLK - read physical block

A read virtual block function to a volume that is mounted foreign is
converted to a read logical block function. A read virtual block
function to a volume that is mounted structured is handled in the
normal manner for a file-structured device.
If the reverse function modifier (IO$M REVERSE) is specified, the read
operation is performed in the reverse direction instead of the forward
direction.
The data check function modifier (IO$M DATACHECK) can be used with all
read functions. If this modifier is specified, a data check operation
is performed after the read data operation has been completed.
(A
space reverse or space forward is performed between the read and the
data check operation.) A data check operation is also performed if the
volume read, or the volume on which the file resides (virtual read),
has the characteristic "data check all reads." Furthermore, a data
check is performed after a virtual read if the file has the attribute
"data check on read."
If a read physical block or read logical block operation is performed
and the reverse function modifies IO$M REVERSE is not specified, an
end-of-tape status is returned if either of the following conditions
occur and no other error condition exists:
•

The tape is positioned past the end-of-tape
start of the read operation.

•

The tape enters the end-of-tape region as a result of the read
operation.
4-9

position

the

MAGNETIC TAPE DRIVER

The transferred byte count reflects the actual number of bytes read.
If a read in the reverse direction is performed when the tape is
positioned past the end-of-tape position, an end-of-tape status is not
returned.
If a tape mark is read during a logical or physical read operation in
either the forward or reverse direction, an end-of-file status is
returned if any of the following conditions exist:
•

The tape is positioned past the end-of-tape
start of the read operation.

position

•

The tape enters the end-of-tape region as a result of the read
operation.

•

A tape mark is read as a result of a read operation
tape does not enter the end-of-tape region.

but

the

An end-of-file status is also returned if a read operation in the
reverse direction is attempted when the tape is positioned at the BOT
marker. All conditions that cause an end-of-file status result in a
transferred byte count of zero.
If an attempt is made during a logical or physical read operation to
read a block that is larger than the specified memory buffer, a data
overrun status is returned. Only the first part of the block is read
into the specified buffer.
(Only the latter part of the block is read
into the buffer on a read in the reverse direction.) The transferred
byte count is equal to the actual size of the block. Read reverse
starts at the top of the buffer. Thus, the start of the block is at
Pl plus P2 minus the length read.
It is not possible to read a block that is less than 14 bytes in
length.
Such records are termed "noise blocks" and are completely
ignored by the driver.

4.4.2

Write

This function writes data from a specified buffer to
forward direction starting at the next block position.

tape

the

VAX/VMS provides three write function codes:
•

IO$ WRITEVBLK - write virtual block

•

IO$ WRITELBLK - write logical block

•

IO$ WRITEPBLK - write physical block

If a write virtual block function is to a volume that is mounted
foreign,
it is converted to a write logical block function.
If a
write virtual block function is to a volume that is
mounted
structured, it is handled in the normal manner for a file-structured
device.
The data check function modifier (IO$M DATACHECK) can be used with all
write functions.
If this modifier- is specified, a data check
operation is performed after the write data operation has been
completed.
(A space reverse is performed between the write and the
data check operation.) A data check operation is also performed if the
volume written, or the volume on which the file resides (virtual
write), has the characteristic "data check all writes." Furthermore, a

4-10

MAGNETIC TAPE DRIVER
data check is performed after
attribute "data check on write."

a virtual write if the file has the

A data check operation is also forced by the driver when an error
occurs during a write operation. This ensures that the data can be
reread.
If a write physical block or write logical block operation is
performed, an end-of-tape status is returned if either of the
following conditions occurs and no other error condition exists:
•

The tape is positioned past the end-of-tape
start of the write operation.

•

The tape enters the end-of-tape region
write operation.

position

the

result

the

(The transferred byte count reflects the size of the block written.)
It is not possible to write a block less than 14 bytes in length.
An
attempt to do so results in the return of a bad parameter status for
the QIO request.

Rewind

4.4.3

This function repositions the tape to the beginning-of-tape (BOT)
marker.
If the IO$M NOWAIT function modifier is specified, the I/O
operation is completed when the rewind is initiated.
Otherwise, I/O
completion does not occur until the tape is positioned at the BOT
marker. IO$_REWIND has no function-dependent arguments.

4.4.4

Skip File

This logical I/O function skips past a specified number of tape marks
in either a forward or reverse direction.
A function-dependent
argument (Pl) is provided to specify the number of tape marks to be
skipped, as shown in Figure 4-2.
If a positive file count is
specified, the tape moves forward;
if a negative file count is
specified, the tape moves in reverse.
(The actual number of files
skipped is returned in the I/O status block.)
31

Pl:

16 15

not used

Figure 4-2

file count

IO$ SKIP FILE Argument

Only tape marks (when the tape moves in either direction) and the BOT
marker (when the tape moves in reverse) are counted during a skip file
operation. The BOT marker terminates a skip file function in the
reverse direction. The end-of-tape (EOT) marker does not terminate a
skip file function in either the forward or reverse direction.
Note
that a negative skip file function leaves the tape positioned just
before a tape mark, that is, at the end of a file, unless the BOT
marker is encountered, whereas a positive skip file function leaves
the tape positioned just past the tape mark.

4-11

MAGNETIC TAPE DRIVER
Skip Record

4.4.5

The skip record function skips past a specified number of physical
tape
blocks
in
either
a
forward or reverse direction.
A
device/function-dependent argument (Pl) specifies the number of blocks
to skip,
as shown in Figure 4-3.
If a positive block count is
specified, the tape moves forward;
if a negative block count is
specified~
the ·tape moves in reverse.
(The actual number of blocks
skipped is returned in the I/O status block.)

Figure 4-3

!0$ SKIPRECORD Argument

Skip record is terminated by end-of-file when the tape moves in either
direction,
by the BOT marker when the tape moves in reverse, and by
the EQT marker when the tape moves forward.

Write End-of-File

4.4.6

This function writes an extended interrecord gap (of approximately 3
inches for NRZI recording and 1.5 inches for PE recording) followed by
a tape mark. No device/function-dependent arguments are used with
IO$ WRITEOF.
An end-of-tape status is returned in the I/O status block if either of
the following conditions is present and no oth~r error conditions
occur:

4.4.7

•

A write end-of-file function is executed
positioned past the EQT marker.

while

the

tape

•

A write end-of-file function causes the tape position to enter
the end-of-tape region.

Rewind Offline

The rewind offline function rewinds and unloads the tape on the
selected drive.
If the IO$M NOWAIT function modifier is specified,
the I/O operation is completed as soon as the rewind is initiated. No
device/function-dependent arguments are used with IO$ REWINDOFF.

4.4.8

Sense Tape Mode

This function senses the current device-dependent tape characteristics
and returns them to the caller in the second longword of the I/O
status block (see Table 4-3). The contents of the second longword are
identical to the device-dependent information shown in Figure 4-1. No
device/function-dependent arguments are used with IO$_SENSEMODE.

4-12

MAGNETIC TAPE DRIVER
4.4.9

Set Mode

Set mode operations affect the operation and characteristics of the
associated magnetic tape device.
VAX/VMS defines two types of set
mode functions:
•

Set Mode

•

Set Characteristic

4.4.9.1 Set Mode - The Set Mode function affects the characteristics
of the associated tape device. Set Mode is a logical I/O function and
requires the access privilege necessary to perform logical I/O.
A
single function code is provided:
IO$ SETMODE
This function takes the following
(other arguments are ignored}:

device/function-dependent

argument

Pl -- the address of a quadword characteristics buff er
Figure 4-4 shows the quadword Set Mode characteristics buffer.
16 15

buffer size

not used

tape characteristics

Figure 4-4

Set Mode Characteristics Buffer

Table 4-5 lists the tape characteristics
$MTDEF macro defines the symbols listed.

and

their

meanings.

The

Table 4-5
Set Mode and Set Characteristic Magnetic Tape Characteristics
MT$M PARITY

If set, all data transfers are performed with
even parity.
If clear (normal case}, all data
transfers are performed with odd parity.
Even
parity can be selected only for NRZI recording at
800 bpi. Even parity cannot be selected for
phase
encoded
recording
(tape
density is
MT$K_PE_l600} and is ignored.
(continued on next page}

4-13

MAGNETIC TAPE DRIVER

Table 4-5 (Cont.)
Set Mode and Set Characteristic Magnetic Tape Characteristics
..------~---r-----~·-·-----~----------------------

MT$V DENSITY
MT$S-DENSITY

Specifies the density at which all data transfers
are performed. Tape density can be set only when
the selected drive's tape position is at the BOT
marker. Possible density values are:
MT$K DEFAULT

Default system density

MT$K PE 1600

Phase encoded, 1600 bpi

MT$K NRZI 800

Non-return-to-zero-inverted,
bpi

800

Specifies the format in which all data transfers
are performed. Possible format values are:

MT$V FORMAT
MT$S-FORMAT

,__------~--·

MT$K DEFAULT

Default system format

MT$K NORMALll

Normal PDP-11 format. Data bytes
are recorded sequentially on tape
with each byte occupying exactly
one frame

----------

4.4.9.2 Set Characteristic - The Set Characteristic function also
affects the characteristics of the associated tape device. Set
Characteristic is a physical I/O function and requires the access
privilege necessary to perform physical I/O functions. A single
function code is provided:
IO$ SETCHAR
This function takes the following
(other arguments are not valid):

device/function-dependent

argument

Pl -- the address of a quadword characteristics buffer
Figure 4-5
buffer.

shows

the

quadword

Set

Characteristic

8 7

16 15

buffer size

characteristics

type

0
class

tape characteristics
·--···---··-----

Figure 4-5

_________

__.

Set Characteristic Buffer

The first longword contains information on device class and type, and
the buffer size. The device class for tapes is DC$ TAPE. The device
type is DT$ TE16.

4-14

MAGNETIC TAPE DRIVER
The $DCDEF macro defines the device type and class names. The buffer
size is the default to be used for tape transfers (this default is
normally 2048 bytes).
Table 4-5 lists the tape characteristics for
function.

4.5

the

Set

Characteristic

I/O STATUS BLOCK

The I/O status block (IOSB) for QIO functions on magnetic tape devices
is shown in Figure 4-6. Table 4-6 lists the status returns for these
functions. Table 4-3 (in Section 4.3) lists the device-dependent data
returned in the second longword. The IO$ SENSEMODE function can be
used to return this data.
16 15

byte count

status

device-dependent data

/Figure 4-6

IOSB Content

The byte count is the actual number of bytes transferred to
the process buffer or the number of files or blocks skipped.

from

Table 4-6
Status Returns for Tape Devices
Status

Meaning

SS$ NORMAL

Successful completion of the operation specified
in the QIO request. The second word of the IOSB
can be examined to determine the actual number
of bytes transferred to or from the buffer or
the number of files or blocks skipped.

SS$ CTRLERR

Controller-related error. One or more of
following conditions can cause this error:

the

Data late
Error confirmation
Invalid map register
Interface timeout
Missed transfer
Programming error
Read timeout
SS$ DATACHECK

Write check error. A mismatch between the data
in memory and the data on tape was detected
during a write check operation.
(See Section
4.2.1)
(continued on next page)

4-15

MAGNETIC TAPE DRIVER
Table 4-6 (Cont.)
Status Returns for Tape Devices
Status

Meaning
-~-----,·~----·-

SS$ DRVERR

Drive-related error.
One or more
of
following conditions can cause this error:

the

Drive timing error
Illegal function
Illegal register
Operation incomplete
Register modify refused
Nonexecutable function
Unrecovered retriable error
SS$ ENDOFFILE

End-of-file condition.
A
tape
mark
was
encountered during the operation.
For data
transfer functions, the byte count is O;
for
skip record functions, the count is the number
of blocks skipped.

SS$ ENDOFTAPE

End-of-tape condition.
This
is
a
normal
completion and is typically treated as such.
The end of an input tape is denoted by an
end-of-tape
marker.
If
this
marker
is
encountered during an operation in the forward
direction, it may be necessary to modify the
source program to respond to the condition.

SS$ ENDOFVOLUME

End of volume. Two consecutive tape marks were
detected during a skip file operation. This
return is also used as a logical end-of-tape
indicator. If an ASCII standard tape is mounted
foreign, this return may only indicate an empty
file within the volume and not the end of
volume.

SS$ FORMAT

Format error. Format specified by last set tape
characteristics function is not implemented in
slave controller.

SS$ MEDOFL

Medium offline. The addressed drive currently
does not have a volume mounted and on line.

SS$ NONEXDRV

Nonexistent drive.
exist.

__________ ______ ____ ________
_._

The addressed drive does not

(continued on next page)

4-16

MAGNETIC TAPE DRIVER
Table 4-6 (Cont.)
Status Returns for Tape Devices
Status
SS$ PARITY

Meaning
Parity error. One or more of
conditions can cause this error:

the

following

CRC error (NRZI only)
Control bus parity error
Correctable data error (PE only)
Correctable skew (PE only)
Data bus parity error
Incorrectable error (PE only)
Invalid tape mark (NRZI only)
Nonstandard gap
Longitudinal parity error
(NRZI only)
Format error (PE only)
Vertical parity error (NRZI only)
Map parity error
MASSBUS control parity error
MASSBUS data parity error
Read data substitute
SS$ UNSAFE

Drive unsafe. The addressed drive is currently
unsafe and cannot perform any function.

SS$ VOLINV

Volume invalid. The addressed drive has not
been mounted and therefore does not have volume
valid set, or a status change has occurred in
the drive so that it has changed to an unknown,
and therefore, invalid state. All logical and
virtual functions will be rejected with this
status until volume valid is set. Volume valid
is set when a volume is mounted and cleared when
the volume is unloaded, the respective drive
changes to an unknown state, or the power fails.
The driver automatically sets volume valid when
the proper volume is mounted and/or power is
restored.

SS$ WRITLCK

Write-lock error. An attempt was made to
on a write-locked drive.

SS$ DATAOVERUN

Data overrun. The data block read was longer
than the assigned buffer. In the case of a read
reverse, the last data on tape (that is, the
data nearest the end-of-tape at the beginning of
the operation) is the first data read.
This
data is in the buffer.

4-17

write

MAGNETIC TAPE DRIVER
4.6

PROGRAMMING EXAMPLE

The following program is an example of how data is written to and read
from magnetic tape.
In the example, QIO operations are performed
through the magnetic tape ACP.
These operations could have been
performed directly on the device using the magnetic tape driver.
However, this would have involved additional programming, for example,
writing header labels and trailer labels •
• TiTLE MAGTAPE PROGRAMMING EXAMPLE
.IDENT /01/

Detine necessary symbols
;Define tile information block symbols
;Define 1/0 function codes

SFIBDEF
SIODEF

Allocate storaqe tor the necessary data structures
Allocate magtape device name string and descriptor
TAPENAME:
.LONG
.LONG
10$:
.ASCII
20$:

20$-10$
10$
/TAPE/

;

;Length of name string
;Address of name string
;Name string
;Reference label

;

; Allocate space to store assigned channel number

TAPECHAN:
.BLKW

;Tape channel number

.
; Allocate space for the I/O status quadword
,

;

lUSTATUS:
.BLKO

;110 status quadword

;

; Allocate storage tor the input/output butter

.R~PT
256
;Initialise butter to contain 'A'
.ASCII /A/
.ENDR
we now define the FIB•flle information block•whlcn the ACP uses
in order to access 1 deaccess the file.we supply some information
in this blocK and the ACP will supply further information.

FlB-DESCR:
.LONG
.LONG
FIB:
.LONG
.WORD
.wORD
.LONG
.WORD
.WORD
ENDFIB:

;start ot FIB
ENDFIB•FIB
;Length of tile information block
FIB
;Address of file information block
FIB$M_WRlTE!f'IB$M_NUWRlTE ;Read/write access allowed
o,o,o
;file 10
o,o,o
;Directory ID
o
;context
o
;Name flags
o
;Extend control
;Reference label

,
! we now define the file name string and descriptor
,
NAME-DESCR:
.LONG
.LONG
hAME:
.ASCII
END-NAME:

END_NAME•NAME
NAME
"MYDATA.DAT;l"

ifile name descriptor
;Address of name string
;File name string
;Heference label

Now the main program
The program firstly assigns a channel to the magnetic tape unit.
It then performs an access function to create and access a file
called "MYDATA.DAT". It now writes 26 blocks of data to the tape
containlnq the letters ot the alphabet. The first block contains
all A's the next all B's and so on. It starts by writing a block
of 256 bytes and each subsequent olock is reduced in size by two
bytes so by the time it writes the block containing Z's the block
size is only 206 bytes. The magtape ACP will not allow reading of
a tile that has been written until one of three things happens.
The tile is de-accessed,the tile is rewound or the file is back•
spaced. In this example the tile is oackspaced zero blocks and
then it is read in reverse (incrementing the blOCK size everr block
and the data checked against what is meant to be there. If a l ls
well the file is de-accessed and the program exits

4-18

MAGNETIC TAPE DRIVER
.ENTHY

MAGTAPE-EXAMPLE,AM<R3,R4,R5,Rb,R7,R8>

first assign a channel to the tape unit
$ASSIGN_S TAPENA~ElTAPECHAN
CMPW
#SSS-NORMA ,RO
BSBW
ERRCHECK

;Assign tape unit
;OK?
; find out

Next create and access the tile •MYDATA.UAT'

CMPW
BSAW
LOU~l

LUUPl:

CHAN=TAPECHAN ;Channel is magtape
FUNC=#l0$-CREATE!IO$M-ACCESS!l0$M_CREATE,•;Function is create
IOSB=IOSTATUS,;Address Of I/O status word
Pl=FIB-DESCR ;FIB descriptor
P2=#NAME_oEstR
;Name descriptor
#SS$_NORMAL,RO
;UK?
ERRCHECK
;Find out

consists of writing the alphabet to the tape as described earlier
MOVL
MOVL

#26 RS
#256,R3
sorow_s CHAN=TAPECHAN,FUNC=#IO$_WRITEVBLK,P1=BUFF'ER,•
P2=R3
CMPW
#SS$_NORMAL,RO
BSBw
ERRCHECK

;set up loop count
;Set up initial byte count in Rl
;start of loop
;Perform QIO to tape channel
;Function is write virtual block
;Butter address
;Byte count
;OK?
;Find out

Now we decrement the byte count ready tor the next write, set up a
, loop count tor updating the character and LOOP2 performs the upaate

LOOP2:

SUHL2
MOVL
MDV AL
INCB
SOBGTR
SOBGTR

#2,R3
R3 R8
BUFFER,R7
CR7)+
R8,LOOP2
R5,LOOP1

;Decrement byte count for next write
;Copy byte count to RS for LOOP2 count
;Get buffer address in R7
;Increment character
; Until finished
;Repeat LOOPl until alphabet complete

we now fall throuqh LOOP1 and should update the byte count so that
it truly reflects the size ot the last block written to the tape
AUDL2

#2 ,R3

;Update byte count

we now want to read the tape out must tirst perform one of the three
operations outlined above otherwise the ACP will not allow write
access. we will perform an ACP control tunction on it specifying
skip zero blocks. This is a special case of sKip reverse and will
cause the ACP to now allow read access.

CMPw

fUNC=#IDS-ACPtONTHOL,Pl=FIB-DESCR
#SS$_NORMAL,RO

;Set UP to space zero blocks
up tor space function
; Perform QIO to tape channel
;Pertorm an ACP control function
;Define the FIB
;success?

BSBW

ERRCl1ECK

;Find out

CLRL
MOVW

FIB+FIBSLS-C~TRLVAL

#FIBSC_SPAC~,flB+FlB$w$_CNTRLFUNC ;Set

SQIOW_S CHAN=TAPECHAN -

Now we read the file in reverse

LOUP3:

MOVL
#26,RS
;set up loop count
MOVB
#~A/Z/,R6
;Get tirst character in R6
MOVAL
BUFFER,R7
;And buffer address to R7
SQIOW_S CHAN=TAPECHAN ·Channel is magtape
FUNC=#IOS-REA6VHLK!l0$M_R~VERSE,- ;Function is read reverse
IOSB:IOSTATUS,·
;Define I/O status quadword
P1=BUFFER,:And buffer address
P2=R3
;R3 bytes
CMPW
#SS$_NORMAL,RO
;Success?
ASBW
ERRCHECK
;Find out

Now we will checK the data we have read in to make sure
that it agrees with what was written
MOVL
CMPB
BNEQ
SOBGTR
DECB
ADDL2

CH~CKOATA:

SOAGTR

R3,R4
(R7)+ R6
MISMATcH
H.4,CHECKDATA
R6
#2,R3
R5,LOOP3

Copy R3 to R4 tor loop count
Check each character
Print message on error
Carry on until finished
Go backwards through alpnabet
Update byte count by 2 tor next block
Read next block

4-19

MAGNETIC TAPE DRIVER
~ow

we deaccess the file
$Q IOW

S CHAN=TAPECHAN •

:Channel is maQtape
;ueaccess tunction
:110 status

fUNC=#IO$_D~Atc1:::ss,

IOSB=IOSTATUS

Now we deassign the channel and exit
!:::XI 1':

SDASSGN_S CHAN=TAPECHAN
RET

;Deassign channel
n.:xit

we are now at a place where normally we would attempt to 9enerate some error
message but for this example we will simply exit
MISMATCH:
BRB
ERRCHl:::CK:
HNEQ
RStj

.~NU

EXIT
EXtT

Exit
lf error then exit
Exit if not UK
Else return

MAGTAPE-EXA~PL~

4-20

CHAPTER 5
LINE PRINTER DRIVER

This chapter describes the use of the VAX/VMS line printer driver.
This driver supports the LPll Line Printer Interface and the LAll
DECprinter I.

5.1

SUPPORTED LINE PRINTER DEVICES

The following sections describe the LPll Line
the LAll DECprinter I.

5.1.1

Printer

Interface

and

LPll Line Printer Interface

The LPll is a high-speed, 132-column, line printer available in
several
models.
Printers are available with either a n4- or
96-character ASCII print set.
The LPll-R and LPll-S are fully
buffered models that operate at a standard speed of 1110 lines per
minute. Other LPll models have 20-character print buffers, and can
print at full speed if the printed line is 20 characters or less.
Longer lines are printed at a slower rate. Forms with up to six parts
can be used for multiple copies.

5.1.2

LAll DECprinter I

The LAll DECprinter I is a medium-speed printer that operates at a
standard speed of 180 characters per second. It incorporates such
features as a forms length switch to set the top of form to any of 11
common lengths, paper-out switch and alarm, and variable forms width.
The LAll uses a 96-charactei ASCII set;
the column width is 132
characters.

5.2

DRIVER FEATURES AND CAPABILITIES

The VAX/VMS line printer driver provides output character formatting
and error recovery, as described in the following sections.

5-1

LINE PRINTER DRIVER

5.2.1

Output Character Formatting

In write virtual and write logical block operations, user-supplied
characters are output as follows (write physical block data is not
formatted, but output directly):
•

Rubouts are discarded.

•

Tabs move the horizontal print position to
(8) position.

•

All lowercase alphabetic characters
uppercase
before
printing
(unless
specifying lowercase characters is set;
and Table 5-2).

•

On printers where the line feed, form feed, vertical tab, and
return characters empty the printer buffer, returns are held
back and output only if the next character is not a form
feed, line feed, or vertical tab. Returns are always output
on units that have the return function characteristic set
(see Section 5.4.3 Table 5-2).

•

The horizontal print position is incremented on the output of
all nonprinting characters such as the space character.
Nonprinting characters are discarded if the horizontal print
position is equal to or greater than the carriage width.

•

On printers without mechanical form feed
(the form feed
function characteristic is not set; see Section 5.4.3 and
Table 5-2), a form feed is converted to multiple line feeds.
The number of line feeds is based on the current line count
and the page length.

•

Print lines are counted and returned to the
second longword of the I/O status block.

5.2.2

the

are
the
see

MODULO

converted
to
characteristic
Section 5.4.2

caller

the

Error Recovery

The VAX/VMS line printer driver performs the following error
operations:

recovery

•

If the printer is offline for 30 seconds, a "device not ready"
message is sent to the system operator process.

•

If the printer runs out of paper or has a fault condition, a
"device not ready" message is sent to the system operator
every 30 seconds.

•

The current operation is retried every 2 seconds to test for a
changed situation, for example, the printer coming online.

•

The current I/O operation can be canceled at the next
without the printer being online.

timeout

•

When the printer
automatically.

resumes

comes

online,

5-2

device

operation

LINE PRINTER DRIVER
5.3

DEVICE INFORMATION

The user process can obtain information on printer characteristics by
using the $GETCHN and $GETDEV system services (see Section 1.10). The
printer-specific information is returned in the first three longwords
of a user-specified buffer, as shown in Figure 5-1 (Figure 1-8 shows
the entire buffer).
31

8 7

16 15

24 23

device characteristics

page width

type

page length

class

printer characteristics

Figure 5-1

Printer Information

The first longword contains device-independent data.
third longwords contain device-dependent data.

The

second

and

Table 5-1 lists the device-independent characteristics returned in the
first longword.
Table 5-1
Printer Device-Independent Characteristics
Dynamic Bi ts l
(Conditionally Set)

Meaning
"

DEV$M SPL

Spooled device

DEV$M AVL

Printer is online and available

Static Bi ts l
(Always Set)
DEV$M REC

Record-oriented device

DEV$M CCL

Carriage control

DEV$M ODV

Device is capable of output
..

1. Defined by the $DEVDEF macro.
In the second longword, the device class is DC$ LP. The printer type
is a value that corresponds to the printer:- LP$ LPll or LP$ LAll.
The page width is a value in the range of 0 to 255.
The third longword contains printer characteristics and the page
length.
The printer characteristics part can contain any of the
values listed in Table 5-2.

5-3

LINE PRINTER DRIVER
Table 5-2
Printer Device-Dependent Characteristics
Value

Meaning

1---------~--+·-···-··---·-----------------------------

LP$M LOWER

Printer can print lowercase characters. If this
value is not set, all lowercase characters are
converted to uppercase when output.

LP$M MECHFORM

Printer has
mechanical
form
feed.
This
characteristic is used when variable form length
is required, for example,
check
printing.
Driver sends ASCII form feed
(decimal 12).
Otherwise, multiple line feeds are generated.
The page length determines the number of line
feeds.

LP$M CR

Printer requires carriage return.
Section 5.2.1) •

....__ _ _ _ _ _ _ _ _ _ _ L .•...

(See note

------------------- ----

_____

___,

Maximum page length is 255.
The $LPDEF macro defines the values for the printer
the $DCDEF macro defines the device class and types.

5.4

characteristics;

LINE PRINTER FUNCTION CODES

The basic line printer I/O functions are write, sense mode,
mode. None of the function codes takes function modifiers.

5.4.1

and

set

Write

The line printer write functions print the contents of the user buffer
on the designated printer.
The write functions and their QIO function codes are:

•
•

IO$ WRITEVBLK - write virtual block
IO$ WRITELBLK - write logical block

is
not
data
WRITEPBLK
write physical block (the
• IO$
formatted,
but output directly, as in PAS SALL mode on
terminals)
The write function codes
dependent arguments:

can

take

the

following

device/function

•

Pl = the starting virtual address of the buffer that is to
written

•

P2 = the number of bytes that are to be written

•

P3 (ignored)

•

P4 = carriage control specifier except for write physical
block operations (write function carriage control is described
in Section 5.4.1.l)
5-4

LINE PRINTER DRIVER
P3, P5, and P6 are not meaningful for line printer write operations.
In write virtual block and write logical block operations, the buffer
specified by Pl and P2 is formatted for the selected line printer and
includes the carriage control information specified by P4.
If the printer is not set spooled, write virtual and write logical
perform the same function.
If the printer is set spooled, a write
logical function queues the I/O to the printer and a write virtual
function queues the I/O to the intermediate device, usually a disk.
All lowercase characters are converted
to
uppercase
if
the
characteristics of the selected terminal do not include LP$M LOWER
{this does not apply to write physical block operations).
Multiple line feeds are generated for form feeds only if the printer
does not have a mechanical form feed, that is, the LP$M MECHFORM
characteristic. The number of line feeds generated depends- on the
current page position and the length of the page.
Section 5.2.1 describes character formatting in greater detail.

5.4.1.1 Write Function Carriage Control - The P4 argument is a
longword that specifies carriage control. Carriage control determines
the next printing position on the line printer.. {P4 is ignored in a
write physical block operation.) Figure 5-2 shows the P4 longword
format.

P4:

POSTFIX

PREFIX

Figure 5-2

0
(not used)

FORTRAN

P4 Carriage Control Specifier

Only bytes O, 2, and 3 in the longword are used. Byte 1 is ignored.
If the low-order byte {byte 0) is not O, the contents of the longword
are interpreted as a FORTRAN carriage control specifier.
Table 5-3
lists the possible byte 0 values (in hexadecimal) and their meanings.
If the low-order byte (byte 0) is O, bytes 2 and 3 of the P4 longword
are interpreted as the prefix and postfix carriage control specifiers.
The prefix (byte 2) specifies the carriage control before the buffer
contents are printed.
The postfix (byte 3) specifies the carriage
control after the buffer contents are printed. The sequence is:
Pref ix carriage control - Print - Postfix carriage control
The prefix and postfix bytes, although interpreted separately, use the
same encoding scheme.
Table 5-4 shows this encoding scheme in
hexadecimal format.

5-5

LINE PRINTER DRIVER
Table 5-3
Write Function Carriage Control (FORTRAN: Byte 0 not equal to 0)
Byte 0
ASCII
Value
Character
(hexadecimal)

Meaning

t-----·-----··----1-·--·-·-··----.,____ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

(space)

Sing le-space carriage control.
(Sequence:
newline, print buffer contents, return.)

Double-space carriage control.
(Sequence:
newline, newline, print buffer contents,
return.)

Page eject carriage control.
(Sequence:
form feed, print buffer contents, return.)

Overprint carriage control.
(Sequence:
print buffer contents, return.) Allows
double printing for emphasis or special
effects.

Prompt
carriage
control.
(Sequence:
newline, print buffer contents.)

All other
values

Same
as
ASCII
space
single-space carriage control.

character:

Table 5-4
Write Function Carriage Control (P4 byte 0 equal to 0)
Prefix/Postfix Bytes
(Hexadecimal)
Bit 7

Meaning

Bits 0 - 6

- · - - - -. - - - · - - · - + - - - - - - - - - - - - - - - - - - - - - - 0

No carriage control is specified,
that is, NULL.

l-7F

Bits 0 through n are a count of
newlines
(carriage
return
followed by line feed).

!---------···-·· · - - · - - - - - - - -. · · · · - - - - - - r - - - - - - - - - - - - - - - - - - - - - 1

Bit 7

Bit 6

Bits
0-4

Meaning

1-lF

Output the single ASCII control
character
specified
by
the
configuration of bits 0 through 4
(7-bit character set).

1-lF

Output the single ASCII control
character
specified
by
the
configuration of bits 0 through 4
which are translated as ASCII
characters 128 through 159 (8-bit
character set) •

______ __

....___

Bit 5

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

"""

·-

--~·--·--------·--------·-

·------------------------

s-n

LINE PRINTER DRIVER
Figure 5-3 shows the pref ix and postfix hexadecimal coding that
produces the carriage control functions listed in Table 5-3. Prefix
and postfix coding provides an alternative way to achieve these
controls.
Sequence:
Prefix= NL
Print
Postfix= CR

Sequence:
Prefix= LF, LF
Print
Postfix= CR

Sequence:
Prefix= FF
Print
Postfix= CR

"+"
P4:

Sequence:

Prefix= NULL
Print
Postfix= CR

"$"

Sequence:

]

P4:
0

Example: Skip 24 lines before printing

P4:

Prefix= NL
Print
Postfix= NULL

Sequence:

Prefix= 24NL
Print
Postfix:= CR

Figure 5-3 Write Function Carriage Control
(Prefix and Postfix Coding)
In the first example, the prefix/postfix coding for a single-space
carriage control
(line feed, print buffer contents, return)
is
obtained by placing the value (1) in the second (prefix) byte and the
sum of the bit 7 value (80) and the return value (D) in the third
(postfix) byte:
+

8 0 (bit 7 = 1)
D (return)
8D (postfix

return)

5-7

LINE PRINTER DRIVER
5.4.2

Sense Printer Mode

This
function
senses
the
current
device-dependent
printer
characteristics and returns them in the second longw6rd of the I/O
status block. No device/function-dependent arguments are used with
IO$ SENSEMODE.

5.4.3

Set Mode

Set mode operations affect the operation and characteristics of the
associated line printer.
VAX/VMS provides two types of set mode
functions: Set Mode and Set Characteristics.
Set Mode requires
logical I/O privilege.
Set Characteristics requires physical I/O
privilege. Two function codes are provided:
•

IO$ SETMODE

•

IO$ SETCHAR

These functions take the following device/function-dependent
(other arguments are not valid):
•

argument

Pl -- the address of a characteristics buffer

Figure 5-4 shows the quadword Pl
characteristics
buffer
IO$ SETMODE. Figure 5-5 shows ths same buffer for IO$ SETCHAR.

24 23

16 15

wi~_t:_

1-------pag---.--e

____

page length

printer

Figure 5-4

page

page length

Figure 5-5

J
J

oot ""d- ·

characteri:t~----

____

Set Mode Characteristics Buff er

24 23

L__

for

w~d-th- ~-~-·-----=

16 15

J__

8 7

-_-_t:_:

~--_-_-c_l_a_s~-~~~~----1__

printer characteristics

Set Characteristic Characteristics Buffer

In the buffer, the device class is DC$ LP.
The printer type is a
value that corresponds to the printer: DT$ LPll or DT$ LAll. The
type can be changed by the IO$ SETCHAR function: The page width is a
value in the range of O to 255:
The printer characteristics part of the buffer can contain any of
values listed in Table 5-2.

5-8

the

LINE PRINTER DRIVER
I/O STATUS BLOCK

5.5

The I/O status blocks (IOSB) for the write and set mode I/O functions
are shown in Figures 5-6 and 5-7. Table 5-5 lists the status returns
for these functions.
31

16 15

byte count

status

number of lines the paper moved*
*O if 10$_WRITEPBLK

Figure 5-fi

IOSB Contents - Write Function
16 15

status

Figure 5-7

IOSB Contents - Set Mode Function

Table 5-5
Line Printer QIO Status Returns
Status

Meaning

SS$ NORMAL

successful completion. The operation specified in the
On a write operation,
QIO was completed successfully.
the second word of the IOSB can be examined to
determine the number of bytes written.

SS$ ABORT

The operation was canceled by the Cancel I/0 on Channel
($CANCEL) system service.

5-9

LINE PRINTER DRIVER
5.6

PROGRAMMING EXAMPLE

The following simple program is an example of I/O to the line printer
that shows how to use the different carriage control formats. This
program prints out the contents of the output buffer (OUT BUFFER) 10
times using 10 different carriage control formats. The-formats are
held in location OUTPUT FORMAT •
• TITLE LINE PRINTER PROGRAMMING EXAMPLE
.IDENT /01/
;uetine necessary symbols
1

SIODEf

;Define 110 function codes

Allocate storaqe tor the necessary data structures
Allocate output buffer and fill with required output text
UUT-BUFFER:
.ASCII

"VAX-PRINTER-EXAMPLE"

OUT-~UFFER-SIZE=.·OUT-BUFFER

;Define size ot output strin9

i Allocate device name string and descriptor
;

DEVICE-DESCR:
.LONG
.LONG
lOS:
.ASCII
20$:

2os-1os
10$

/LINE-PRINT~R/

iLength of name strin9
;Address of name strin9
;Name string of output device
;Reference label to calculate lenQth

;

; Allocate space to store assiqned channel number

D~VlCE-CHANNEL:

.BLKw

ichannel number

Now set up the carriage control formats
OUTPUT-FORMAT:
.A¥TE

o,o 0 0

;No carriage control
;BlanK=Lf+ ••• TEXT •• +CR
;Zero=LF+Lf+.TEXT •• +CR
.BYTE
;une=FF+ ••• TEXT •••• +CR
.BYTE
;Plus=overprint, ••• +CR
;Dollar=Lf+TEXTlPrompt)
.R¥TE
Now tne prefix•posttix carriage control formats
.BYTE
0,0,1,141
;LF+ ••••• TEXT ••••• +CR
.BYTE
.AYTE

.BYTE
.RYTE

.AYTE

32,6,6,0

48,0,0,0
49,0,0,0
43,0,0,0
36,0,0,0

0,0,24{141
0,0,2, 41
0,0,140,141

;24LF+ ••• TEXT ••••• +CR
;LF+LF+ •• TEXT ••••• +CR
;FF+ ••••• TEXT ••••• +CR

Program starting point
The program assigns a channel to the output device,sets up a loop
Count for the number of times it wishes to print, and performs ten
QIO and wait system services.The channel is then deassigned •
• ENTRY

PRINTER-EXAMPLE,~M<R2,R3>;Program

starting address

First assign a channel to the output device
SASSIGN_S DEVNAM=DEVICE-DESCR,- !Assign a channel to printer
CHAN:OEVICE-CHANNEL
,
Ro sos
;It low bit cleartassignment failure
BLBC
#1 1 R3
;set up loop coun~
MOVL
OUTPUT-FORMAT,R2
;Set up o/p format address in R2
MOVAL
Start of printinq loop
JOS:

so1ow_s CHAN:DEVICE-CHA~NEL,

40$:

ALMC
H0,40$
SOBGTR R3 30$
SDASSGN_S CHAN=DEVICE-CHA~NEL

FUNC=#l0$_WRITEVBLK,Pl=OUT-BUFfEH •
P2=#0UT-BUFFER-SIZE,•
P4:(P2)+

~os:

RET

.END

;Print on device cnannel
;110 tunct1on is write virtual
;Address of output buffer
;Size of buffer to print
;Format control in R2
;w~11 auto-increment.
;It low bit clear,i/o failure
;Hranch if not finished
;Deassign channel
;Return

PHINTER-fXAMPLE

5-10

CHAPTER 6
CARD READER DRIVER

This chapter describes the use of the VAX/VMS
This driver supports the CRll Card Reader.

6.1

card

reader

SUPPORTED CARD READER DEVICE

The CRll Card Reader reads standard 80-column punched data

6.2

driver.

cards~

DRIVER FEATURES AND CAPABILITIES

The VAX/VMS card reader driver provides the following capabilities:
•

Multiple controllers of the same type;
one CRll can be used on the system

for example, more than

•

Binary, packed Hollerith, and translated 02n or 029 read modes

•

Unsolicited interrupt support for automatic card reader
spooling

•

Special card punch combinations to indicate
condition and to set the translation mode

•

Error recovery

The following sections describe the read modes, special
combinations, and error recovery in greater detail.

6.2.1

input

end-of-file

card

punch

Read Modes

VAX/VMS provides two card reader device/function-dependent modifier
bits for read data operations:
read packed Hollerith (IO$M PACKED)
and read binary .(IO$M BINARY). If IO$M PACKED is set, the aata is
packed and stored Tn sequential bytes of the input buffer. If
IO$M BINARY is set, the data is read and stored in sequential words of
the Tnput buffer. IO$M_BINARY takes precedence over IO$M PACKED.
The read mode can also be set by a set translation mode card
Section 6.2.2.2) or by the Set Mode function {see Section n.4.3).

6-1

(see

CARD READER DRIVER
Special Card Punch Combinations

6.2.2

The VAX/VMS card reader driver recognizes three special card punch
combinations in column 1 of a card.
One combination signals an
end-of-file condition. The other two combinations set the current
translation mode.

End-of-File Condition - A card with the 12-11-0-1-n-7-8-9
holes punched in column 1 signals an end-of-file condition. If the
read mode is binary, the first eight columns must contain this punch
combination.

6.2.2.1

Set Translation Mode - If the read mode is
nonbinary,
nonpacked
Hollerith
(the
IO$M BINARY and IO$M PACKED function
modifiers are not set), the current translation mode can be set to the
026 or 029 punch code.
A card with the 12-2-4-8 holes punched in
column 1 sets the translation mode to the 02n code. A card with the
12-0-2-4-6-8 holes punched in column 1 sets the translation mode to
the 029 code. The translation mode can be changed as often as
required.
6.2.2.2

If a translation mode card contains punched information in
through 80, it is ignored.

columns

Logical, virtual, and physical read functions result in only one
card's being read.
If a translation mode card is read, the read
function is not completed and another card is read immediately.

Error Recovery

6.2.3

The VAX/VMS card.reader driver performs the following
operations:

error

recovery

•

If the card reader is offline for 30 seconds, a
ready" message is sent to the system operator.

"device

not

•

If .a recoverable card reader failure is detected, a "device
not ready" message is sent to the system operator every 30
seconds.

•

The current operation is retried every two seconds to test for
a changed situation, for example, the removal of an error
condition.

•

The current I/O operation can be canceled at the next timeout
without the card reader being online. When the card reader
comes online, device operation resumes automatically.

There are four categories of card reader failures:
•

Pick check -- The next card cannot be delivered from the input
hopper to the read mechanism.

•

Stack check -- The card just read did not
the output hopper.

n-2

stack

properly

CARD READER DRIVER

•

Hopper check -- Either the output hopper is full or the
hopper is empty.

input

•

Read check -- The last card was read incorrectly due
edges or punches before column 1 or after column 80.

torn

Manual intervention is required if any of these errors occur.
The
recovery is transparent to the user program issuing the I/O request.
When a recoverable card reader failure is detected, a "device not
ready" message is displayed on the system operator console. When this
message is received, the card reader indicator lights should be
examined to determine the reason for the failure. The indicator
lights and the respective recovery procedures are:

6.3

•

Pick check -- The next card cannot be delivered to the read
mechanism.
Remove the next card to be read from the input
hopper and smooth the leading edge, that is, the edge that
will enter the read mechanism first. Replace the card in the
input hopper and press the RESET button.
Card
reader
operation will resume automatically. If a pick check error
occurs again on the same card, remove the card from the input
hopper and repunch it. Place the duplicate card in the input
hopper and press the RESET button. If the problem persists,
either an adjustment is required or nonstandard cards are in
the input hopper.

•

Stack check -- The card just read did not stack properly in
the output hopper. Remove the last card read from the output
hopper and examine the condition. If it is excessively worn
or mutilated, repunch it. Place either the duplicate or the
original card in the read station of the input hopper and
press the RESET button.
Card reader operation will resume
automatically. If the stack check error recurs immediately,
an adjustment is required.

•

Hopper check -- Either the input hopper is empty or the output
hopper is full.
Examine the input hopper and, if empty,
either load the next deck of input cards or an end of file
card. If the input hopper is not empty, remove the cards that
have accumulated in the output hopper and press the RESET
button. Card reader operation will resume automatically.

•

Read check -- The last card was read incorrectly. Remove the
last card from the output hopper and examine its condition.
If it is excessively worn, mutilated, or contains punches
before
column 0 or after column 80, repunch the card
correcting any incorrect punches. Place either the original
or duplicate card in the read station of the input hopper and
press the RESET button. Card reader operation will resume
automatically. If the read check error recurs immediately, an
adjustment is necessary.

DEVICE INFORMATION

Users can obtain information on card reader characteristics by using
the $GETCHN and $GETDEV system services (see Section 1.10). The
information is returned in a user-specified buffer shown in Figure
6-1. Only the first three longwords of the buffer are shown in Figure
6-1 (Figure 1-9 shows the entire buffer).

n-3

CARD READER DRIVER
31

8 7

16 15

------

-~·-

device characteristics
,,

type

buffer size

____
class

device-dependent information
··--~-·-~-

Figure 6-1

·---

Card Reader Information

The device characteristics returned in the first longword
in Table 6-1.

are

listed

Table 6-1
Card Reader Device-Independent Characteristics
Dynamic Bit l
(Conditionally Set)

Meaning
- ""-····-·----~ -----------·-------·-·-·-----1

DEV$M AVL

Device is online and available
-----·-~·--'

Static Bits 1
(Always Set)

·--·-·------··.·-·-----------------1
. . ·---------,----·---------1

DEV$M IDV

Device is capable of input

DEV$M REC

Device is record oriented
·----

1. Defined by the $DEVDEF macro
The second longword contains information on device class and type, and
the buffer size. The device class for card readers is DC$ CARD. The
device type is DT$_CR11 for the CRll.
The $DCDEF macro defines the device type and class names. The buffer
size is the default to be used for all card reader devices (this
default is 80 bytes).
The
third
longword
contains
device-dependent
card
reader
characteristics.
Table 6-2 lists these characteristics. The $CRDEF
macro defines the characterstics values.

6-4

CARD READER DRIVER
Table 6-2
Device-Dependent Information for Card Readers
Value

Meaning

CR$V TMODE
CR$S-TMODE

Specifies the translation mode for nonbinary,
nonpacked Hollerith data transfers.l Possible
values are:
CR$K T026

Translate according to 026 punch
code

CR$K T029

Translate according to 029 punch
code

1. Section 6.2.2.2 describes the set translation mode punch code.

CARD READER FUNCTION CODES

6.4

The VAX/VMS card reader can perform logical, virtual, and physical I/O
functions.
Table 6-3 lists these functions and their function codes.
These functions are described in more detail in the following
paragraphs.
Table 6-3
Card Reader I/O Functions
Function Code and
Arguments

Type 1

Function
Modifiers

Function

IO$ READLBLK Pl,P2

IO$M BINARY
IO$M-PACKED

Read logical block

IO$ READVBLK Pl,P2

IO$M BINARY
IO$M-PACKED

Read virtual block

IO$ READPBLK Pl,P2

IO$M BINARY
IO$M-PACKED

Read physical block

IO$ SENSEMODE

Sense the card reader
characteristics and
return them in the
I/O status block

IO$ SETMODE Pl

Set card reader
characteristics for
subsequent operations

IO$ SETCHAR Pl

Set card reader
characteristics for
subsequent operations

virtual; L

logical; P

physical

n-5

CARD READER DRIVER

6.4.1

Read

This function reads data from the next card in the card reader input
hopper into the designated memory buffer in the specified format.
Only one card is read each time a read function is specified.
VAX/VMS provides three read function codes:
•

IO$ READVBLK - read virtual block

•

IO$ READLBLK - read logical block

•

IO$ READPBLK - read physical block

Two function-dependent arguments are used with these codes:
•

Pl -- the starting virtual address of the buffer
receive the data

that

•

P2 -- the number of bytes that are to be read in the specified
format

The read binary function modifier (IO$M BINARY) and the read packed
Hollerith function modifier
(IO$M PACKED) can be used with all read
functions. If IO$M BINARY is specifTed, successive columns of data
are stored in sequential word locations of the input buffer. If
IO$M PACKED is specified, successive columns of data are packed and
stored in sequential byte locations of the input buffer. If neither
of these function modifiers is specified, successive columns of data
are translated in the current mode (026 or 029) and stored in
sequential bytes of the input buffer. Figure 6-2 shows how data is
stored by IO$M_BINARY and IO$M PACKED.
Binary column (10$M_BINARY):
15

12 11

11211

~-1·-~3-.

4 5 6

*Bits 12 - 15 are 0

Pac!<ed column (10$M_PACKED):
7

3 2

112 11 o g al

J
0

*n = 0 if no punches in rows 1 - 7
= 1 if a punch in row 1
= 2 if a punch in row 2

= 7 if a punch in row 7

Figure 6-2

Binary and Packed Column Storage

Regardless of the byte count specified by the P2 argument, a maximum
of 160 bytes of data for binary read operations and 80 bytes of data
for nonbinary read operations (IO$M PACKED, or 026 or 029 modes) are
transferred to the input buffer:
If P2 specifies less than the
maximum quantity for the respective mode, only the number of bytes

n-6

CARD READER DRIVER

any

specified are transferred;
filled with data.

6.4.2

remaining buffer locations are not

Sense Card Reader Mode

This function senses the current device-dependent
card
reader
characteristics and returns them in the second longword of the I/O
status block (see Table 6-2). No device/function dependent arguments
are used with IO$ SENSEMODE.

6.4.3

Set Mode

Set mode operations affect the operation and characteristics of the
associated card reader device. VAX/VMS defines two types of set mode
functions:
•

Set Mode

•

Set Characteristic

6.4.3.1 Set Mode - The Set Mode function affects the characteristics
of the associated card reader. Set Mode is a logical I/O function and
requires the access privilege necessary to perform logical I/O.
A
single function code is provided:
IO$ SETMODE
This function takes the following device/function dependent argument:
Pl -- the address of a characteristics buffer
Figure 6-3 shows the quadword Set Mode characteristics buffer.
31

1615

not used

buffer size

card reader characteristics

Figure 6-3

Set Mode Characteristics Buff er

Table 6-4 lists the card reader characteristics and
The $CRDEF macro defines the characteristics values.

n-7

their

meanings.

CARD READER DRIVER

Table 6-4
Set Mode and Set Characteristic Card Reader Characteristicss
Value 1

Meaning

------------;-----····----- · - - CR$V TMODE
CR$S-TMODE

Specifies the translation mode for nonbinary,
nonpacked Hollerith data transfers. Possible
values are:
CR$K T026

Translate according to 026 punch
code

CR$K T029

Translate according to 029 punch
code

'-------------'--·-------·-···----------------------------..!
1. If neither the 026 or 029 mode is specified, the default

mode

can

be set by the SET CARD READER command.

6.4.3.2 Set Characteristic - The Set Characteristic function also
affects the characteristics of the associated card reader device. Set
Characteristic is a physical I/O function and requires the access
privilege necessary to perform physical I/O functions. A single
function code is provided:
IO$ SETCHAR
This function takes the following device/function dependent argument:
Pl -- the address of a characteristics buffer
Figure 6-4 shows the Set Characteristic characteristics buffer.
16 15

. . - - - - - - - - - - - - - ·-----·- ---..------buffer size

8 7

---~--------

type

class

card reader characteristics
.. ,,,

_____________________

Figure

.,_

n-4

----------------------'

Set Characteristic Buffer

The device type value is DT$ CRll.
The device class value is
DC$ CARD. Table 6-4 lists the card reader characteristics for the Set
Characteristic function.

6.5

I/O STATUS BLOCK

The I/O status block (IOSB) format for QIO functions on the card
reader is shown in Figure 6-5. Table 6-5 lists the status returns for
these functions. Table 6-2 lists the device-dependent data returned
in the second longword.
The 10$ SENSEMODE function can be used to
obtain this data.
-

n-8

CARD READER DRIVER
31

16 15

byte count

status

device-dependent data

Figure 6-5

IOSB Contents

Table 6-5
Status Returns for Card Reader
Status

Meaning

SS$ NORMAL

Successful completion of the operation specified
in the QIO request. The second word of the IOSB
can be examined to determine the actual number
of bytes written to the buffer.

SS$ DATAOVERRUN

Data overrun. Column data was delivered to the
controller data buffer before previous data had
been read by the driver.

SS$ ENDOFFILE

End-of-file condition. An end-of-file card
encountered during the read operation.

IS-9

was

CHAPTER 7
MAILBOX DRIVER

VAX/VMS supports a virtual device, called a mailbox, that is used for
communication between processes. Mailboxes provide a controlled and
synchronized method for .processes to exchange
data.
Although
mailboxes transfer information in much the same way that other I/O
devices do, they are not actual devices.
Rather, mailboxes are
software-implemented
devices
that
can perform read and write
operations.
Multiport memory mailboxes function the same as regular mailboxes.
However, they can also be used by processes on different processors
that are connected to an MA780.
The VAX/VMS Real-Time User's Guide contains additional information
the use of mailboxes.

7.1

MAILBOX OPERATIONS

Software mailboxes can be compared to the actual metal boxes used for
mail delivery. As shown in Table 7-1, both types of mailboxes perform
similar operations.
Table 7-1
Mailbox Read and Write Operations
Use of Conventional
Mailboxes

Use of VAX/VMS
Software Mailboxes

Receive Mail

Resident checks mailbox to
see if any mail was delivered.
If so, picks it up, opens it,
and reads it.

A process initiates a read
to a mailbox to obtain data
sent by another process.
The process reads data
if a message was
previously transmitted
to the mailbox.

Receive
Notification
of Mail

The mail carrier leaves notification to the resident that
mail can be picked up at the
post office.

A process specifies that it
wants to be notified
through an AST when a
message is sent to the
mailbox.

Operation

(continued on next page)

7-1

MAILBOX DRIVER
Table 7-1 (Cont.)
Mailbox Read and Write Operations

Operation

Use of Conventional
Mailboxes

use of VAX/VMS
Software Mailboxes

t------------+---·------------·-----·Send Mail
(without
notification
of receipt)

The resident leaves mail
addressed to another person
in the mailbox, but neither
waits for nor expects notification of its delivery.

A process initiates a write
request to a mailbox to
transmit data to another
process. The sending
process does not wait until
the data is read by the
receiving process before
completing the I/O operation.

Send Mail
(with notification of
receipt)

The resident leaves mail
addressed to another person
in the mailbox and asks to
be notified of its delivery.

·A process initiates a write
request to a mailbox to
transmit data to another
process. The sending
process waits until the
receiving process reads the
data before completing the
I/O operation.

Reject Mail

The resident discards
junk mail.

The receiving process reads
messages from the mailbox,
sorts out unwanted messages,
and responds only to useful
messages.

7.1.1

Creating Mailboxes

A process uses the Create Mailbox and Assign Channel ($CREMBX) system
service to create a mailbox and assign a channel and logical name to
it.
The system enters the logical name in either the system
(permanent mailbox) or group (temporary mailbox) logical name table
and gives it an equivalence name of MBAn, where n is a unique unit
number.
$CREMBX also establishes the characteristics of the mailbox.
These
characteristics include a protection mask, permanence indicator,
maximum message size, and buffer quota.
Other processes can assign additional channels to the mailbox using
either $CREMBX or the Assign I/O Channel ($ASSIGN) system service.
The mailbox is identified by its logical name both when it is created
and when it is assigned channels by cooperating processes.
Figure 7-1 illustrates the use of $CREMBX and $ASSIGN.
Creating mailboxes requires privilege. If sufficient dynamic memory
for the mailbox data structure is not available, a resource wait will
occur if resource wait mode is enabled.
The programming example at the end of this chapter (Section
illustrates mailbox creation and interprocess communication.

7-2

7.5)

MAILBOX DRIVER

USER OR
SYSTEM
PROCESS
CREATES
MAILBOX

MAILBOX

B
Figure 7-1

7.1.2

Multiple Mailbox Channels

Deleting Mailboxes

The system maintains a count of all channels assigned to a temporary
mailbox.
As each process finishes using a mailbox, it deassigns the
channel using the Deassign I/O Channel ($DASSGN) system service.
The
channel count is decremented by one. The system automatically deletes
the mailbox when no more channels are assigned to it
(that is,· when
the channel count reaches 0).
Permanent mailboxes must be explicitly deleted using the Delete
Mailbox
($DELMBX) system service.
This can occur at any time.
However, the mailbox is actually deleted when no processes have
channels assigned to it.
When a mailbox is deleted, its message buffer quota is returned to the
process that created it.

7.1.3

Mailbox Message Format

There is no standardized format for mailbox messages and none is
imposed on users. Figure 7-2 shows a typical mailbox message format.
Other types of messages can take different formats;
for an example,
see Figure 2-1 in Section 2.2.5.

7-3

MAILBOX DRIVER

16 15

not used

data

Figure 7-2

7.2

Typical Mailbox Message Format

DEVICE INFORMATION

Users can obtain information on mailbox characteristics by using the
$GETCHN
and
$GETDEV system services
(see Section 1.10).
The
information is returned in a user-specified buffer. The first three
longwords of the buffer are shown in Figure 7-3 (Figure 1-9 shows the
entire buffer).
31
.....-------~

8 7

16 15

---··,.- ·-···--····

device characteristics

buffer size

unused

number of messages in mailbox

Figure 7-3

Mailbox Information

The first longword in the buffer contains the device characteristics
values listed in Table 7-2. The $DEVDEF macro defines these values.
Table 7-2
Mailbox Characteristics
Dynamic Bit
(Conditionally Set)

Meaning

DEV$M SHR

Shareable device

DEV$M AVL

Device is available

Static Bits
(Always Set)
DEV$M REC

Record-oriented device

DEV$M IDV

Device is capable of input

DEV$M ODV

Device is capable of output

DEV$M MBX

Mailbox device
7-4

MAILBOX DRIVER
The second
class and
The device
The buffer

7.3

longword of the buffer contains information on the device
type, and the buffer size. The device class is DC$ MAILBOX
type is DT$ MBX. The $DCDEF macro defines these symbols.
size is the-maximum message size in bytes.

MAILBOX FUNCTION CODES

The VAX/VMS mailbox I/O functions
end-of-file, and set attention AST.

are:

read,

write,

write

No buffered I/O byte count quota checking is performed on mailbox I/O
messages.
Instead, the byte count or buffer quota of the mailbox is
checked for sufficient space to buffer the message being sent.
The
buffered I/O quota and AST quota are also checked.

Read

7.3.1

Read mailbox QIO requests are used to obtain messages written by other
processes. The three mailbox functions and their codes are:
•

IO$ READVBLK - read virtual block

•

IO$ READLBLK - read logical block

•

IO$ READPBLK - read physical block

These function codes take two device/function-dependent arguments:
•

Pl -- the starting virtual address of the buffer
receive the message read

that

•

P2 -- the size of the buffer in bytes (limited by the
message size for the mailbox)

maximum

One function modifier can be specified with a QIO read request:
IO$M NOW -- the I/O operation is completed immediately
wait-for a write request from another process

with

Figure 7-4 illustrates the read mailbox functions;
in this figure,
Process A reads a mailbox message written by Process B. As the figure
indicates, a mailbox read request requires a corresponding mailbox
write request (except in the case of an error). The requests can be
made in any sequence; that is, the read request can either precede or
follow the ~rite request.
Two possibilities exist if Process A issues a read request before
Process B issues a write request. If Process A did not specify the
function modifier IO$M NOW, Process A's request is queued during the
wait for Process B -to issue the write request. When this request
occurs, the data is transferred from Process B, through the system
buffers, to Process A to complete the I/O operation.
However, if Process A did specify the IO$M NOW function modifier, the
read operation is completed immediately. That is, Process A's request
is not queued during the wait for the message from Process B, and no
data is transferred from Process B to Process A.

7-5

MAILBOX DRIVER
If Process B sends a message (with no function modifier; see Section
7.3.2) before Process A issues a read request (with or without a
function modifier), Process A finds a waiting message in the mailbox.
The
data
is
transferred and the I/O operation is completed
immediately.
To issue the read request, Process A can specify any of the
function codes; all perform the same operation.

0or0

READ QIO

WRITE QIO

PROCESS
A

read

QIO

PROCESS
B

MAILBOX

DATA

NOTE: Numbers indicate order of events.

Figure 7-4

Read Mailbox

Write

7.3.2

Write mailbox QIO requests are used to transfer data from a process to
a mailbox.
The three mailbox functions and their QIO function codes
are:
•

IO$ WRITEVBLK

write virtual block

•

IO$ WRITELBLK

write logical block

•

IO$ WRITEPBLK

write physical block

These function codes take two device/function-dependent arguments:
•

Pl -- the starting virtual address of the buffer that contains
the message being written

•

P2 -- the size of the buffer in bytes (limited by the
message size for the mailbox)

maximum

One function modifier can be specified with a QLO write request:
IO$M NOW - the I/O operati-0n is completed immediately
wait-for another process to read the mailbox message

with

Figure 7-5 illustrates the write mailbox function;
in this figure,
Process A writes a message to be read by Process B. As in the read
request example above, a
mailbox
write
request
requires
a
corresponding mailbox read request (unless an error occurs), and the
requests can be made in any sequence.
Two possibilities exist if Process A issues a write request before
Process B issues a read request. If Process A did not specify the
function modifier IO$M NOW, Process A's write request is queued during
the wait for Process B to issue a read request. When this request

7-n

MAILBOX DRIVER

occurs, the data is transferred
complete the I/O operation.

from

Process

However, if Process A did specify the IO$M NOW function modifier, the
write operation is completed immediately. The data is available to
Process B and is transferred when Process B issues a read request.
If Process B issues a read request (with no function modifier) before
Process A issues a write request
(with or without the function
modifier), Process A finds a waiting request in the mailbox. The data
is transferred and the I/O operation is completed immediately.
To issue the write request, Process A can specify any of the write QIO
function codes; all perform the same operation.

PROCESS

PROCESS
B

MAILBOX

DATA

NOTE: Numbers indicate order of events.

Figure 7-5

Write Mailbox

Write End-of-File Message

7.3.3

Write End-of-File Message QIO requests are used to insert a special
message in the mailbox.
The process that reads the end-of-file
message is returned the status code SS$ ENDOFFILE in the I/O status
block.
No data is transferred. This function takes no arguments or
function modifiers. VAX/VMS provides a single function code:
IO$ WRITEOF

write end-of-file message

Set Attention AST

7.3.4

Set Attention AST QIO requests are used to specify that an AST be
given to notify the requesting process when a cooperating process
places an unsolicited read or write request in a designated mailbox.
Because the AST only occurs when the read or write request arrives
from a cooperating process, the requesting process need not repeatedly
check the mailbox status.
The Set Attention AST functions and their function codes are:
•

10$ SETMODE!IO$M READATTN - read attention AST

!0$ SETMODE!IO$M WRTATTN - write attention AST

7-7

MAILBOX DRIVER
These function codes take two device/function-dependent arguments:
•

Pl -- AST address (request notification
address is O)

disabled

•

P2 -- AST parameter returned in the argument list when the AST
service routine is called

•

P3 -- access mode to deliver AST;
mode

maximized with

the

requester's

These functions are one-time AST enables;
they must be explicitly
reenabled once the AST has been delivered if the user desires
notification of the next unsolicited request. Both types of enables,
and more than one of each type, can be set at the same time. The
number of enables is limited only by the AST quota for the process.
Figure 7-6 illustrates the write attention AST function.
In this
figure, an AST is set to notify Process A when Process B sends an
unsolicited message.
Process A uses the IO$ SETMODE!IO$M WRTATTN function to request an
AST.
When Process B sends a message to the mailbox, the AST is
delivered to Process A. Process A responds to the AST by issuing a
read request to the mailbox.
The function modifier IO$M NOW is
included in the read request.
The data is then transferred to
complete the I/O operation.
If several requesting processes have set ASTs for unsolicited messages
at the same mailbox, all ASTs are delivered when the first unsolicited
message is placed in the mailbox. However, only the first process to
respond to the AST with a read request receives the data. Thus, when
the next process to respond to an AST issues a read request to the
mailbox, it may find the mailbox empty. If this request does not
include the function modifier IOSM NOW, it will be queued during the
wait for the next message to arrive in the mailbox.

AST

AST SPECIFIED BY
10$_SETMODE
!10$M_WRTATTN

PROCESS

MAILBOX

PROCESS
B

DATA

NOTE: Numbers indicate order of events.

Figure 7-6

Write Attention AST (Read Unsolicited Data)

7-8

MAILBOX DRIVER

Figure 7-7 illustrates the r~ad attention AST function.
In this
figure, an AST is set to notify Process A when Process B issues a read
request for which no message is available.
Process A uses the IO$ SETMODE!IO$M READATTN function to specify an
AST.
When Process B Tssues a read-request to the mailbox, the AST is
delivered to Process A. Process A responds to the AST by sending a
message to the mailbox. The data is then transferred to complete the
I/O operation.
If several requesting processes have set ASTs for read requests at the
same mailbox, all ASTs are delivered when the first read request is
placed in the mailbox. Only the first process to respond with a write
request is able to transfer data to Process B.

AST

AST SPECIFIED BY
10$_SETMODE
!10$M_READATTN

PROCESS
A

PROCESS
B

MAILBOX

DATA

Figure 7-7

7.4

Read Attention AST

I/O STATUS BLOCK

The I/O status blocks (IOSB) for mailbox read and write QIO functions
are shown in Figures 7-8 and 7-9. Table 7-3 lists the status returns
for these functions.
IOSB

byte count

status

sender process identification (Pl D) *
+4
*O if the sender was a system process

Figure 7-8

IOSB Contents - Read Function

7-9

MAILBOX DRIVER
+2
byte count

IOSB

status

receiver process identification (PIO)*
~-~~

*o if 10$M_NQW was specified

Figure 7-9

IOSB Contents - Write Function

Table 7-3
Mailbox QIO Status Returns

-··---------------------------·-Status

Meaning
--··--""---·---·--·--··-----------------------f

SS$ NORMAL

Successful completion. The operation specified
in the QIO was completed successfully. The
second word of the IOSB can be examined to
determine the number of bytes transferred.

SS$ ENDOFFILE

No message available
at
the
mailbox
end-of-file (IO$_ENDOFFILE) message read.

SS$ NOPRIV

Access denied. The requesting process does not
have the privilege to read or write to this
mailbox.
(The protection mask is defined when
the mailbox is created.)

SS$ ACCVIO

Buffer access violation.
User buffer
accessible to the requesting process.

SS$ MBTOOSML

Mailbox too small. The request is for a message
that will not fit in the mailbox. Maximum
message size is established when the mailbox is
created.

SS$ MBFULL

Mailbox full. The mailbox is full and
wait mode is not enabled.

resource

SS$ INSFMEM

Insufficient dynamic memory for the
Resource wait mode is not enabled.

request.

7.5

not

PROGRAMMING EXAMPLE

The following program creates a mailbox and puts some mail in it;
no
matching
read is pending on the mailbox.
First, the program
illustrates that if the function modifier IO$M NOW is not used when
mail is deposited, the write function will waiI until a read operation
is performed on the mailbox. In this case, IO$M NOW is specified and
the program continues after the mail is left in the mailbox.
Next, the mailbox is read. If there was no mail in the mailbox the
program would wait at this point because IO$M NOW is not specified.
IO$M NOW should be specified if there is any doubt concerning the
avaiTability of data in the mailbox and it is important for the
program not to wait.

7-10

MAILBOX DRIVER
It is up to the user to coordinate what data goes into and out of
mailboxes.
In this example the process reads its own message.
Normally, two mailboxes are used for interprocess communication:
one
for sending data from process A to process B, and one for sending data
from process B to process A. If a program is arranged in this manner,
there is no possibility of a process reading its own message.
MAILBOX DRIVER PROGRAMMING EXAMPLE
1011

Define necessary symbols
SIDDEF

;Define 110 function codes

Allocate storage for necessary data structures
Allocate terminal device name strinq and descriptor
oi::v ICl::-DESCR:
.LONG
• LONG
lOS:
.ASCII
20$:

2os-1os

10$
/TERMINAL/

;Length of name string
;Address of name string
;Name string of output device
;Reference label

; Allocate space to store assiqned channel number

DEV l Cr.;_c HAN NE L:
.flLKW

;channel number

Allocate mailbox name
MAILBUX_NAr-1£:
.LONG
.LONG
NAMi'.:BUX: .ASCII

~tring

ENOHOX·NAMEBOX
NA"IEAOX
/146_MAIN_ST/

and descriptor
;Length ot name string
;Address of name string
;Name string
;Reference label

~NDBOX:

!, Allocate space to store assigned channel number
MAILBOX-CHANNEL:
.BLKW
1

:channel number

1 Now allocate space to store the outgoing and incoming messages
fN_BOX-BUFFER:
.BLKB
40
;Allocate 40 bytes for received message
IN-LENGTH=.•IN-AOX-BUFFl::R
;Define input buffer length
OUT-BOX-BUFFER:
.ASCII /SHF.EP ARE VERY DIM/
;Message to send
OUT-LENGTH:. •OIJT_BOX-BUFFER
;Define length of message to send
Now allocate space for the I/O status quadword
STATUS: .OUAD

;l/U status quadword

Now tne Proqram. A mailbox is created and a channel is assigned
to the terminal. A message is put in the mailbox and a message
is received from the mailbox Cthe same message).The contents of
the mailbox Are then Printed on the terminal.
STAR'f:

• WORD
0
; Entry ma sic
SCREMBX_s CHAN=~AILBOX-CHANNEL,-;Channel is tne mailbox
PROMSK=#AXOOOO,;No protection
BUFQUO=#AX0060,;Butter quota is hex 60
LDG~AM=MAILBOX-NAME,;Logical name descriptor
MAXMSG=#AX0060
;Maximum message is hex 60
CMPW
#SS$_NORMAL,RO
;Test for normal return
BSBW
ERROR-CHECK
;See if all well
SASSIGN_s
-;Assign Channel
DEVNAM=DEVICE-DESCR
-;Device descriptor
CHA~=DEVICE-CHANNEL
;Channel
CMPW
#SSS-NORMAL,RO
;Test tor normal return
HSBw
ERROR-CHECK
;See if all is well

7-11

MAILBOX DRIVER
Now we will write the message to the mailbox using the function
modifier IOSM_NOW so that we may continue without waiting for a
read on the mailbox

SOIOw_s fUNC=#IO$_wRITEVBLK!IOSM-NOWlCHAN=MAILBOX-CHANNEL,Pl=OUT-BOX-BUFF~R,-

CMPW
BSBW

P2=#0UT-LENGTH
#SS$_NORMAL,RO
ERROR-CHECK

;write message NOW
;to the mailbox Channel
;Buffer to write
;How mucn to write
;Test for normal return
;see it all is well

Now the mailbox is read
sornw_s FUNC=#IOS-R~ADVBLK •
CHAN:MAILBOX-CHANNEL,•
IDSB:S'f ATUS •
Pl:IN-BOX-BUFFER,•
P2=#IN-LENGTH
CMP~
#SSS-NORMAL,RO
BSBW
ERROR-CHECK

;read box
;Mailbox channel
;Define status to receive message length
;wnere to read it
;How much
;Test for normal return
;see if all is well

Now we find out how mucn mail was in the box and print it to the terminal
The amount of mail read is held in STATUS+2
MOVZWL

STATUS+2 R2

;Put brte count into R2
;Funct on is write
;To the terminal
;Address ot butter to write
;How mucn to write
;Carriage control ClH ,)

sorow_s FUNC=#IOS-WFITEVBLK,CHAN=DEVICE-CHA~NEL,

Pl:IN-AOX-BUFFER,•
P2:R2 •

P4:#3l1

we now deassiqn the channel and exit
EXIT:

SDASSGN_S
RET

CHAN=OEVICE_CHANN~L

;Deassign channel
;Return

This is the error checking part of the program. Normally some Kind ot
error recovery would be attempted nere but not tor this example.
t:RROR-CHECK:

BNEO

EXIT

RSB

.END

;Directive tailed so exit
;E:lse return

START

7-12

CHAPTER 8
DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER

This chapter describes the use of the VAX/VMS DMCll Synchronous
Communications
Line
Interface
driver.
The DMCll provides a
direct-memory-access (DMA)
interface between two computer systems
using the DIGITAL Data Communications Message Protocol (see Section
8.1.l below). The DMCll supports DMA data transfers of up to 16K
bytes at rates of up to 1 million baud for local operation (over
coaxial cable) and 56,000 baud for remote operation (using modems).
Both full- and half-duplex modes are supported.
The DMCll is a message-oriented communications line interface that is
used primarily to link two separate but cooperating computer systems.

8.1

SUPPORTED DMCll SYNCHRONOUS LINE INTERFACES

Table 8-1 lists the DMCll options supported by VAX/VMS.
Table 8-1
Supported DMCll Options
Type

Use

-·--

8.1.1

DMCll-AR with DMCll-FA
DMCll-AR with DMCll-DA

Remote DMCll and EIA or V35/DDS
line unit

DMCll-AL with DMCll-MD
DMCll-AL with DMCll-MA

Local DMCll and lM
bps

bps

DIGITAL Data Communications Message Protocol

To ensure reliable data transmission, the DIGITAL Data Communications
Message Protocol
(DDCMP) has been implemented, using a high-speed
microprocessor, on the VAX-11/780 processor. For remote operations, a
DMCll can communicate with a different type of synchronous interface
(or even a different type of computer), provided the remote system has
implemented DDCMP, version 4.
DDCMP detects errors on the communication line interconnecting the
systems using a 16-bit Cyclic Redundancy Check (CRC). Errors are
corrected, when necessary, by automatic message
retransmission.
Sequence numbers in message headers ensure that messages are delivered
in the proper order with no omissions or duplications.

8-1

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
The DDCMP specification (Order No. AA-D599A-TC) provides more detailed
information on DDCMP.

8.2

DRIVER FEATURES AND CAPABILITIES

DMCll driver capabilities include:
•

A nonprivileged QIO interface to the DMCll.
of the DMCll as a raw-data channel.

•

Unit attention conditions transmitted through
and mailbox messages.

•

Both full- and half-duplex operation.

•

Interface design common
supported by VAX/VMS.

Error logging
• errors.

all

DMCll

all

This

allows

use

attention

ASTs

devices

communications

microprocessor

and

line

unit

• Online diagnostics.
• Separate transmit and receive quotas •
• Assignment of several read buffers to the device.
The following sections describe mailbox usage and I/O quotas.

8.2.1

Mailbox Usage

The device owner process can associate a mailbox with a DMCll by using
the $ASSIGN system service (see Section 7.1.2). The mailbox is used
to receive messages that signal attention conditions about the unit.
As illustrated in Figure 8-1, these messages have the following
content and format:
•

Message type;

this can be any one of the following:

Message type
MSG$ XM DATAVL
MSG$-XM-SHUTDN
MSG$-XM-ATTN

Meaning
Data is available
Unit has been shutdown
A disconnect, timeout,
check occurred

The $MSGDEF macro is used to define message types
•

Physical unit number of the DMCll

•

Size (count) of the ASCII device name string

•

Device name string

8-2

data

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
8 7

16 15

type

unit

count
device name

Figure 8-1

8.2.2

Mailbox Message Format

Quotas

Transmit operations are considered direct
limited by the process's direct I/O quota.

I/O

operations

and

are

The quotas for the receive buffer free list (see Section 8.4.3.4) are
the process's buffered I/O count and buffered I/O byte limit. After
start up, the transient byte count and the buffered I/O byte limit are
adjusted.

8.2.3

Power Failure

When a system power failure occurs, no DMCll recovery
The device is in a fatal error state and is shut down.

8.3

possible.

DEVICE INFORMATION

Users can obtain information on device characteristics by using the
$GETCHN
and
$GETDEV system services
(see Section 1.10).
The
information is returned in a user-specified buffer shown in Figure
8-2. Only the first three longwords of the buffer are shown in Figure
8-2 (Figure 1-9 shows the entire buffer).
31

8 7

16 15

24 23

device characteristics

maximum message size

type

class

not used

error summary

Figure 8-2

status

characteristics

DMCll Information

The first longword in the buffer contains the device characteristics
values listed in Table 8-2. The $DEVDEF macro defines these values.

8-3

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
Table 8-2
DMCll Device Characteristics
Dynamic bit
(Conditionally Set}

Meaning

DEV$M NET

Network device

Static bits
(Always Set}
DEV$M ODV
DEV$M-IDV

Output device
Input device

The second longword contains information on the device class and type,
and the maximum message size.
The device class for the DMCll is
DC$ SCOM. Table 8-3 lists the device types.
The device class and
types are defined by the $DCDEF macro.
Table 8-3
DMCll Device Types
.
1
Meaning

Device Type
1-------····---··· ·--·-··-·

OT$ XM ARDA

DMCll-AR with DMCll-DA

OT$ XM ARFA

DMCll-AR with DMCll-FA

DT$ XM ALMD

DMCll-AL with DMCll-MD

OT$ XM ALMA

DMCll-AL with DMCll-MA

1. Table 8-1 describes the different device types
The maximum message size is the maximum send or receive message size
for the unit.
Messages greater than 512 bytes on modem controlled
lines are more prone to transmission errors and therefore may require
more retransmissions.
The third longword contains unit characteristics and
error summary.

status,

and

Unit characteristics bits govern the DDCMP operating mode.
They are
defined by the $XMDEF macro and can be read or set. Table 8-4 lists
the unit characteristics values and their meanings.

8-4

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
Table 8-4
DMCll Unit Characteristics
Meaning 1

Characteristic
XM$M CHR_M9P

DDCMP maintenance mode

XM$M CHR SLAVE

DDCMP half-duplex slave station

XM$M CHR HDPLX

DDCMP half-duplex

XM$M CHR LOOPB

DDCMP loop back

XM$M CHR MBX

Shows the status of the mailbox
that can be associated with the
unit;
if this bit is set, the
mailbox is enabled to receive
messages signaling unsolicited
data.
(This bit can also be
changed as a subfunction of read
or write QIO functions)

1. Section 8.1.1 describes DDCMP
The status bits show the status of the unit and the line. The values
are defined by the $XMDEF macro. They can be read, set, or cleared as
indicated. Table 8-5 lists the status values and their meanings.
Table 8-5
DMCll Unit and Line Status
Meaning

Status
XM$M STS ACTIVE

Protocol is active. This bit is
set when IO$ SETMODE!IO$ STARTUP
is done and- cleared when the
unit is shut down.
(Read only.)

XM$M STS TIMO

Timeout. If set, indicates that
the
receiving
computer
is
unresponsive. DDCMP time outs.
(Read or clear.)

XM$M STS ORUN

Data overrun. If set, indicates
that a message was received but
lost due to the lack of
a
receive
buffer.
(Read
or
clear.)

XM$M STS DCHK

Data check. If set, indicates
that a retransmission threshold
has been exceeded.
(Read or
clear.)

XM$ M STS DISC

If set, indicates that the Data
Set Ready (DSR) modem line went
from on to off.
(Read
or
clear.)

8-5

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER

The error summary bits are set only when the driver must shut down the
DMCll because a fatal error occurred. These are read-only bits that
are cleared by any of the IO$ SETMODE functions (see Section 8.4.3).
The XM$M STS ACTIVE status -bit is clear if any error summary bit is
set. Table s=n lists the error summary bit values and their meanings.
Table 8-fi
Error Summary Bits

___ _________ ____
.

,,.,.,

Error Summary
Bit

Meaning

---------

8.4

message

XM$M ERR MAINT

DDCMP
maintenance
received

XM$M ERR START

DDCMP START message received

XM$M ERR LOST

Data was lost when a message was
received that was longer than
the specified maximum message
size.

XM$M ERR FATAL

An unexpected hardware/software
error occurred.

DMCll FUNCTION CODES

The basic DMCll function codes are read, write,
three functions take function modifiers.

8.4.l

·and

set

mode.

All

Read

VAX/VMS provides three read function codes:

•
•
•

IO$ READLBLK - read logical block
IO$ READPBLK - read physical block

IO$ READVBLK - read virtual block

Received messages are multi-buffered in system dynamic memory and then
copied to the user's address space when the read operation is
performed.
The QIO arguments for the three function codes are:
•

Pl -- the starting virtual address of the buffer
receive data

•

P2 -- the size of the receive buffer in bytes

that

The read QIO functions can take two function modifiers:
•

IO$M DSABLMBX - disable use of the associated mailbox for
unsolicited data notification

•

IO$M NOW

- complete the read operation immediately if no
message is available

8-6

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
Write

8.4.2

VAX/VMS provides three write QIO function codes:
•

!0$ WRITELBLK - write logical block

•

!0$ WRITEPBLK - write physical block

•

IO$ WRITEVBLK - write virtual block

Transmitted messages are sent directly from the
buffer.

requesting

process's

The QIO arguments for the three function codes are:
•

Pl -- the starting virtual address of
the data to be transmitted

•

P2 -- the size of the buffer in bytes

the

buffer

containing

The message size specified by P2 cannot be larger than the maximum
send message size for the unit (see Section 8.3).
If a message larger
than the maximum size is sent, a status of SS$ DATAOVERUN is
returned
in the I/O status block.
The write QIO functions can take one function modifier:
•

IO$M ENABLMBX - enable use of the associated mailbox

Set Mode

8.4.3

Set mode operations are used to perform protocol,
operational,
and
program/driver
interface operations with the DMCll. VAX/VMS defines
five types of set mode functions:
•

Set Mode

•

Set Characteristics

•

Enable Attention AST

•

Set Mode and Shut Down Unit

•

Set Mode and Start Unit

8.4.3.1 Set Mode and Set Characteristics - These functions set device
characteristics such as maximum message size. VAX/VMS provides two
function codes:
•

IO$ SETMODE -

set mode

•

IO$ SETCHAR privilege)

set

(requires logical I/O privilege)

characteristics

(requires

physical

I/O

One argument is used with these function codes:
Pl -- the virtual address of the quadword characteristics buffer
block
if the characteristics are to be set.
If this argument is
zero, only the unit status and characteristics are
returned
in
the I/O status block (see Section 8.5).
Figure 8-3 shows the Pl
characteristics block.

8-7

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER

Figure 8-3

Pl Characteristics Block

In the buffer designated by Pl the device class is DC$ SCOM.
Table
8-3 (in Section 8.3) lists the device types. The maximum message size
describes the maximum send or receive message size.
The second longword contains device/function-dependent characterises:
unit characteristics, status, and error summary bits. Any of the
characteristics values and some of the status values can be set or
cleared (see Tables 8-4, 8-5, and 8-6).
If the unit is active (XM$M STS ACTIVE is set), the action of a Set
Mode or Set Characteristici fuiiction with a characteristics buffer is
to clear the status bits or the error summary bits. If the unit is
not active, the status bits or the error summary bits can be cleared,
and the maximum message size, type, device
class,
and
unit
characteristics can be changed.

8.4.3.2 Enable Attention AST - This function enables an AST to be
queued when an attention condition occurs on the unit. An AST is
queued when the driver sets or clears either an error summary bit or
any of the unit status bits, or when a message is available and there
is no waiting read request. The Enable Attention AST function is
legal at any time, regardless of the condition of the unit status
bits.
VAX/VMS provides two function codes:
•

IO$ SETMODE!IO$M ATTNAST - enable attention AST

•

IO$ SETCHAR!IO$M ATTNAST - enable attention AST

Enable Attention AST is a single (one-time) enable.
After the AST
occurs, it must be explicitly reenabled by the function before the AST
can occur again. The function code is also used to disable the AST.
The function is subject to AST quotas.
The Enable Attention AST functions take the following
dependent arguments:

device/function

address of AST service routine or 0 for disable

•

(ignored)

access mode to deliver AST

The AST service routine is called with an argument list.
The first
argument is the current value of the device/function dependent
characteristics longword shown in Figure 8-3.
The access mode
specified by P3 is maximized with the requester's access mode.

8-8

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
8.4.3.3 Set Mode and Shut Down Unit - This function stops the
operation on an active unit (XM$M STS ACTIVE must be set) and then
resets the unit characteristics.
VAX/VMS provides two function codes:
•

IO$ SETMODE!IO$M SHUTDOWN - shut down unit

IO$ SETCHAR!IO$M SHUTDOWN - shut down unit

These codes take one device/function dependent argument:
Pl -- the virtual address of the quadword characteristics block
(Figure 8-3)
if modes are to be set after shutdown.
Pl is 0 if
modes are not to be set after shutdown.
These functions stop the DMCll microprocessor and
release
all
outstanding message blocks;
any messages that have not been read are
lost.
The characteristics are reset after shutdown.
Except
for
the
signaling of attention ASTs and mailbox messages, the action of these
functions is the same as the action of the driver when shutdown occurs
because of a fatal error.

8.4.3.4 Set Mode
and
Start
Unit - This
characteristics and starts the protocol on
VAX/VMS provides two function codes:
•

IO$ SETMODE!IO$M STARTUP - start unit

•

IO$ SETCHAR!IO$M STARTUP - start unit

function
sets
the
the associated unit.

These codes take the following device/function dependent arguments:
•

Pl -- the virtual address of the quadword characteristics
block
(Figure 8-3)
if the characteristics are to be set.
Characteristics are set before the device is started.

•

P3
the number of pre-allocated receive-message blocks
ensure the availability of buffers to receive messages.

(ignored).

The total quota taken
is
the DMCll work
specified by P3 times
200-byte, buffers are
256

+ 1200
1456

from the process's buffered I/O byte count quota
space plus the number of receive-message buffers
the maximum message size.
For example,
if six
required, the total quota taken is 1456 bytes:

(DMCll work space)
(number of buffers X buffer size)
(total quota taken)

This quota is returned to the process when shutdown occurs.
Receive-message blocks are used by the driver to receive messages that
arrive
independent of QIO
read
request timing.
When a message
arrives, it is matched with any outstanding read requests.
If there
are no outstanding read
requests,
the message
is queued and an
attention
AST
or
mailbox
message
is
generated.
(IO$ SETMODE!IO$M ATTNAST or IO$ SETCHAR!IO$M ATTNAST must be set to
enable an attention AST;
IO$M ENABLMBX must be used to enable a
mailbox message.)
-

8-9

DMCll SYNCHRONOUS COMMUNICATIONS LINE INTERFACE DRIVER
When read,
the
receive-message
block
is
returned
to
the
receive-message "free list" defined by P3. If the "free list" is
empty, no receive-messages are possible. In this case, a data lost
condition can be generated if a message arrives. This nonfatal
condition is reported by device-dependent data and an attention AST.

8.5

I/O STATUS BLOCK

The I/O status block (IOSB) usage for all DMCll QIO functions is shown
in Figure 8-4.
Table 8-7 lists the status returns for these
functions.
+2

IOSB

transfer size

status

device-dependent characteristics

Figure 8-4

IOSB Content

In Figure 8-4, the transfer size at IOSB+2 is the actual number of
bytes
transferred.
Table
8-4
lists
the
device-dependent
characteristics returned at IOSB+4. These characteristics can also be
obtained by using the $GETCHN and $GETDEV system services (see Section
8. 3) •

Table 8-7
Status Returns for DMCll
Status

Meaning

SS$ ABORT

Fatal hardware
progress.

SS$ DATAOVERUN

Message received
overran
buffer
(read), or message too big (write).

SS$ ENDOFFILE

No data available
specified.

SS$ NORMAL

Operation was successfully
write, or set modes).

SS$ DEVOFFLINE

Device protocol not started (read or write).
The function is inconsistent with the current
state of the unit (Set Mode).

SS$ DEVACTIVE

The function is inconsistent
state of the unit •

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

____

error

(read)

I/O

when

canceled

allocated

IO$M NOW

completed

with

the

was

(read,

current

··-·· -·····-·-··..···-· ·-··· ......------·· · - - - - - - · - - - - - - - - - - - - - - - '

8-10

CHAPTER 9
QIO INTERFACE TO FILE SYSTEM ACPS

An ancillary control process (ACP)
is a process that interfaces
between the user process and the driver, and performs functions that
supplement the driver's functions. Virtual I/O ope~ations involving
file-structured devices
(disks and magnetic tapes) often require ACP
intervention. In most cases, ACP intervention is requested by VAX-11
Record Management Services (RMS)
and is transparent to the user
process. However, user processes can request ACP functions directly
by issuing a QIO request and specifying an ACP function code, as shown
in Figure 9-1.
The DECnet User's
operations.

Guide

User
Process

describes

network

Figure 9-1

(NETACP)

interface

.....

•

ACP

J ACP l

Driver

ACP QIO Interface

This chapter describes the QIO interface to ACPs for disk and magnetic
tape devices
(file system ACPs).
The sample program in Chapter 4
performs QIO operations to the magnetic tape ACP.

9.1

FILE INFORMATION BLOCK

The File Information Block (FIB) contains much of the information that
is exchanged between the user process and the ACP. Figure 9-2 shows
the format of the FIB. Because the FIB is passed by a descriptor
(Pl
in Figure 9-7), its length can vary. Thus a short FIB can be used in
ACP calls that do not need arguments toward the end of the FIB.
The
ACP automatically zero-extends a short FIB. Figure 9-3 shows the
format of a typical short FIB, in this case one that would be used to
open an existing file.
Table 9-1 lists the values of these FIB
fields.

9-1

QIO INTERFACE TO FILE SYSTEM ACPS
24 23

8 7

16 15

FIB$L_ACCTL

FIB$B_WSIZE

·---·-·-·-·---·------------------------!

1 - - - - - - ' ,_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ··--····

FIB$W_FID

FIB$W_DID

FIB$L_WCC

F IB$W_CNTR LFUNC/F IB$W_EXCTL

FIB$W_NMCTL

FI B$L_CNTR LVAL/F I B$L_EXSZ

-------·---·-------- - - - - - - - - - - - - - - - - !
FIB$L_EXVBN
i------·--~-~-~- ~-

_____ ,__ _,,,. .__ . _---- -----r------· -----.----------·-----1

FIB$B_ALALIGN

FIB$B_ALOPTS

FIB$W_ALLOC

.......__________________
Figure 9-2

-----File Information Block Format

24 23

FIB$B_WSIZE

16 15

FIB$L_ACCTL

~~-------Fl-B$_W

___F_ID--------i

FIB$W_DID

FIB$L_wcc

----·- ·--.--------·----·--------------------- --·--·-· -------

FIB$W_NMCTL

--o
etc.

Figure 9-3

Typical Short File Information Block

9-2

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1
Contents of the File Information Block
Field

Field Values

FIB$L ACCTL

Meaning
Specifies field values
that
control access to the file.
The following bits are defined:

FIB$M WRITE

Set for write access;
for read-only access.

FIB$M NOREAD

Set to deny read access to
others.
(The user also must
have write privilege to the
file.)

FIB$M NOWRITE

Set to deny
others.

FIB$M NOTRUNC

Set to prevent the
being
truncated;
allow truncation.

FIB$M DLOCK

Set to enable
(close check).
devices.

write

clear

access

file from
clear to

deaccess lock
Only for disk

Used to
flag
a
file
as
inconsistent in the event the
program currently modifying the
file terminates abnormally. If
the program then closes the
file without performing a write
attributes operation, the file
is marked as locked and cannot
be
accessed
until
it
is
unlocked.
FIB$M_SEQONLY

Set for sequential-only access.
Only for disk devices.

FIB$M REWIND

Set to rewind
before access.

FIB$M CURPOS

Set to create magnetic tape
file at current position (note:
a magnetic tape file will be
created
at the end of the
volume
set
if
neither
FIB$M REWIND nor FIB$M CURPOS
is set). If the tape Ts not
positioned at the end of a
file, FIB$M CURPOS creates a
file at the next file position.

FIB$M UPDATE

Set to position at start of a
magnetic tape file when opening
file for write;
clear
to
position at end-of-file.

magnetic

tape

(continued on next page)

9-3

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field

Field Values

Meaning

- - - - - - - - - - - - - - - - - - - - - - - !--------··-·-·· ·····--··---- - - - - -------t

FIB$L ACCTL
(Cont:)

FIB$M PRSRV ATR

Set to use
span
attribute
system -dependent
recorded in
attribute
Only
for
area.
magnetic tape devices

FIB$M READCK

Set to enable read ch ecking
the file.

FIB$M WRITECK

Set to enable write c hecking of
the file.

FIB$M EXECUTE

Set to access the file
in
execute mode.
The protection
check is made
against
the
EXECUTE bit instead of the READ
bit. Valid only for requBsts
issued
from EXEC or KERNEL
mode.

FIB$M RMSLOCK

Set to declare
RMS
record
locking on the file. All users
of a file must employ the same
configuration of this bit, that
is, if a file is opened with
RMS
record
locking,
other
non-RMS users are locked out.
Valid only for requests issued
from EXEC or KERNEL mode.

J.i'IB$B WSIZE

Controls the size of the file
window used to map a disk file.
The ACP will use the volume
default if FIB$B WSIZE is O. A
value of 1 to 127 indicates the
number of retrieval pointers to
be allocated to the window.
A
value of -1 indicates that the
window should be as large as
necessary to map the entire
file.

FIB$W FID

Specifies
the
file
identification.
The
user
supplies the file identifier
when it is known;
the ACP
returns the file
identifier
when
it becomes k nown, for
example, as a resu l t of
a
create
or director y lookup.
The following subf i elds
are
defined:
FIB$W FID NUM

File number
(continuBd on next page)

9-4

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.}
Contents of the File Information Block
Field

Field Values

Meaning

FIB$W FID
(Cont:-}

FIB$W FID_SEQ

File sequence number

FIB$W FID RVN

Relative volume number

FIB$W DID

Contains the fil~ identifier of
the
directory
file.
The
following
subfields
are
defined:
FIB$W DID NUM

File number

FIB$W DID_SIQ

File sequence number

FIB$W DID RVN

Relative volume number

FIB$L wee

Maintains position context when
processing wild card directory
operations

FIB$W NMCTL

Controls the processing of a
name
string in a directory
operation. The following bits
are defined:
FIB$M WILD

Set if name
wild cards

string

FIB$M ALLNAM

Set to
values

match

all

name

field

FIB$M ALLTYP

Set to
values

match

all

field

type

FIB$M ALLVER

Set to match all version
values

field

FIB$M NEWVER

Set to create file of same name
with
next
higher
version
number. Only for disk devices.

FIB$M_SUPERSEDE

Set to supersede an existing
file of the same name type, and
version.
Only
for
disk
devices.

FIB$M FINDFID

Set to search a directory
the
file
identifier
FIB$W FID

FIB$M LOWVER

Set on return from a CREATE if
a lower numbered version of the
file exists.
Only for disk
devices •

contains

for
in

________ ________ --'-----------(continued on next page}

.___

____,,____

-·~

9-5

--·-------'

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field

Field Values

Meaning

!-----···-··--·--··--·· - - - + - - - - - - - - - - - + - - - - - - - - - - · - - - - - - - - - - - - !

FIB$W NMCTL
(Cont:-)

FIB$M HIGHVER

Set on return from a CREATE if
if a higher numbered version of
the file exists. Only for disk
devices.

FIB$W EXCTL

Specifies extend control for
disk devices.
The following
bits are defined:
FIB$M EXTEND 1

Set to enable extension

FIB$M TRUNC l

Set to enable truncation

FIB$M NOHDREXT

Set to inhibit generation
extension file headers

FIB$M ALCON

Allocate contiguous space

FIB$M ALCONB

Allocate
contiguous
best effort

FIB$M FILCON

Mark file contiguous

FIBSM ALDEF

Allocate
the
extend
size
(FIB$L EXSZ)
or
the system
default, whichever is greater

FIB$M MARKBAD

Set to deallocate blocks to the
bad
block
file
during
a
truncate operation

FIB$M ALLOCATR

Set if placement control data
is present in the attribute
list. For compatibility mode
use.

FIB$W CNTRLFUNC

space;

Controls
magnetic
tape
functions and disk quota file
operations.
This
field
overlays FIB$W EXCTL.
In an
ACPCONTROL
function,
the
FIB$W CNTRLFUNC
field
can
contain one of the following
values:
FIB$C REWINDFIL

Rewind to beginning of file

FIB$C POSEND

Position to end of volume set

FIB$C NEXTVOL

Force next volume

1. Only one of these can be set at one time;
that is, extension
cannot be enabled at the same time truncation is enabled, and vice
versa.
(continued on next page)

9-n

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field
FIB$W CNTRLFUNC
(Cont7)

Field Values

Meaning

FIB$C SPACE

Space n blocks
reverse

FIB$C REWINDVOL

Rewind to beginning
set

FIB$C_ENA_QUOTA

Enable the disk quota filel

FIB$C_DSA_QUOTA

Disable the disk quota filel

FIB$C_ADD_QUOTA

Add an entry to the disk
filel

quota

FIB$C_EXA QUOTA

Examine
entryl

file

FIB$C_MOD_QUOTA

Modify a disk quota file entry 1

FIB$C_REM_QUOTA

Remove a disk quota file entryl

FIB$C LOCK VOL

Allocation lock the volume 1

FIB$C UNLK VOL

Unlock the volume.
FIB$C LOCK VOL.1

FIB$L EXSZ

disk

forward
of

quota

volume

Cancels

Specifies the number of blocks
to allocate to, or remove from,
a disk file depending on the
FIB$W EXCTL
field
configuration.
For
truncate
operations,
this field must
contain O.
The number of blocks actually
allocated
or
removed
is
returned in this longword. The
value
may
differ from the
user-requested value because of
adjustments
for
cluster
boundaries.
More blocks are
allocated
and
fewer blocks
removed
to
meet
cluster
boundaries.

1. Table 9-6 describes the disk quota and lock/unlock bits in
detail.

greater

(continued on next page)

9-7

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field

Field Values

Meaning

t-------------t----------+---------------------~

FIB$L CNTRLVAL

Specifies magnetic tape block
movements or disk quota file
functions. This field overlays
FIB$L EXSZ.
If FIB$C SPACE is indicated,
the
F!BSL CNTRLVAL
field
specifies
the
number
of
magnetic tape blocks to space
forward if positive or space
backward if negative.
The following bits are defined
for disk quota file operations:
FIB$M ALL MEM

disk
Wild card through the
quota file and match all UIC
members

FIB$M ALL GRP

Wild card through the
disk
quota file and match all UIC
groups

FIB$M MOD PERM

If
FIB$C MOD QUOTA
is
specified, change-the permanent
disk quota

FIB$M MOD USE

If
FIBSC MOD QUOTA
is
specified,
change the usage
data.
The volume
must
be
locked by FIB$C LOCK VOL. This
operation requires write access
to the disk quota file.

FIB$L EXVBN

Specifies the starting
disk
file virtual block number at
which the allocated blocks are
to
appear
in
an
extend
operation, or the first virtual
block number to be removed in a
truncate operation. For extend
operations,
this field must
contain either the end-of-file
block number plus 1, or o. For
truncate operations, this field
specifies
the first virtual
block number to be removed.
The
actual starting· virtual
block number of the extend or
truncate operation is returned
in this field.

__________ ________ __________ ------···-·-----'

,__

____._

(continued on next page)

9-8

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field

Field Values

Meaning

!-----------~------------·

···--+---------~·--·- ~-

FIB$B ALOPTS

Contains
option
bits
that
control
the
placement
of
allocated
blocks.
The
following bits are defined:
FIB$M EXACT

Set to require exact placement;
clear to specify approximate
placement.

FIB$M ONCYL

Set to locate allocated
within a cylinder

FIB$B ALALIGN

space

Contains
the
interpretation
mode
of
the
allocation
(FIB$W ALLOC)
field.
One of
the following values can be
specified:
(zero)

No
placement
data.
The
remainder
of the allocation
field is ignored.

FIB$C CYL

Location is specified as
a
dummy longword, followed by a
word Relative Volume
Number
(RVN), followed by a longword
cylinder number.

FIBSC LBN

Location is specified as
a
dummy longword, followed by a
word
RVN,
followed
by
a
longword Logical Block Number
( LBN) •

FIB$C VBN

Location is specified as three
dummy
words
followed by a
longword Virtual Block Number
(VBN)
of
the
file
being
extended. A zero VBN or one
that fails to map indicates the
end of the file.

FIB$C RF!

Location is specified as
a
3-word file ID, followed by a
longword VBN in that file.
A
zero file ID indicates the file
being extended. A zero VBN or
one that fails to map indicates
the end of that file.
(continued on next page)

9-9

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-1 (Cont.)
Contents of the File Information Block
Field

Meaning

Field Values

-1--------------------·----·--"
Contains the desired physical
location of the blocks being
allocated.
Interpretation of
the field is controlled by the
FIB$B ALALIGN
field.
The
following
subfields
are
.defined:

FIB$W ALLOC

FIB$W LOC FID

3-word related file ID for
placement

FIB$W LOC NUM

Related file number

FIB$W_LOC_SEQ

Related file sequence number

FIB$W LOC RVN

Related file RVN
RVN

FIB$W LOC ADDR

Placement LBN, cylinder, or VBN

RFI

placement

Table 9-2 shows which FIB fields and field values are used in the
respective QIO functions.
Some of the FIB fields and values are
applicable only to disk devices or only to magnetic tape devices.
See
Table 9-1.
Table 9-2
FIB Argument Usage in ACP

Q~O

Functions

Applicable Arguments
I/O Function
Field Values

FIB Field

---------------·-""-""'__,.______., __,1--------------IO$ CREATE

FIB$L ACCTL

FIB$M WRITE
FIB$M-NOREAD
FIB$M-NOWRITE
FIB$M-NOTRUNC
FIB$M-DLOCK
FIB$M-SEQONLY
FIB$M-REWIND
FIB$M-CURPOS
FIB$M-UPDATE
FIB$M-PRSRV ATR
FIB$M-READCK
FIB$M-WRITECK
FIB$M EXECUTE
FIB$M-RMSLOCK

---

___________ _ __ __ _____ _ ·----------·--·--·- __ ___________ ---

...___

,,,,

....

... _..., ..

.. _

...._

(continued on next page)

9-10

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-2 (Cont.)
FIB Argument Usage in ACP QIO Functions

Applicable Arguments
I/O Function
FIB Field
IO$ CREATE
(CONT.)

Field Values

FIB$B WSI ZE
FIB$W FID 1

FIB$W FID NUM
FIB$W-FID-SEQ
FIB$W-FID-RVN

FIB$W DID

FIB$W DID NUM
FIB$W-DID-SEQ
FIB$W-DID-RVN

FIB$W NMCTL

FIB$M NEWVER
FIB$M-SUPERSEDE
FIB$M-FINDFID
FIB$M-LOWVER 2
FIB$M-HIGHVER 2

FIB$W EXCTL

FIBSM EXTEND
FIB$M-NOHDREXT
FIB$M-ALCON
FIB$M-ALCONB
FIBSM-FILCON
FIB$M-ALDEF
FIB$M-ALLOCATR

FIB$L EXSZ
FIBSB ALOPTS

FIBSM EXACT
FIB$M-ONCYL

FIB$B ALALIGN

(zero)
FIBSC CYL
FIB$C-LBN
FIB$C-VBN
FIB$C-RFI

FIB$W ALLOC

FIBSW LOC FID
FIBSW-LOC-NUM
FIB$W-LOC-SEQ
FIB$W-LOC-RVN
FIB$W-LOC-ADDR

1. If FIB$W DID= 0 and IO$M CREATE
is
output argument if IO$M CREATE is set.

not

set;

FIB$W FID

2. Output argument
(continued on next page)

9-11

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-2 (Cont.)
FIB Argument Usage in ACP QIO Functions
-

Applicable Arguments
I/O Function
Field Values

FIB Field
t-------··----------·-·---··-·-····---·· ·-····--···---

IO$ ACCESS

""">._,,_,............

--~·

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

....................,.... _.......___ ...

-""----~--

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

FIB$M WRITE
FIB$M NO READ
FIB$M-NOWRITE
FIB$M NOTRUNC
FIB SM DLOCK
FIB$M SEQONLY
FIB$M REWIND
FIB$M- CURPOS
FIB$M- UPDATE
FIB$M PRSRV ATR
FIB$M READCK
FIB$M- WRIT ECK
FIB$M EXECUTE
FIB$M RMS LOCK

FIB$L ACCTL

FIB$B WSIZE

FIB$W FID 1
-

FIB$W FID NUM
FIB$W- FID SEQ
FIB$W- FID- RVN

FIB$W DID NUM
FIB$W-DID- SEQ
FIB SW- DID- RVN

FIB$W DID

FIB$L wee 2

FIB$W NMCTL
-

FIB$M WILD
FIB$M- ALLNAM
FIB$M- ALLTYP
FIB$M- ALL VER
FIB$M FINDFID

IO$ DEACCESS

FIB$W EXCTL

FIB$M TRUNC

FIB$L EXVBN

FIB$W FID 1

IO$ MODIFY

FIB$W FID NUM
FIB SW- FID- SEQ
FIB$W FID RVN

FIB$W DID

-B•·---~-••

1. If FIB$W DID is O;
not 0.
-

FIB$W DID NUM
FIB$W- DID- SEQ
FIBSW-DID- RVN

_ _ _,,_.........--..-.____,_ .__

_____ -·--·- ----·--··----,

...

......

FIB$W FID is an output argument if FIB$W DID is

2. If FIB$M WILD is set.
(continued on next page)

9-12

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-2 (Cont.)
FIB Argument Usage in ACP QIO Functions

Applicable Arguments
I/O Function
FIB Field

IO$ MODIFY
(Cont.)

FIB$L

Field Values

wee 1

FIB$W NMCTL

FIB$W EXCTL

FIB$M WILD
FIB$M-ALLNAM
FIB$M-ALLTYP
FIB$M-ALLVER
FIB$M-FINDFID
3
FIB$M EXTEND
FIBSM-TRUNC
FIB$M-NOHDREXT
FIB$M-ALCON
FIB$M-ALCONB
FIB$M-FILCON
FIBSM-ALDEF
FIB$M-MARKBAD
FIB$M-ALLOCATR

FIB$L EXSZ
FIB$L EXVBN

IO$ DELETE

FIBSB ALOPTS

FIBSM EXACT
FIBSM-ONCYL

FIB$B ALALIGN

(zero)
FIB$C CYL
FIBSC-LBN
FIBSC-VBN
FIBSC-RFI

FIBSW ALLOC

FIBSW LOC FID
FIB$W-LOC-NUM
FIB$W-LOC-SEQ
FIBSW-LOC-RVN
FIB$W-LOC-ADDR

FIB$W FID

FIB$W DID

FIB$W FID NUM
FIB$W-FID-SEQ
FIB$W-FID-RVN
FIBSW DID NUM
FIB SW-DID-SEQ
FIB$W-DID-RVN

1. I f FIB$M WILD is set.
2. I f FIB$W DID is
not 0.
-

FIBSW DID is an output argument i f FIB$W DID is

3. Only FIB$M EXTEND or FIB$ TRUNC can be set at any given time;
cannot both be set at the same time.

they

(continued on next page)

9-13

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-2 (Cont.)
FIB Argument Usage in ACP QIO Functions
Applicable Arguments
I/O Function
FIB Field
IO$ DELETE

ccont.)

Field Values

FIB$L wee 1
FIB$W NMCTL

FIB$M WILD
FIB$M ALLNAM
FIB$M-ALLTYP
FIB$M-ALLVER
FI B$M-FINDFID

FIB$W CNTRLFUNC

FIB$C REWINDFIL
FIB$C-POSEND
FIB$C-NEXTVOL
FIB$C-SPACE
FIB$C-REWINDVOL
FIB$C-ENA QUOTA
FIB$C-DSA-QUOTA
FIB$C-ADD-QUOTA
FIB$C-EXA-QUOTA
FIB$C-MOD QUOTA
FIB$C-REM-QUOTA
FIB$C-LOCK VOL
FIB$C-UNLK-VOL

IO$ MOUNT
(no-arguments used)
IO$ ACPCONTROL

FIB$L CNTRLVAL

FIB$M ALL MEM
FIB$M-ALL-GRP
FIB$M-MOD-PERM
FIB$M-MOD-USE

1. If FIB$M WILD is set.

9.2

ATTRIBUTE CONTROL BLOCK

The attribute control block contains the codes that control the
reading and writing of file attributes, for example, file protection
and record
attributes.
Device/function-dependent
argument
PS
specifies the address of this list. The list consists of a variable
number of 2-longword control blocks, terminated by a zero longword, as
shown in Figure 9-4. The maximum number of attribute control blocks
in one list is 14. Table 9-3 describes the attribute control block
fields.

9-14

QIO INTERFACE TO FILE SYSTEM ACPS

16 15
ATR$W_ TYPE

ATR$W_SIZE

----

ATR$L_ADDR

r-(additional control blocks)

---I

t---

------1

Figure 9-4 Attribute Control Block Format
Table 9-3
Attribute Control Block Fields
Field

Meaning

ATR$W SIZE

Specifies the number of bytes of the attribute
to be transferred. Legal values are from 0 to
the maximum size of the particular attribute
(see Table 9-4).

ATR$W TYPE

Identifies the individual attribute to be read
or written.

ATR$W ADDR

Contains the buffer address of the user's
memory space to or from which the attribute is
to be transferred.
The
particular
I/O
function determines whether the attribute is
read or written, as follows:
I/O Function Operation
Create
Access
Deaccess
Modify
Delete
Mount
ACP Control

Write
Read
Write
Write
Not used
Not used
Not used

Table 9-4 lists the valid attributes for ACP QIO functions.
The
maximum size (in bytes)
is determined by the required attribute
configuration. For example, the file name uses only n bytes, but is
always accompanied by the file type and file version - so a total of
10 bytes is required. Each attribute has two names: one for the code
(for example, ATR$C UCHAR)
and one for the size (for example,
ATR$S_UCHAR).
-

9-15

QIO INTERFACE TO FILE SYSTEM ACPS

Table 9-4
ACP QIO Attributes

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

Attribute
Name

----·-

--------..·------·--

Maximum
Size (bytes)

Meaning

(unnamed) 2

Two-byte file owner UIC plus the next
attribute
and the first byte of
ATR$C UCHAR. Used for compatibility
mode only.

(unnamed) 2

Two-byte file protection plus the
first byte of ATR$C UCHAR. Used for
compatibility mode only.

ATR$C UCHAR 3
ATR$S-UCHAR

ATR$C RECATTR 3
ATR$S-RECATTR

ATR$C FILNAM
ATR$S-FILNAM

Six-byte Radix-SO file name
ATR$C FILTYP and ATR$C FILVER.

plus

ATR$C FILTYP
ATR$S-FILTYP

Two-byte Radix-SO
ATR$C FILVER

plus

ATR$C FILVER
ATR$S-FILVER

ATR$C EXPDAT 2
ATR$S-EXPDAT

ATR$C STATBLK l
ATR$S-STATBLK

ATR$C HEADER 1
ATR$S-HEADER

512

Four-byte file characteristics.
Record attribute area. Section 9.2.1
describes the record attribute area
in detail.

file

type

Two-byte binary version number.
Expiration date in ASCII.
Statistics block.
Section
9.2.2
describes the statistics block in
de ta i 1.
Complete file header.

ATR$C BLOCKSIZE
ATR$S-BLOCKSIZE

ATR$C ASCDATES 2
ATR$S-ASCDATES

Magnetic tape block size.
Revision count (2 binery
bytes),
revision date, creation date, and
expiration date, in ASCII. Format =
DDMMMYY
(revision
date),
HHMMSS
(time),
DDMMMYY
(creation date),
HHMMSS
(time)' DDMMMYY (expiration
date), HHMMSS
(time).
The format
contains no
embedded
spaces
or
commas:
DDMMMYYHHMMSSDDMMMYYHHMMSSDDMMMYYHHMMSS

1. Read-only
2. Protected (can be written to only by system or owner)
3. Locked (can not be written to while the file is locked)
(continued on next page)

9-10

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-4 (Cont.)
ACP QIO Attributes
Attribute
Name

Meaning

Maximum
Size (bytes)

----------r--------+----------------·------ - - - - - ATR$C ALCONTROL
ATR$S ALCONTROL

ATR$C ASCNAME
ATR$S ASCNAME

ATR$S CREDATE 2
ATR$S-CREDATE

ATR$C REVDATE 2
ATR$S-REVDATE

ATR$C EXPDATE 2
ATR$S-EXPDATE

ATR$C UIC 2
ATR$S-UIC

ATR$C FPRO 2
ATR$S-FPRO

ATR$C ACLEVEL 2
ATR$S-ACLEVEL

ATR$C UIC RO 1

File name, type, and
ASCII,
including
name.typ;version

version,
in
punctuation:

64-bit creation date and time.
64-bit revision date and time.
64-bit expiration date and time.
4-byte file owner UIC.
File protection.
File access level.
4-byte file owner UIC

1. Read-only

2. Protected (can be written to only by system or owner)

9.2.1

ACP QIO Record Attributes Area

Figure 9-5 shows the format of the record attributes area.

9-17

QIO INTERFACE TO FILE SYSTEM ACPS
16 15

24 23

FAT$W_RSIZE

___

.,.___

87
FAT$B_RATTRIB

0
FAT$B_RTYPE

FAT$L_HIBLK

·---·--···---·---FAT$l_EFBLK

FAT$B_VFCSIZE

FAT$W_FFBYTE

FAT$B_BKTSIZE

------ - - - - ------

FAT$W_FEFEXT

FAT$W_MAXREC

(reserved for future use)

Figure 9-5 ACP QIO Record Attributes Area
Table 9-5 lists the record attributes values and their meanings.
Table 9-5
ACP Record Attributes Values
Field Value
FAT$B RTYPE

FAT$B RATTRIB

Meaning
Record type.
defined:

The

following

bit

values

are

FAT$C FIXED
FAT$C-VARIABLE
FAT$C-VFC

Fixed record type
Variable length
Variable and fixed control

Record attributes.
defined:

The following bit values are

FAT$M FORTRANCC
FAT$M-IMPLIEDCC
FAT$M-PRINTCC
FAT$M-NOSPAN

FORTRAN carriage control
Implied carriage control
Print file carriage control
No spanned records

FAT$W RSIZE

Record size in bytes

FAT$L HIBLK 1

Highest allocated VBN

FAT$L EFBLK l

End-of-file VBN

FAT$W FFBYTE

First free byte in FAT$L EFBLK

FAT$B BKTSIZE

Bucket size in blocks

FAT$B VFCSIZE

Size in bytes of fixed length
records

FAT$W MAXREC

Maximum record size in bytes

FAT$W DEFEXT

Default extend quantity

1. Inverted format field

9-18

control

for

VFC

QIO INTERFACE TO FILE SYSTEM ACPS
9.2.2

ACP QIO Attributes Statistics Block

Figure 9-6 shows the format of the statistics block.
31

8 7

16 15

start LBN

file size

LCNT

Figure 9-6

ACNT

ACP QIO Attributes Statistics Block

If the file is contiguous, the first longword contains the LBN of the
first
block
of
the
file, that is, the starting LBN.
For
non-contiguous files,
this field is zero.
The second longword
contains the total file size in blocks. The ACNT byte contains the
total number of users who are currently accessing the file. The LCNT
byte contains the number of write locks on the file.
Both start LBN and file size appear as inverted longwords, that
the high- and low-order 16 bits are transposed.
This is
compatibility with PDP-11 software.

9.3

is,
for

ACP FUNCTIONS AND ENCODING

All VAX/VMS ACP functions can be expressed using seven function
and four function modifiers. The function codes are:

codes

creates a directory entry or file

•

IO$ CREATE

•

IOS ACCESS
searches a directory for a
accesses that file, if found

•

IO$ DEACCESS -- deaccesses a file and, if
the-final attributes in the file header

•

IO$ MODIFY -- modifies
allocation

•

IO$ DELETE -- deletes a directory entry and/or file header

•

IO$ MOUNT -- informs the
requires mount privilege

•

IO$_ACPCONTROL -- performs miscellaneous control functions

the

file

ACP

when

specified

specified,

attributes

file

volume

writes

and/or

and

file

mounted;

In addition to the function codes and modifiers, VAX/VMS ACPs take
five device/function-dependent arguments, as shown in Figure 9-7.

9-19

QIO INTERFACE TO FILE SYSTEM ACPS

P1:

Address of FIB descriptor
t--------------------------------------··-------------------· ---·--·-·-·· ·--

P2:

Address of file name string descriptor (optional)

P3:

Address of word to receive resultant string length (optional)

P4:

Address of resultant string descriptor (optional)
- - - - - ------------!

P5:

Address of attribute control block (optional)

___________________________________________________________

.__

Figure 9-7

ACP Device/Function-Dependent Arguments

The first argument, Pl, is the address of the File Information
descriptor. Section 9.1 describes the FIB in detail.

Block

The second argument, P2, is an optional argument used in directory
operations.
It specifies the address of the descriptor for the file
name string to be entered in the directory. The file name itself must
be in read/write memory.
The file name string must have the following format:
name.type;version
or
name.typ.version
where name and type may be any combination of alphanumeric characters,
plus the asterisk (*) and percent (%) characters. The version must
consist of numeric characters or a single asterisk. The total number
of alphanumeric and percent characters in the name and type fields
must not exceed 9 and 3, respectively.
Any number of additional
asterisks may be present.
The wild card characters % and

* are not legal in IOS_CREATE requests.

If any of the bits FIB$M ALLNAM, FIB$M ALLTYP, and FIBSM ALLVER are
set, then the contents-of the corresponding field in the-name string
is ignored and assumed to be *·
Note that the file name string cannot contain a directory string. The
directory is specified by the FIB$W DID field (see Table 9-1). Only
VAX-11 RMS can process directory strings.
Argument P3 is the address of a word
name string length. The resultant
length is returned in P3. P4 is the
buffer to receive the resultant
arguments are optional.

to receive the iesultant file
string is not padded. The actual
address of a descriptor for a
file name string.
Both these

The fifth argument, PS, is an optional argument containing the address
of the attribute control block. Section 9.2 describes the attribute
control block in detail.

9-20

QIO INTERFACE TO FILE SYSTEM ACPS
Figure 9-8 shows the format for the descriptors.
31

16 15

not used

count

address

Figure 9-8

9.3.l

ACP Device/Function Argument Descriptor Format

Create File

This virtual I/O function creates a directory entry and/or a file on a
disk device, or a file on a magnetic tape device.
The function code is:
IO$ CREATE
The function modifiers are:
•

IO$M CREATE

creates a file

•

IO$M ACCESS

opens the file on the user's channel

•

IO$M DELETE
deletes the file (or marks
ApplTcable only to disk devices.

for

deletion).

The device/function-dependent arguments for IO$ CREATE are:
•

Pl -- the address
descriptor.

the

File

Information

Block

•

P2 -- the address of the file
name
string
descriptor
(optional).
The file name is written into the file header;
is a directory is specified, this name is entered in the
directory. If specified for a magnetic tape file, the name is
the name of the created file.

•

P3 -- the address of the word that is to receive the length of
the resultant file name string (optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string (optional).

•

P5 -- the address of a list
of
attribute
descriptors
(optional).
If specified for a disk file, the indicated
attributes are written to the file header. If specified for a
magnetic tape file, P5 is the address of the descriptor list
for the new file.

(FIB)

If the FIB$W DID field of the FIB is nonzero, the name string is
entered in -the disk directory specified by the field.
If the
resultant string descriptor is present, a string representing the full
directory entry is returned. If the address of a word to receive the
resultant string size is specified, the size, in bytes, of the string
is returned. A disk file can also be extended if FIBSM EXTEND is set.
The number of blocks allocated is returned in the second longword of
the IOSB.

9-21

QIO INTERFACE TO FILE SYSTEM ACPS
A disk file header is created if IO$M CREATE is specified.
(The file
ID is returned in FIB$W FID.) If an attribute list is present, the
indicated attributes are written to the file header.
If IO$M DELETE
is specified,
the disk file is marked for deletion.
This function
modifier may only be used
in conjunction with IO$M CREATE and
IO$M_ACCESS.
If IO$M ACCESS is specified,
the disk or magnetic
accessed, that is, opened on the user's channel.

tape

file

In the name control field (FIB$W NMCTL) of the FIB,
the FIB$M NEWVER
and FIB$M SUPERSEDE bits function as described in Table 9-1;
other
flags are Ignored. The wild card context field,
FIB$L_WCC,
is also
ignored.
The FIB$L ACCTL and FIB$W EXCTL
described In Table 9-1.

FIB

fields

are

interpreted

Listed below are the arguments for IO$ CREATE in the order in which
they are used. All other areguments are illegal and must be zero:
IO$M CREATE
FIB$W DID
FIB$W NMCTL
Attribute List
IO$M ACCESS
FIB$L ACCTL
FIB$M EXTEND (disk only)
FIB$W_EXCTL (disk only)
FIB$B ALOPTS
FIB$B ALALIGN
FIB$B ALLOC
IO$M DELETE (disk only)

Access File

9.3.2

This virtual I/O function searches a directory on a disk device, or a
magnetic tape, for a specified file and accesses that file if found.
The function code is:
IO$ ACCESS
The function modifiers are:
•

IO$M CREATE

creates a file

•

IO$M ACCESS

opens the file on the user's channel

9-22

QIO INTERFACE TO FILE SYSTEM ACPS
IO$M CREATE changes the IO$ ACCESS function code to IO$ CREATE if the
directory search failed ~ith a "file not found" ~ondition. The
function is then re-executed as a CREATE. In that case, the argument
interpretations
for
IO$ CREATE
apply,
rather than those for
IO$ ACCESS. If IO$M CREATE-is specified, the file is accessed.
A
file must be accessed before it can be read or written.
The device/function-dependent arguments for IO$ ACCESS are:
of

the

File

Information

Block

(FIB)

•

Pl -- the address
descriptor.

•

P2 -- the address of the file
name
string
descriptor
(optional). If specified for disks, the directory is searched
for this name. If IO$ ACCESS is converted to IO$ CREATE, the
name is entered in -the directory specified by-the FIB. If
specified for magnetic tapes, the name identifies the file
being sought.

•

P3 -- the address of the word that is to receive the length of
the resultant file name string (optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string (optional).

•

P5 -- the address of a list
of
attribute
descriptors
(optional).
If specified for disks, the indicated attributes
are read from the file header.
If specified for magnetic
tapes, the file attributes are returned to the user.

If the FIB$W DID field is nonzero, a search is made for the name
string indicated in a directory specified by the field. If the
resultant string descriptor is present, a string representing the full
directory entry is returned. The size of the string is returned if
the address of the resultant string size word is present.
The file
identifier is returned in FIB$W FID.
Several other FIB fields are used in IO$ ACCESS execution.
In the
FIB$W NMCTL
field,
FIB$M ALLNAM, FIBSM ALLTYP, and FIB$M ALLVER
control matching of the name-fields. If FIB$M WILD is set, FIB$W wee
indicates the position in the directory to resume the search;- on
return, this field contains the position of the directory entry found.
The FIB$L_ACCTL field is interpreted as described in Table 9-1.
If an attribute list is present, the
read.

indicated

file

attributes

Listed below are the arguments for IO$ ACCESS in the order in
they are used. All other arguments are illegal and must be O.
FIB$W DID
FIB$W NMCTL
FIB$W wee
IO$M CREATE
IO$M ACCESS
FIB$L ACCTL
Attribute List
(Extend control data is ignored)
9-23

are
which

QIO INTERFACE TO FILE SYSTEM ACPS
9.3.3

Deaccess File

This virtual I/O function deaccesses a file and, if specified,
final attributes in the file header.

writes

Attributes are written to a disk file if they are present and if the
file was accessed for a write operation.
(If write access and no
attributes are specified, and if FIB$M DLOCK was set when the file was
accessed, the deaccess lock bit is set in the file header, inhibiting
further access to that file.)
The function code is:
IO$ DEACCESS
The device/function-dependent arguments for IOS_DEACCESS are:
•

Pl -- the address
descriptor.

the

File

Information

Block

(FIB)

-- the address of a list
of
attribute
descriptors
• PS(optional).
If specified, the indicated attributes are
written to the file header.
Normally, two arguments are used with IO$ DEACCESS:
the attribute
list and the FIB$L ACCTL field (in that order); the FIB$L_ACCTL flag
bits are ignored. The FIB$W FID field can be nonzero. If so, it must
match the file identifier of-the accessed file.
IO$ DEACCESS takes no
function modifiers.
A truncate operation can also be performed with IO$ DEACCESS, using
the
FIB$W EXCTL
and FIB$L EXVBN arguments described below for
IO$ MODIFY.- In this case, the-arguments are used in the following
order:
Attribute List
FIB$W EXCTL
FIB$L EXVBN

9.3.4

Modify File

This virtual I/O function modifies the file attributes
and/or
allocation of a disk file.
If used with magnetic tape, modify file is
basically a NOP.
The function is:
IO$ MODIFY
The device/function-dependent arguments for IO$_MODIFY are:
of

the

Pl -- the address
descriptor.

•

P2 -- the address of the file
name
string
descriptor
(optional).
If specified, the directory is searched for the
name.

•

P3 -- the address of the word that is to receive the length of
the resultant file name string (optional).

9-24

File

Information

Block

•

(FIB)

QIO INTERFACE TO FILE SYSTEM ACPS
•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string {optional).

•

attribute
descriptors
PS -- the address of a list
of
(optional).
If specified, the indicated attributes are
written to the file header.

An initial search is made for the indicated file string.
The search
is performed the same way, and with the same consequences, as the
IO$ ACCESS search (see Section 9.3.2).
If an attribute list is
present, attributes are written. The file can be either extended or
truncated. If extended (FIB$M EXTEND is set), the amount is indicated
by the extend control data (FIBSL EXSZ) and the total number of blocks
allocated to the file is returned-in the second longword of the IOSB.
If truncated (FIB$M TRUNC is set), the file is shortened to the number
of blocks specified- in FIB$L EXVBN, minus 1.
The file round-up
quantity, that is, the resuiting file size minus the requested file
size, is returned in the second longword of the IOSB.
The FIB$W EXCTL field is interpreted as described in Table 9-1.
FIB$L EXVBN and FIB$ EXSZ are
virtual block number
(VBN)
allocated or truncated.

used to return the actual
and size, respectively, of

starting
the area

The FIB$W NMCTL and FIB$L wee fields are interpreted as described for
IO$ ACCESS.
If an attribute list is present, the indicated file
attributes are written. IO$ MODIFY takes no function modifiers.
Listed below are the legal arguments for IO$ MODIFY in the order in
which they are used. All other arguments are illegal and must be O.
Attribute List
FIB$W DID (disk only)
FIB$W_NMCTL (disk only)
FIB$L_WCC (disk only)
FIB$M_EXTEND (disk only)
FIB$L_EXSZ (disk only)
FIB$W_EXCTL (disk only)
FIB$B_ALOPTS (disk only)
FIB$B_ALALIGN (disk only)
FIB$B ALLOC (disk only)
FIB$M TRUNC (disk only)
FIB$M MARKBAD (disk only)

9.3.5

Delete File

This virtual I/O function
header from a disk file.

removes

9-25

directory

header

and/or

file

QIO INTERFACE TO FILE SYSTEM ACPS
The function code is:
IO$ DELETE
The function modifier is:
IO$M DELETE -- deletes the file {or marks it for deletion)
The device/function-dependent arguments for IO$_DELETE are:
of

the

File

Information

Block

{FIB)

•

Pl -- the address
descriptor.

•

P2 -- the address of the file
{optional).
If specified, the
directory specified by the FIB.

•

P3 -- the address of the word that is to receive the length of
the resultant file name string {optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string {optional).

name
string
descriptor
name is removed from the

A search is made for the directory entry to be deleted. The search is
performed the same way as the IO$ ACCESS search {see Section 9.3.2).
The directory entry is then removed.
The
function
modifier
{IO$M_DELETE) deletes the file header specified by FIB$W_FID.
Listed below are the legal arguments for IO$ DELETE in the order in
which they are used. All other arguments are illegal and must be O.
FIB$W DID
FIB$W NMCTL
FIB$L wee
IO$M DELETE

9.3.6

Mount

This virtual I/O function informs the ACP when a disk or magnetic tape
volume is mounted. Mount privilege is required. IO$ MOUNT takes no
arguments or function modifiers. Note that this function is only a
part of the volume mounting operation. Most of the actual processing
is performed by the MOUNT utility.

9.3.7

ACP Control

This virtual I/O function performs miscellaneous
depending on the arguments specified.
The function code is:
IO$ ACPCONTROL
The function modifier is:
IO$M DMOUNT -- dismounts a volume

9-2n

control

functions,

QIO INTERFACE TO FILE SYSTEM ACPS
The device/function-dependent arguments for IOS_ACPCONTROL are:
Pl -- the address
• descriptor.

the

File

Information

•

P2 -- the address
( opt i on a 1 ) .-

the

file

name

•

P3 -- the address of the word that is to receive the length of
the resultant file name string (optional).

•

P4 -- the address of a descriptor for a buffer that
receive the resultant file name string (optional).

•

P5 -- the address
(optional).

list

Block

string

attribute

(FIB)

descriptor

descriptors

If IO$M DMOUNT is not set, the
FIB
control
function
field
(FIB$W CNTRLFUNC) has one of its field values set. Listed below are
the legal arguments for IO$ ACPCONTROL in the order in which they are
used; all other arguments are illegal and must be 0:
IO$M DMOUNT
FIB$W CNTRLFUNC field values:
FIB$C REWINDFIL
FIB$C POSEND
FIB$C NEXTVOL
FIB$C SPACE
FIB$C REWINDVOL
FIB$C _ENA_QUOTA
FIB$C_DSA_QUOTA
FIB$C_ADD_QUOTA
FIB$C_EXA_QUOTA
FIBSC_MOD_QUOTA
FIB$C_REM_QUOTA
FIB$C LOCK VOL

FIB$C UNLK VOL
FIB$L CNTRLVAL

9.3.7.1 Disk Quotas - Disk quota enforcement is enabled by a quota
file on the volume, or relative volume 1 if the file is on a volume
set. The quota file appears in the volume's master file directory
(MFD) under the name QUOTA.SYS;l.
Figure 9-9 shows the format of the block used to transfer
data to and from the ACP.

9-27

quota

file

QIO INTERFACE TO FILE SYSTEM ACPS
31

0
Flags Longword (DQF$L_FLAGS)

User Identification Code (00F$L_UIC)

Current Usage (DQF$L_USAGE)

_______

Permanent Quota (DOF$L_PERMOUOTA)

.,__

--··--·-·-·-··"- ................................ _____ ....
,

,..,_

Overdraft Limit (0QF$L_OVERDRAFT)
t--------~---------

. ·---.

--~--

(reserved for future use)

---------···· ..... ___..........._
,.,

Figure 9-9

,,,.

Quota File Transfer Block

In the flags longword, the DQF$V_ACTIVE flag bit is set if this
file slot is in use.

quota

IO$ ACPCONTROL functions that transfer quota file data between the
caller
and the ACP use the following device/function-dependent
arguments:
•

P2 -- the address of a descriptor for a data buffer block that
transmits quota file data to the ACP. This block has exactly
the same format as a record in the quota file.

•

P4
the address of a descriptor for a data block that
receives quota file data from the ACP. This block has exactly
the same format as a record in the quota file.

the address of a word that returns the data length.

Table 9-6 describes the FIB$W CNTRLFUNC
bits.

9-28

disk

quota

and

lock/unlock

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-6
Disk Quota and Lock/Unlock Bits
Value
FIB$C_ENA_QUOTA

Meaning
Enable the disk quota file. The quota file, if
present,
is accessed by the ACP and quota
enforcement is turned on. To locate the quota
file,
the directory specified by FIB$W DID is
searched for the name specified in the -string
given by the P2 argument. The result string
and its length are returned in P4 and PS.
The
quota file must be enabled in order to execute
any of the quota file operations listed below.
FIB$C ENA QUOTA can return the following status
values in-the IOSB:
SS$ NOPRIV
SS$-NOQFILE
SS$-BADQFILE
SS$=QFACTIVE

No access to quota file
Quota file does not exist
Quota file has bad format
Quota file is already active

(Any of the common error status values, e.g.,
SS$ BADPARAM and SS$_FCPREADERR, can also be
returned)
FIB$C_DSA_QUOTA

Disable the disk quota file. The quota file is
deaccessed and quota enforcement is turned off.
FIB$C DSA QUOTA can return the following status
values in-the IOSB:
SS$ NOPRIV
No access to quota file
SS$-NOQFILE
Quota file does not exist
SS$-QFNOTACT
Quota file is not active
(Any of the common error status values, e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)

FIB$C_ADD_QUOTA

Add an entry to the disk quota file, using the
UIC and quota specified in the P2 argument
block. FIB$C ADD QUOTA requires write access
to the quota file: The following status values
can be returned in the IOSB:
No access to the quota file
Quota file does not exist, or
is not enabled
SS$_DUPDSKQUOTA Quota entry for UIC already
exists
(Any of the common error status values, e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)
-

SS$ NOPRIV
SS$=NOQFILE

(continued on next page)

9-29

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-6
Disk Quota and Lock/Unlock Bits
Value

Meaning

- - - - - - - - - - - - · · - - - - · -..···t--··- ._.,._,. .. "

FIB$C_EXA_QUOTA

Examine a disk quota file entry.
The entry
whose UIC is specified in the P2 argument block
is returned in the P4 argument block,
and
its
length is returned
in the P3 argument word.
Using two flags
in FIB$L CNTRLVAL,
it
is
possible to wild card through the quota file.
(The ACP
maintains
position
context
in
FIB$L wee,
and each examine call returns the
next matching entry.) The two flags are:
FIB$M ALL MEM
FIB$M-ALL-GRP

Match all UIC members
Match all UIC groups

Read access is required to examine all entries
not belonging to the user.
FIBSC EXA QUOTA can
return the following status values in-the IOSB:
SS$ NOPRIV

No access to quota file
Quota file does not exist,
or
is not enabled
entry
SS$_NODISKQUOTA Specified quota file
does not exist
(Any of the common error status values,
e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)
ss(~NOQFILE

FIB$C_MOD_QUOTA

Modify a disk quota file entry. The quota file
entry specified by the UIC in the P2 argument
block is modified according to the values
in
the block,
as controlled by two flags
in
FIB$L CNTRLVAL:
FIB$M MOD PERM
FIB$M-MOD-USE

Change the permanent quota
Change the usage data

The usage data can be changed only if the
volume is locked by FIB$C LOCK VOL (see below).
FIBSC MOD QUOTA requires- write access.
The
follo~ing- status values can be returned in the
IOSB:
SS$ NOPRIV
ss(=NOQFILE

No access to quota file
Quota file does not exist,
or
is not enabled
entry
SS$_NODISKQUOTA Specified quota file
does not exist
SS$ OVRDSKQUOTA Usage is greater than quota
SS$-ACCONFLICT
Volume is not lock~d
(usage
change)
(Any of the common error status values,
e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)

~----··--···-···-----------'-·---·--·-·------~-- ·-----~-~--~----·-

(continued on next page)

9-30

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-6 (Cont.)
Disk Quota and Lock/Unlock Bits
Value

Meaning

------------+----------- ------------ --.------------!
FIB$C_REM_QUOTA

Remove a disk quota file entry whose UIC
is
specified
in
the
P2
argument
block.
FIB$C REM QUOTA requires write access to the
quota-file.
The following status values can be
returned in the IOSB:
No access to quota file
Quota file does not exist,
or
is not enabled
SS$_NODISKQUOTA Specified quota file
entry
does not exist
SS$ OVRDSKQUOTA Usage is non-zero
(Any of the common error status values,
e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)
SS$ NOPRIV

ss(~NOQFILE

FIB$C LOCK VOL

Allocation lock the volume;
operations which
change the file
structure are not permitted.
This function must be executed
prior
to
rebuilding the quota file.
To issue this
function, the user must either have a system
UIC or SYSPRV privilege, or be the owner of the
volume.
FIB$C LOCK VOL
can
return
the
following status-values in the IOSB:
SS$ NOPRIV
No access to volume
(Any of the common error status values,
e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)

FIB$C UNLK VOL

Unlock the volume • . Cancels FIB$C LOCK VOL.
To
issue this function, the user must either have
a system UIC or SYSPRV privilege,
or be the
owner of the volume.
FIB$C UNLK VOL can return
the following status values-in the IOSB:
SS$ NOPRIV
No access to volume
(Any of the common error status values,
e.g.,
SS$ BADPARAM and SS$ FCPREADERR can also be
returned)

9.4

I/O STATUS BLOCK

Figure 9-10 shows the I/O status block (IOSB) for ACP QIO
Table 9-7 lists the status returns for these functions.

functions.

The file ACP returns a completion status in the first longword of the
IOSB.
In an extend operation, the second longword is used to return
If a contiguous extend
the number of blocks allocated to the file.
operation
(FIB$M ALCON)
fails, the second longword is used to return
the size of the fTle after truncation.
Values returned in the IOSB are most useful during operations
in
compatibility mode.
When executing programs in the native mode, the
user should use the values returned in FIB locations.

9-31

QIO INTERFACE TO FILE SYSTEM ACPS

+2
not used

IOSB

status

Figure 9-10

IOSB Contents - ACP QIO Functions

If an extend operation {including CREATE) was performed, IOSB+4
contains the number of blocks allocated, or the largest available
contiguous space if a contiguous extend operation failed.
If a
truncate operation was performed, IOSB+4 contains the number of blocks
added to the file size to reach the next cluster boundary.
Table 9-7
ACP QIO Status Returns
--------------<<-

Status

Meaning

SS$ ACCONFLICT

Access mode conflict. Requested access mode
conflicted with existing file accesses, for
example, an attempt to op~n a file for a write
when the file is write locked.

SS$ ACPVAFUL

The magnetic tape ACP's virtual address space
is full. Since each volume set has a virtual
page assigned to it, additional volume sets
cannot be handled. Corrective action consists
of starting a different ACP using the unique
switch in MOUNT.

SS$ BADATTRIB

Invalid attribute code or size
read or write attribute list.

SS$ BADCHKSUM

Invalid checksum in the file header.

SS$ BADFILEHDR

Invalid file header, for example, structure is
inconsistent or the storage map indicates
blocks are marked free.

SS$ BADFILENAME

Invalid syntax in file
string contains illegal
larger than 9 characters.

SS$ BADFILEVER

Invalid file version number, that is, a number
greater than 32767.

SS$ BADIRECTORY

Invalid directory file. The file is not a
directory or the file contains invalid data.

SS$ BADPARAM

Invalid parameter list. For example, the FIB
contains
options
not applicable to this
function.

specified

name string.
The
characters, or is

{continued on next page)

9-32

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-7 (Cont.)
ACP QIO Status Returns
Status

Meaning

SS$_BADQFILE

Bad quota file.
format.

SS$ BLOCKCNTERR

Block count error. The number of blocks read
differs from the number of blocks recorded in
the trailer labels. There is a possibility
that a record was skipped or an extra noise
record was read.

SS$ CREATED

File created by an ACCESS
CREATE function modifier.
return.)

SS$ DEVICEFULL

Device full. No free blocks are available on
the device or the number of contiguous blocks
specified in a contiguous request is not
available.

SS$ DIRFULL

Directory if full. An error occurred while
creating a disk file because the directory
specified is full and cannot catalog any more
entries.
A directory is limited to 1024
blocks.

SS$_DUPDSKQUOTA

Duplicate disk quota.
UIC already exists.

SS$ DUPFILENAME

Duplicate file name. Another directory entry
with the same name, type, and version already
exists.

SS$ ENDOFFILE

End-of-file.
End
of
allocated
space
encountered in a virtual I/O operation or an
attempted truncation.

SS$ FCPREADERR

FCP read error. An I/O error occurred when
file structure data, for example, a directory,
was read.

SS$ FCPREWINDERR

File process rewind error.
An
occurred when rewinding a volume.

SS$ FCPSPACERR

File process space error.
An I/O
error
occurred when spacing within a file or spacing
files.

SS$ FCPWRITERR

FCP write error. An I/O error occurred when
file structure data, for example, a directory,
was written.

SS$ FILELOCKED

File deaccess locked. Attempted to access a
locked file. A file becomes locked when it is
accessed with FIB$M DLOCK
set
and
then
deaccessed without wrTting attributes.

The quota file has an invalid

function with a
(A success status

Another quota entry for

I/O

error

(continued on next page)

9-33

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-7 (Cont.)
ACP QIO Status Returns
Status

Meaning
............_..................... ·······-'"·

-----·---~-··-·--·~~~-

·--

SS$ FILENUMCHK

File identifier number check.
contains invalid data.

SS$_FILESEQCHK

File identifier sequence check.
A directory
entry points to a file that has been deleted.

SS$ FI LESTRUCT

The
file
Unsupported
file
structure.
structure
on the accessed volume is not
compatible with the ACP.
For example, an
attempt was made to use a structure level 2
ACP with a structure level 1 disk.

SS$ FILNOTEXP

File not expired. A magnetic tape file that
has not expired cannot be written over unless
the
override
expiration
qualifier
was
specified to MOUNT.

SS$ HEADERFULL

File header map area is full and header
extension is inhibited. This can occur on a
volume's index file in a CREATE operation.

SS$ IDXFILEFULL

Volume index file is full. The maximum number
of files specified at initialization time has
been reached.

SS$ ILLCNTRFUNC

Illegal control function. An illegal function
is specified for IO$_ACPCONTROL.

SS$_ NODISKQUOTA

No disk quota. The specified quota file entry
does not exist.

SS$ NOMOREFILES

No more files exist which match the given wild
card in a file specification string. At least
one file was found, that is, one match was
made.

SS$ NOPRIV

No privilege. Volume or file protection
not allow the requested operation.

SS$_ NOQFILE

No quota file.

SS$ NOSUCHFILE

No such file. No file with the given file
name or file identifier exists. Can be caused
by a directory entry that points to a file
that has been deleted.

SS$ NOTAPEOP

No tape operator. There is no tape operator
and a need to communicate with one exists, for
example, the next volume in a volume set must
be mounted.

SS$ NOTLABELMT

Magnetic tape not labeled. A request to read
a magnetic tape failed because the tape does
not have standard labels.

The index

file

will

The quota file does not exist.

(continued on next page)

9-34

QIO INTERFACE TO FILE SYSTEM ACPS
Table 9-7 (Cont.)
ACP QIO Status Returns
Status

Meaning

SS$_OVRDSKQUOTA

Over disk quota.
Disk usage
(A success status return.)

SS$_QFACTIVE

Quota file is already active.

SS$_QFNOTACT

Quota file not active.

SS$ SUPERSEDE

An existing file of the same name,
type,
and
version has been deleted by a CREATE function.
(A success status return.)

SS$ TAPEPOSLOST

Magnetic tape position lost.

SS$ TOOMANYVER

Too many versions.
The maximum number of file
versions
already exists.
All are higher
versions than the one being created.

SS$ WRTLCK

The device is software write
hardware write lock switch
set.

9-35

exceeds

quota.

locked or the
on the drive is

CHAPTER 10
LABORATORY PERIPHERAL ACCELERATOR DRIVER

This chapter describes the use of the VAX/VMS Laboratory Peripheral
Accelerator
(LPAll-K)
driver and the high-level language procedure
library that interfaces with the LPAll-K driver.
The procedure
library is implemented with callable assembly language routines that
translate arguments into the format required by the LPAll-K driver and
handle buffer chaining operations. Routines for microcode loading and
device initialization are also described.
This chapter is written with the understanding that the reader has
access to a copy of the LPAll-K Laboratory Peripheral Accelerator
User's Guide.

10.l

SUPPORTED DEVICE

The LPAll-K is a peripheral device that controls analog-to-digital
(A/D)
and digital-to-analog (D/A) converters, digital I/O registers,
and real-time clocks. It is connected to the VAX-11 processor through
the UNIBUS Adapter (UBA) •
The LPAll-K is a fast, flexible, and easy to use microprocessor
subsystem that is designed for applications requiring concurrent data
acquisition and data reduction at high rates.
The LPAll-K allows
aggregate analog input and output rates up to 150,000 samples per
second. The maximum aggregate digital input and output rate is 15,000
samples per second.
Table 10-1 lists the useful minimum and maximum LPAll-K configurations
supported by VAX/VMS.

10.1.1

LPAll-K Modes of Operation

The LPAll-K operates
multirequest.

two

distinct

modes:

dedicated

and

In dedicated mode only one user, that is, one request, can be active
at a time, and only analog I/O data transfers are supported. Up to
two A/D converters can be controlled simultaneously.
One
D/A
converter can be controlled at a time. Sampling is initiated either
by an overflow of the real-time clock or by an externally supplied
signal.
Dedicated mode provides sampling rates of up to 150,000
samples per second.

10-1

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-1
Minimum and Maximum Configurations per LPAll-K
Minimum

Maximum

-------··-··--·--·-·-··------------------4----------------------1
1 - DDll-Cx or Dx Backplane

2 - 0011-Cx or Dx Backplanes

1 - KWll-K Real Time Clock

One of the following:

2 -

ADll-K A/D Converters

2 - AMll-K Multiplexers
for ADll-K Converters

ADll-K A/D Converter
AAll-K A/D Converter
DRll-K Digital I/O
Register

1 - AAll-K D/A Converter
5 - DRll-K Digital I/O
Registers

In multirequest mode, sampling from all the devices listed in Table
10-1 is supported.
The LPAll-K operates like a multicontroller
device;
up to eight requests (from one through eight users)
can be
active simultaneously. The sampling rate for each user is a multiple
of the common real-time clock rate.
Independent rates can be
maintained for each user. Both the sampling rate and the device type
are specified as part of each data transfer request.
Multirequest
mode provides a maximum aggregate sampling rate of 15,000 samples per
second.

10.1.2

Errors

The LPAll-K returns three classes of errors:
1.

Errors associated with the issuance of a new LPAll-K
(SS$_DEVCMDERR).

command

Errors associated
(SS$ DEVREQERR) •

with

active

data

transfer

request

which

affect

all

LPAll-K

activity

Fatal hardware
(SS$ CTRLERR) •

errors

Appendix A of the LPAll-K Laboratory Peripheral Accelerator User's
Guide lists these three classes of errors and the specific error codes
for each class. The LPAll-K aborts all active requests if any of the
following conditions occur:
•

Power failure

•

Device timeout

•

Fatal error

Power failure is reported to any active users when power is recovered.
Device timeouts are monitored only when a new command is issued.
For
data transfers, the time between buffer full interrupts is not
defined. Thus, no timeout errors are reported on a buffer to buffer
basis.

10-2

LABORATORY PERIPHERAL ACCELERATOR DRIVER

If a required resource is not available to a process, an error message
is returned immediately. The driver does not place the process in the
resource wait mode.

SUPPORTING SOFTWARE

10.2

The LPAll-K is supported by a device driver, a high-level language
proc~dure
library of support routines, and routines for microcode
loading and device initialization. All data transfer algorithms for
the laboratory data acquisition I/O devices are accomplished by the
LPAll-K. The only purpose for the system software and support
routines is to provide a control path for synchronizing the use of
buffers, specifying requests, and starting and stopping requests.
The LPAll-K driver and the associated I/O interface have the following
features:
•

They permit multiple LPAll-K subsystems on a single UBA.

•

They operate as an integral
system.

part

•

They can be loaded on an
relinking the executive.

operating

the

VAX/VMS

operating

system

without

I/O requests,
function dispatching,
interrupts, and error-reporting for
LPAll-K subsystems.

UBA map
multiple

handle
• They
allocation,
•

The LPAll-K functions as a multibuffered device. Up to eight
buffer areas can be defined per request. Up to eight requests
can be handled simultaneously. Buffer areas can be reused
after the data they contain is processed.

•

Since the LPAll-K chains buffer areas automatically, a start
data transfer request can transfer an infinite and continuous
amount of data.

•

Multiple ASTs are dynamically queued by the driver to indicate
when a buffer has been filled
(the data is available for
processing) or emptied (the buffer is available for new data).

The high-level language support routines have the following features:
•

They translate arguments provided in the high-level language
calls into the format required for the Queue I/O interface.

•

They provide a buffer chaining capability for a multibuffering
environment by maintaining queues of used, in use, and
available buffers.

•

They adhere to all VAX/VMS conventions for calling
use of shareable resources, and reentrancy.

sequences,

•

They can be part of a resident global library,
into a process image as needed.

10-3

linked

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The routines for microcode loading and device initialization have
following features:

the

•

They execute, as separate processes, images which issue I/O
requests.
These
I/O requests initiate microcode image
loading, start the LPAll-K subsystem, and
automatically
configure the peripheral devices on the LPAll-K internal I/O
bus.

•

They can be executed by user or operator request.

•

They can be executed at the request of other processes.

•

They can be executed automatically
initialized and on power recovery.

when

the

system

Figure 10-1 shows the relationship of the supporting software
LPAll-K.

is
the

µCODE LOADING
AND DEVICE
INITIALIZATION
ROUTINES

rvA""iiv'Ms OPERATING SYSTEM -

I
010 REQUESTS

j_
-w-

I
010
INTERFACE

L--

.---

LPA 11-K
DRIVER

1--+l_.,.
•

LPA 11-K

IL ____________ .JI
HIGH LEVEL
ASSEMBLY
LANGUAGE
SUPPORT
ROUTINES

HIGH LEVEL
APPLICATION
PROGRAM

BUFFER
CHAINING
ROUTINES

I
I

DATA
BUFFER
AREAS

DATA

Figure 10-1

10.3

Relationship of Supporting Software to LPAll-K

DEVICE INFORMATION

Users can obtain information on all peripheral data acquisition
devices on the LPAll-K internal I/O bus by using the $GETCHN and
$GETDEV system services
(see Section 1.10).
The LPAll-K-specific
information
is
returned
in
the first three longwords of a
user-specified buffer, as shown in Figure 10-2 (Figure 1-9 shows the
entire buffer).

10-4

LABORATORY PERIPHERAL ACCELERATOR DRIVER

16 15

device characteristics

type

class

device-dependent characteristics

Figure 10-2

LPAll-K Information

The first longword contains device-independent information.
second and third longwords contain device-dependent data.

The

Table 10-2 lists the device-independent
the first longword.

characteristics

returned

Table 10-2
Device-independent Characteristics
Dynamic Bi ts 1
(Conditionally Set)

Meaning

DEV$M AVL

Device is online
and available

Static Bi ts 1
(Always Set)
DEV$M IDV

Input device

DEV$M ODV

Output device

DEV$M RTM

Real-time device

DEV$M SHR

Device is shareable

1. Defined by the $DEVDEF macro.
The second longword contains information on the device class and type.
The device class for the LPAll-K is DC$ REALTIME and the device type
is DT$ LPAll. The $LADEF macro defines these values. Buffer size is
not applicable to the LPAll-K;
this word is O.
The third longword contains LPAll-K characteristics,
that
is,
device-dependent data.
LPAll-K characteristics are set by the set
clock, initialize, and load microcode I/O functions to any one of, or
a combination of, the valu~s listed in Table 10-3.

10-5

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-3
Device-Dependent Characteristics
Field l

Meaning

LA$M MCVALID
LA$S-MCVALID
LA$V-MCVALID

The
load
microcode I/O function (IO$ LOADMCODE)
was performed
successfully. LASM MCVALID is set
by IO$ LOADMCODE. Each microword is verified by
reading it back and comparing it with the specified
value. LA$M MCVALID is cleared if there is no
match.

LA$V MCTYPE
LA$S-MCTYPE

The microcode type, set by the load microcode I/O
function (IO$ LOADMCODE), is one of the following
values:
LA$K MRMCODE
LA$K ADMCODE
LA$K DAMCODE

LA$V CONFIG
LA$S-CONFIG

microcode type is in multi request
mode
microcode type is in dedicated A/D
mode
microcode type is in dedicated D/A
mode

The bit
positions, set by the initialize I/O
function {IO$ INITIALIZE), for the peripheral data
acquisition ~evices on the LPAll-K internal I/O bus
are one or more of the following:
LA$V CLOCKA = Clock A
LA$M-CLOCKA
LA$V CLOCKB
LA$M-CLOCKB

Clock B

LA$V ADl
LA$M-AD1

A/D device 1

LA$V AD2
LA$M-AD2

= A/D device 2

LA$V DA
LA$M-DA

D/A device 1

LA$V DIOl
LA$M-DI01

Digital I/O Buff er 1

LA$V DI02
LA$M-DI02

Digital I/O Buff er 2

LA$V DI03
LA$M-DI03

Digital I/O Buffer 3

LA$V DI04
LA$M-DI04

Digital I/0 Buffer 4

LA$V DIOS = Digital I/O Ruffer 5
LA$M-DI05
1. Values defined by the $LADEF macro.
(continued on next page)

10-(i

LABORATORY PERIPHERAL ACCELERATOR DRIVER

Table 10-3 (Cont.)
Device-Dependent Characteristics
Field 1

Meaning

LA$V RATE
LA$S RATE

The Clock A rate, set by the set clock function
(IO$_SETCLOCK), is one of the following values:

= Stopped
l = l MHz
2 = 100 kHz
3 = 10 kHz
4 = l kHz
5 = 100 Hz
n = Schmidt trigger
7 = Line frequency
0

LA$V PRESET
LA$S-PRESET

The
Clock A preset value set by the set clock
function (IO$ SETCLOCK).
(The value is in the range
0 through 65,535 - in 2's complement form.) The
clock rate divided by the clock preset value yields
the clock overflow rate.

1. Values defined by the $LADEF macro.

10.4

LPAll-K I/O FUNCTION CODES

The LPAll-K I/O functions are:
1.

Load microcode into the LPAll-K.

Start the LPAll-K microprocessor.

Initialize the LPAll-K subsystem.

Set the LPAll-K real-time clock rate.

Start a data transfer request.

The Cancel I/O on Channel ($CANCEL) system service is
data transfers.

10.4.l

used

abort

Load Microcode

This I/O function resets the LPAll-K and loads an image of LPAll-K
microcode.
Physical I/O privilege is required. VAX/VMS defines a
single function code:
10$ LOADMCODE - load microcode

10-7

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The load microcode
arguments:

function

takes

three

device/function

dependent

•

Pl = the starting virtual address of the microcode image
is to be loaded into the LPAll-K

•

P3
the starting microprogram address {usually
LPAll-K that is to receive the microcode

that

the nu·mber of bytes {usually 2048) that are to be loaded
0)

the

If any data transfer requests are active at the time a load microcode
request is issued, the load request is rejected and SSS DEVACTIVE is
returned in the I/O status block.
Each microword is verified by comparing it with the specified value in
memory.
If all words match, that is, if the microcode was loaded
successfully, the driver sets the microcode valid bit {LA$V MCVALID)
in the device-dependent characteristics longword {see Table 10-3). If
there is no match, SS$ DATACHECK is returned in the I/O status block
and LA$V MCVALID is -cleared to indicate that the microcode was not
properly loaded. If the microcode was loaded successfully, the driver
stores one of the microcode type values (LASK MRCODE, LASK ADCODE, or
LA$K_DAMCODE) in the characteristics longword.After a load microcode function is completed, the second word
I/O status block contains the number of bytes loaded.
In addition to SS$ DATACHECK, IO$ LOADMCODE can
in the I/O status olock.

10.4.2

return

the

SS$ DEVACTIVE

Start Microprocessor

This I/O function resets the LPAll-K and starts {or restarts)
the
LPAll-K microprocessor. Physical I/O privilege is required. VAX/VMS
defines a single function code:
IO$ STARTMPROC - start microprocessor
This function code takes no device/function-dependent arguments.
The start microprocessor function can return five error codes in the
I/O
status
block:
SS$ DEVACTIVE, SS$ MCNOTVALID, SS$ CTRLERR,
SS$ POWERFAIL, and SS$ TIMEOUT (see Section TO.h}.

10.4.3. Initialize LPAll-K

This I/O function issues a subsystem initialize command to the
LPAll-K.
This command specifies LPAll-K laboratory I/O device
addresses and other table information for the subsystem. It is issued
only once after restarting the subsystem and before any other LPAll-K
command is given.
Physical I/O privilege is required.
VAX/VMS
defines a single function code:
IO$ INITIALIZE - initialize LPAll-K

10-8

LABORATORY PERIPHERAL ACCELERATOR DRIVER

The initialize LPAll-K function
arguments:

takes

two

device/function-dependent

•

Pl = the starting, word-aligned, virtual address of
the
Initialize Command Table in the user process. This table is
read once by the LPAll-K during the execution of
the
initialize command.
See the LPAll-K Laboratory Peripheral
Accelerator User's Guide for additional information.

•

P2 = length of
bytes)

the

initialize

command

buffer

(always

278

If the initialize function is completed successfully, the appropriate
device
configuration
values
are
set in the device-dependent
characteristics longword (see Table 10-3).
The initialize function can return ten error codes in the I/O status
block:
SS$ IVMODE,
SS$ INCLENGTH, SS$ BUFNOTALIGN, SS$ CTRLERR,
SS$ DEVCMDERR:
SS$ CANCEL,
SS$ INSFMAPREG,
SS$_MCNOTVALID,
SS$=POWERFAIL, and SS$=TIMEOUT (see Section 10.~).
If a device specified in the Initialize Command Table is not in the
LPAll-K configuration, an error condition (SS$ DEVCMDERR) occurs and
the address of the first device not found is returned in the LPAll-K
maintenance status register
(see Section 10.6). A program can use
this characteristic to poll the LPAll-K and determine the current
device configuration.

10.4.4

Set Clock

This virtual function issues a clock control command to the LPAll-K.
The clock control command specifies information necessary to start,
stop, or change the sample rate at which the real-time clock runs on
the LPAll-K subsystem.
If the LPAll-K has more than one user, caution should be exercised
when the clock rate is changed. In multirequest mode, a change ,in the
clock rate will affect all users.
VAX/VMS defines a single function code:
IO$ SETCLOCK - set clock
The set clock
arguments:
•

takes

three

device/function-dependent

P2 = mode of operation. VAX/VMS defines the
start mode word (hexadecimal) values:
1
11

•

function

following

KWll-K Clock A
KWll-K Clock B

P3
clock control and status. VAX/VMS defines the
clock status word (hexadecimal) values:
0
143
145

147
149
148
14D
14F

clock

stop clock
l MHz clock rate
100 kHz clock rate
10 kHz clock rate
1 kHz clock rate
100 Hz clock rate
clock rate is Schmidt trigger 1
clock rate is line frequency
10-9

following

LABORATORY PERIPHERAL ACCELERATOR DRIVER
•

P4 = the 2's complement of the real-time clock preset value.
The range is ln bits for the KWll-K Clock A and 8 bits for the
KWll-K Clock B.

The LPAll-K Laborator_y Peripheral Accelerator User's Guide describes
the clock start modi-word ~nd the clock status word in greater detail.
If the set clock function is completed successfully for Clock A, the
clock rate and preset values are stored in the device-dependent
characteristics longword (see Table 10-3).
The set clock function can return six error codes in the I/O status
block:
SS$ CTRLERR,
SS$ DEVCMDERR,
SS$ CANCEL, SS$_MCNOTVALID,
SS$_POWERFAIL~ and SS$ TIMEOUT (see Section 10.n).

10.4.5

Start Data Transfer Request

This virtual I/O function issues a Data Transfer Start command that
specifies the buffer addresses, sample mode, and sample parameters
used by the LPAll-K. This information is passed to the Data Transfer
Command Table. VAX/VMS defines a single function code:
IO$ STARTDATA - start data transfer request
The start data transfer request function takes one function modifier:
IO$M SETEVF - set event flag
The
start
data
transfer
request
device/function-dependent arguments:

function

takes

four

•

Pl = the starting virtual address of the Data Transfer Command
Table in the user's process

•

P2 = the length in bytes (always
Command Table

•

P3 = the AST address
routine (optional)

•

P4 = the AST address of the buffer overrun completion AST
routine
(optional).
Only used when the buffer overrun bit
(LA$M BFROVRN) is set, that is, a buffer overrun condition is
classTfied as a non-fatal error.

the

40)

normal

the

buffer

Data

Transfer

completion

AST

A buffer overrun condition is not the same as a data overrun
condition.
The LPAll-K fetches data from, or stores data in, memory.
If data cannot be fetched quickly enough, for example, when there is
too much UNIBUS activity, a data underrun condition occurs. If data
cannot be stored quickly enough, a data overrun condition occurs.
After each buffer has been filled or emptied, the LPAll-K obtains the
index number of the next buff er to process from the User Status Word
(USW).
(See Section 2.5 of the LPAll-K Laboratory Peripheral
Accelerator User's Guide). A buffer overrun condition occurs 1f the
LPAll-K fills - or empties buffers faster than the application program
can supply new buffers. For example, buffer overrun can occur when
the sampling rate is too high, the buffers are too small, or the
system load is too heavy.
The LPAll-K driver accesses the 10-longword Data Transfer Command
Table, shown in Figure 10-3, when the Data Transfer Start command is
processed. After the command is accepted and data transfers have
begun, the driver makes no further access to the table.
10-10

LABORATORY PERIPHERAL ACCELERATOR DRIVER
2423

16 15

highest available
buffer and buffer
overrun bit

mode

user status word address

overall data buffer length

overall data buffer address

random channel list length

random channel list address
start
channel
number

channel
increment

delay

number of channels

dwell

event
mark
channel

digital trigger mask

digital
trigger
channel
event mark mask

Figure 10-3

Data Transfer Command Table

In the first longword of the Data Transfer Command Table, the first
two bytes contain the LPAll-K start data transfer request mode word.
(Section 3.4.1 of the LPAll-K Laboratory Peripheral Accelerator User's
Guide describes the functions of this word.)
The third byte contains the number
(0-7) of the highest buffer
available
and
the buffer overrun flag bit (bit 23;
values:
LA$M BFROVRN and LA$V BFROVRN). If this bit is set, a buffer overrun
condTtion is a nonfatal error.
The second longword contains the User Status Word address (see Section
3.4.3 of the LPAll-K Laboratory Peripheral Accelerator User's Guide).
This virtual address points to a 2-byte area in the user process
space, and must be word-aligned.
The third longword contains the size (in bytes) of the overall buffer
area.
The virtual address in the fourth longword is the beginning
address of this area. This address must be longword-aligned.
The
overall buffer area contains a specified number of buffers (the number
of the highest available buffer specified in the first longword plus
one).
Individual buffers are subject to length restrictions:
in
multirequest mode the length must be in multiples of two bytes;
in
dedicated mode the length must be in multiples of four bytes. All
data buffers are virtually contiguous for each data transfer request.

10-11

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The fifth and sixth longwords contain the Random Channel List
(RCL)
length
and
address,
respectively.
The RCL address must be
word-aligned.
The last word in the RCL must have bit 15 set.
(See
Section 3.4.6 of the LPAll-K Laborator Peri heral Accelerator User's
Guide for additional in ormat1on on
RCL.)
The seventh through· tenth longwords contain LPAll-K-specific sample
paramet~rs.
The driver passes these parameters directly to the
LPAll-K.
(See Sections 3.4.7 through 3.4.12 of the LPAll-K Laboratory
Peripheral Accelerator User's Guide
for
a detailed description of
their tunct
--~-·,

rc,-n·s-:T---------

------ -

The start data transfer request function can return 15 error codes
in
the
I/O status block:
SS$ INCLENGTH, SS$ BUFNOTALIGN, SS$ DEVCMDERR,
SS$ CTRLERR, SS$ DEVREQERR~
SS$ ABORT, - SS$ CANCEL,
SS$ EXQUOTA,
SS$-INSFBUFDP,
- SS$ INSFMAPREG,SS$ INSFMEM,
SS$ MCNOTVALID,
SS$=PARITY, SS$_POWERFAIL, and SS$_TIMEOUT-(see Section lO:n).
Data buffers are chained and
reused as the LPAll-K and the user
process dispose of the data.
As each buffer is filled or emptied, the
LPAll-K driver notifies the application process by either setting the
event flag specified by the QIO request efn argument or queueing an
AST.
Since buffer use is a continuing process, the event flag is set
or the AST is queued a number of times.
The user process must clear
the event flag (or receive the AST), process the data, and specify the
next buffer for the LPAll-K to use.
If the set event flag function modifier
(IOSM SETEVF)
is specified,
the event flag is set repeatedly:
when the aata transfer request is
started, on each buffer completion, and when the
request completes.
If IO$M SETEVF is not specified, the event flag is set only when the
request completes.
ASTs are preferred over event flags for synchronizing a
program with
the LPAll-K because AST delivery is a queued process while setting of
event flags is not.
If only event flags are used, it is possible to
lose buffer status.
Three AST addresses can be specified.
For normal data buffer
transactions the AST address specified in the P3 argument is used.
If
the buffer overrun bit in the Data Transfer Command Table is set and
an overrun condition occurs,
the AST address specified in the P4
argument is used.
The AST address specified in the astadr argument of
the QIO
request
is used when the entire data transfer request is
completed.
The astprm argument specified in the QIO request is passed
to all three AST routines.
If insufficient dynamic memory is available to allocate an AST block,
an error
(SS$ INSFMEM)
is
returned.
If the
user does not have
sufficient AST quota remaining to allocate an AST block,
an error
(SS$ EXQUOTA)
is
returned.
In either case, the request is stopped.
Normally, there are never more than three outstanding ASTs per LPAll-K
request.

10.4.6

LPAll-K Data Transfer Stop Command

The Cancel I/O on Channel ($CANCEL) system service is used to abort
data
transfers for a particular process.
When the LPAll-K driver
receives a $CANCEL request, a Data Transfer Stop command is issued to
the LPAll-K.

10-12

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The normal way to stop a data transfer is to set bit 14 of the user
Status Word. If this bit is set, the transfer stops at the end of the
next buffer transaction (see Section 2.5 of the LPAll-K Laboratory
Peripheral Accelerator User's Guide).

10.5

HIGH LEVEL LANGUAGE INTERFACE

VAX/VMS supports several program-callable procedures that provide
access to the LPAll-K. The formats of these calls are documented here
for VAX-11 FORTRAN users. VAX-11 MACRO users must set up a standard
VAX/VMS
argument block and issue the standard procedure CALL.
(Optionally, VAX-11 MACRO users can access the LPAll-K directly
through the use of the device-specific Queue I/O functions described
in Section 10.4.) Users of other high-level languages must specify the
proper subroutine or procedure invocation.

10.5.1

High-level Language Support Routines

VAX/VMS provides 20 high-level language procedures for the LPAll-K.
These procedures are divided into four classes. Table 10-4 lists the
VAX-11 procedures for the LPAll-K.
Table 10-4
VAX-11 Procedures for the LPAll-K
Class

Subroutine

Sweep Control

LPA$ADSWP
LPA$DASWP
LPA$DISWP
LPA$DOSWP
LPA$LAMSKS

Function

LPA$SETADC
LPA$SETIBF
LPASSTPSWP

St art A/D converter sweep
St art D/A converter sweep
St art digital input sweep
St art digital output sweep
Sp ecify
LPAll-K
controller
and
di gital mask words
Sp ecify channel select parameters
Sp ecify buffer parameters
St op sweep

Clock control

LPA$CLOCKA
LPA$CLOCKB
LPA$XRATE

Se t Clock A rate
Se t Clock B rate
Co mpute clock rate and preset value

Data Buff er
Control

LPA$ IBFSTS
LPA$IGTBUF
LPA$ INXTBF
LPA$IWTBUF
LPA$RLSBUF
LPA$RMVBUF

Re turn buff er status
Re turn next available buffer
Al ter buffer order
Re turn next buffer or wait
Re lease buffer to LPAll-K
Re move buffer from device queue

Miscellaneous

LPA$CVADF
LPA$FLTln

Co nvert A/D input to floating point
Co nvert unsigned integer to floating
po int
microcode
and
initialize
Lo ad
LP All-K

LPA$LOADMC

10-13

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.5.1.1 Buffer Queue Control - This section
is
provided
for
informational purposes only. Normally, the user does not need to be
concerned with the details of buffer queues.
Buffer queue control for data
involves the use of three queues:
•

Device queue (DVQ)

•

User queue (USQ)

•

In-use queue (IUQ)

transfers

LPAll-K

subroutines

Each data transfer request can specify from one through eight data
buffer areas.
The user specifies these buffers by address. During
execution of the request, the LPAll-K assigns an index from 0 through
7 when a buffer is referenced.
The DVQ contains the indices of all the buffers that the user has
released, that is, made available to be filled or emptied by the
LPAll-K. For output functions (D/A and digital output), these buffers
contain data to be output by the LPAll-K. For input functions (A/D
and digital input), these buffers are empty and waiting to be filled
by the LPAll-K.
The USQ contains the indices of all buffers that are waiting to be
returned to the user. The LPA$IWTBUF and LPA$IGTBUF calls are used to
return the index of the next buffer in the USQ. For output functions
(D/A and digital output), these buffers are empty and waiting to be
filled by the application program.
For input functions
(A/D and
digital input), these buffers contain data to be processed by the
application program.
The IUQ contains the indices of all buffers that are currently being
processed by the LPAll-K. Normally, the IUQ contains the indices of
two buffers:
•

The buffer currently being filled or emptied by the LPAll-K

•

The next buffer to be filled or emptied by the LPAll-K.
This
is the buffer specified by the next buffer index field in the
User Status Word.

Because the LPAll-K driver requires that at least one buffer be ready
when the input or output sweep is started, the user must call
LPA$RLSBUF before the sweep is initiated.
Figure 10-4 shows the flow between the buffer queues.

10.5.1.2 Subroutine Argument Usage - Table 10-5 describes the general
use of the subroutine arguments. The subroutine descriptions in the
following sections contain additional information on argument usage.
The IBUF, BUF, and ICHN (Random Channel List address) arguments must
be aligned on specific boundaries.
(The VAX-11 FORTRAN User's Guide
describes the alignment of FORTRAN arguments.)

10-14

LABORATORY PERIPHERAL ACCELERATOR DRIVER

BUFFER 0

BUFFER OVERRUN
AST HANDLER
NORMAL BUFFER
AST HANDLER

NORMAL BUFFER
AST HANDLER

•

LPA$1WTBUF
LPA$1GTBUF
(TO APPLICATION
PROGRAM)

HEAD

DEVICE
QUEUE

IN-USE
QUEUE

USER
QUEUE

TAIL

HEAD

LPA$RLSBUF
(FROM APPLICATION
PROGRAM)

Figure 10-4

Buffer Queue Control

Table 10-5
Subroutine Argument Usage

,--------..--------------Argument
IBUF

------------~----~----~---

Meaning
A SO-longword array initialized by the LPASSETIBF
subroutine.
IBUF is the impure area used by the
buffer management subroutines. A unique IBUF array
is required for each simultaneously active request.
IBUF must be longword-aligned.
The first quadword in the IBUF array is an I/O status
block
(IOSB)
for high-level language subroutines.
The LPA$IGTBUF and LPA$IWTBUF subroutines fill this
quadword with the current and completion status (see
Section 10.6).

LBUF

Specifies the size of each data buffer in words (must
be even for dedicated mode sweeps}. All buffers are
the same size. The minimum value for LBUF is 1 for
multirequest
mode
data
transfers and 258 for
dedicated mode data transfers. The aggregate size of
the assigned buffers must be less than 32,7h8 words.
Thus, the maximum size of each buffer (in words)
is
limited to 32,768 divided by the number of buffers.
The LBUF argument length is one word.
(continued on next page)

10-15

LABORATORY PERIPHERAL ACCELERATOR DRIVER

Table 10-5 (Cont.)
Subroutine Argument Usage
----------.-------·---····--··-- ··--·-·-----···----

Argument

Meaning

NBUF

Specifies the number of times the buffers are to be
filled
during the life of the request.
If 0
(default) is specified, sampling is indefinite and
must be stopped with the LPA$STPSWP subroutine. The
NBUF argument length is one longword.

MODE

Specifies sampling options.
MODE bit values are
listed in the appropriate subroutine descriptions.
The default is O.
MODE values can be added to
specify several options.
No options are mutually
exclusive although not all bits may be applicable at
the same time. The MODE argument length is one word.

IRATE

Specifies the clock rate:
0
Clock B overflow or no rate
1 = 1 MHz
2
100 kHz
3
10 kHz
4
1 kHz
5
100 Hz
6
Schmidt trigger
7
Line frequency
The IRATE argument length is one longword.

IP RS ET

Specifies the hardware clock preset value.
This
value is the 2's complement of the desired number of
clock ticks between clock interrupts.
(The maximum
value is the 2's complement of n5,536.) IPRSET can be
computed by the LPASXRATE· subroutine.
The IPRSET
argument length is one word.

DWELL

Specifies the number of hardware clock overflows
between sample sequences in multirequest mode. For
example, if DWELL is 20 and NCHN is 3, then after 20
clock overflows one channel is sampled on each of the
next three successive overflows; no sampling occurs
for
the next 20 clock overflows.
This allows
different users to use different sample rates with
the same hardware clock overflow rate. In dedicated
mode, the hardware clock overflow rate controls
sampling and DWELL is not accessed. Default for
DWELL is 1. The DWELL argument length is one word.

~-----~~·--·---·--~~,_

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

(continued on next page)

10-Hi

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-5 (Cont.)
Subroutine Argument Usage
Meaning

Argument
IEFN

Specifies the event flag number or completion routine
address.
The selected event flag is set at the end
of each buffer transaction. If IEFN is 0 (default),
event flag 22 is used.
IEFN can also specify the address of a completion
routine.
This routine is called by the buffer
management routine when a buffer is available and
when the request is terminated, either successfully
or with an error. The standard VAX/VMS calling and
return sequences are used. The completion routine is
called from an AST routine and is therefore at AST
level.
If IEFN specifies the address of a
completion
routine, the program must call LPA$IGTBUF to obtain
the next buffer. If IEFN specifies an event flag,
the program must call LPA$IWTBUF to obtain the next
buffer and must use the %VAL operator:
, %VAL ( 3) ,

(Event flag 3)

,BFRFULL,

(Address of completion
routine)

The IEFN argument length is one longword.
If multiple sweeps are initiated, they must use
different event flags (the software does not enforce
this policy).
Event flag 23 is reserved for use by the LPASCLOCKA
and LPA$CLOCKB subroutines.
If either of these
subroutines is included in the user program, event
flag 23 cannot be used. Also, if IEFN is defaulted,
event flag 22 cannot be used in the user program.
LDELAY

Specifies the delay, in IRATE units, from the start
event until the first sample is taken. The maximum
value is nS,536; default is 1. The LDELAY argument
length is one word. The LPAll-K supports the LDELAY
argument in multirequest mode only.

ICHN

Specifies the number of the first I/O channel to be
sampled.
Default is channel O. The ICHN argument
length is one byte. The channel number is not the
same as the channel assigned to the device by the
$ASSIGN system service (see Section 1.8.1).
The
LPAll-K uses the channel number to specify the
multiplexer address of an A/D, D/A, or digital I/O
device on the LPAll-K internal I/O bus.
(continued on next page)

10-17

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-5 (Cont.)
Subroutine Argument Usage
Argument

Meaning

i--------------···-----------------------------4
NCHN

Specifies the number of I/O device channels to sample
in a sample sequence.
Default is 1. If the NCHN
argument is 1, the single channel bit is set in the
mode word of the start Request Descriptor Array (RDA)
when the sweep is started.
The RDA contains the
information needed by the LPAll-K for each command
(see the LPAll-K Laboratory Peripheral Accelerator
User's Guide). The NCHN argument length is one word.

IND

Receives the VAX/VMS success or failure code of
call. The IND argument length is one longword.
--~-··--·--------·--""'"'""""'

10.5.2

__ ___
.

the

---------~

LPA$ADSWP - Initiate Synchronous A/D Sampling Sweep

The LPA$ADSWP subroutine initiates A/D sampling through an ADll-K.
The format of the LPA$ADSWP call is as follows:
CALL LPA$ADSWP (IBUF,LBUF,[NBUF], [MODE], [DWELL], [IEFNl, [LDELAY],
[ICHN], [NCHN], [IND])
Arguments are as described in Section
additions:
MODE

with

10.5.1.2,

Specifies sampling options.
VAX/VMS
following sampling option values:
Value

the

following

defines

the

Meaning

Parallel A/D conversion sample algorithm is
used if dual A/D converters are specified
(value
8192).
Absence of this
bit
implies the serial A/D conversion sample
algorithm.

Multirequest mode request. Absence of this
bit implies a dedicated mode request.

512

External trigger
(Schmidt
trigger
1).
Dedicated
mode
only.
(The
LPAll-K
Laboratory Peripheral Accelerator User's
Guide describe·5--· ~-use of an external
trigger.)

1024

Time stamped sampling with Clock B.
The
double word consists of one data word
followed by the value of the LPAll-K's
internal ln-bit counter at the time of the
sample (see Section 2.4.3 in the LPAll-K
Labor a ~~EY.... E>~_r ~-p_~_e r_a 1 Acee 1 er.-~ to_!;:___ User's
Guide). Multi request mode only.

2048

Event marking.
Multirequest mode only.
(The
LPAll-K
Laboratory
Peripheral
Accelerator _____
User's
Guide describes event
........______
marking.)
.

10-18

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Value

Meaning

4096

Start method. If selected, digital input
start.
If not selected, immediate start.
Multirequest mode only.

8192

Dual A/D converters
Dedicated mode only.

16384

Buffer overrun is a nonfatal error.
The
LPAll-K will automatically default to fill
buffer 0 if a buffer overrun condition
occurs.

are

used.

If MODE is defaulted, A/D sampling starts immediately
with absolute channel addressing in dedicated mode.
The LPAll-K does not support delays in dedicated mode.
IND

Returns the success or failure status:
0 = Error in call~ Possible causes are:
LPA$SETIBF
was
not
previously
called;
LPA$RLSBUF was not
previously called; size of data buffers disagrees with
the ,size computed by the LPA$SETIBF call.
1 = successful sweep started
nnn = VAX/VMS status code

10.5.3

LPA$DASWP - Initiate Synchronous D/A Sweep

The LPA$DASWP subroutine initiates D/A output to an AAll-K.
The format for the LPA$DASWP call is as follows:
CALL LPA$DASWP (IBUF,LBUF,[NBUF], [MODE], [DWELL], [IEFN], [LDELAY],
[ICHN], [NCHN], [IND])
Arguments are as described in Section
additions:
MODE

10.5.1.2,

Specifies the sampling options.
following start criteria values:
Value

with
VAX/VMS

the

following

defines

the

Meaning

Immediate start.
for MODE.

Multirequest mode. If not selected,
request is for dedicated mode.

4096

Start method. If selected, digital input
start.
If not selected, immediate start.
Multirequest mode only.

16384

Buffer overrun is a nonfatal error.
The
LPAll-K will automatically default to empty
buffer 0 if a buffer overrun condition
occurs.

10-19

This is the default value
this

LABORATORY PERIPHERAL ACCELERATOR DRIVER
IND

Returns the success or failure status:
O = Error in call. Possible causes are:
LPA$SETIBF
was
not
previously
called;
LPA$RLSBUF was not
previously called; size of data buffers disagrees with
the size computed by the LPA$SETIBF call.

1 = successful sweep started
nnn

10.5.4

= VAX/VMS status code

LPA$DISWP - Initiate Synchronous Digital Input Sweep

The LPA$DISWP subroutine initiates digital input through
LPA$DISWP is applicable in multirequest mode only.

DRll-K.

The format of the LPA$DISWP call is as follows:
CALL LPA$DISWP (IBUF,LBUF,[NBUF], [MODE], [DWELL], [IEFN] ,[LDELAY],
[ICHN], [NCHN], [IND])
Arguments are as described in Section
additions:
MODE

10.5.1.2,

with

Specifies sampling options.
VAX/VMS
following sampling option values:

the

following

defines

the

Meaning

Value
0

Immediate start.
for MODE.

512

External trigger for DRll-K.
(The LPAll-K
Laboratory _ Peripl'!_~ral Accelerator User's
Guide describes the use of an external
trigger.)

1024

Time stamped sampling with Clock B.
The
double word consists of one data word
followed by the value of the internal
LPAll-K, lo-bit, counter at the time of the
sample (see Section 2.4.3 in the LPAll-K
Laboratory Peripheral Ac~elerator User's
Guide).

2048

Event marking.
(The LPAll-K Laboratory
Peripheral
Accelerator
User's
Guide
describes event marking.)

4096

Start method. If selected, digital input
start. If not selected, immediate start.

16384

Buffer overrun is a non-fatal error.
The
LPAll-K will automatically default to fill
buffer 0 if a buffer overrun condition
occurs.

10-20

This is the default value

LABORATORY PERIPHERAL ACCELERATOR DRIVER
IND

Returns the success or failure status:
0 = Error in call. Possible causes are:
LPA$SETIBF
was
not
previously
called;
LPA$RLSBUF was not
previously called; size of data buffers disagrees with
the size computed by the LPA$SETIBF call.
1 = successful sweep started
nnn

10.5.5

= VAX/VMS status code

LPA$DOSWP - Initiate Synchronous Digital Output Sweep

The LPA$DOSWP subroutine initiates digital output through
LPA$DOSWP is applicable in multirequest mode only.

DRll-K.

The format of the LPA$DOSWP call is as follows:
CALL LPA$DOSWP (IBUF,LBUF,[NBUF] ,[MODE] ,[DWELL] ,[IEFN] ,[LDELAY],
[ICHN], [NCHN], [IND])
Arguments are as described in Section
additions:
MODE

10.5.1.2,

Specifies the sampling options.
following values:

Value
0

with
VAX/VMS

the

following

defines

the

Meaning
Immed~ate

start.

This is the default value

for MODE.

IND

512

External trigger for DRll-K (The LPAll-K
Laboratory Peripheral Accelerator User's
Guide describes the use of an external
trigger.)

4096

Start method. If selected, digital input
start. If not selected, immediate start.

ln384

Buffer overrun is a non-fatal error.
The
LPAll-K will automatically default to empty
buffer 0 if a buffer overrun condition
occurs.

10-21

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.5.6

LPA$LAMSKS - Set LPAll-K Masks and NUM Buffer

The LPA$LAMSKS subroutine initializes a user buffer which contains a
number to append to the logical name LPA11$, a digital start word
mask, an event mark mask, and channel numbers for the two masks.
LPA$LAMSKS must be called:
•

By users who intend to use digital
marking

input

starting

•

By users who do not want to use the default of
to LPA11$0

•

If multiple LPAll-Ks are used

LAAO

event

assigned

The format of the LPA$LAMSKS call is as follows:
CALL LPA$LAMSKS (LAMSKB, [NUM], [!UNIT], [!DSC], [!EMC], [IDSW],
[ I EMW] , [ IND ] )
Argument descriptions are as follows:
LAMSKB

Specifies a 4-word array.

NUM

Specifies the number appended to LPA11$. The sweep
is started on the LPAll-K assigned to LPA11$num.

!UNIT

Not
used.
This
compatibility only.

!DSC

Specifies the digital START word channel. Range is
0 through 4.
The !DSC argument length is one byte.

!EMC

Specifies the event MARK word channel. Range is 0
through 4. The !EMC argument length is one byte.

IDSW

Specifies the digital START word
argument length is one word.

mask.

The

IDSW

IEMW

Specifies the event MARK word
argument length is one word.

mask.

The

IEMW

IND

Always equal to l
(success).
present for compatibility only.

This

10.5.7

argument

present

argument

for

LPA$SETADC - Set Channel Information For Sweeps

The LPA$SETADC subroutine establishes channel start and increment
information for the sweep control subroutines (see Table 10-4). The
LPA$SETIBF subroutine must be called to initialize IBUF before
LPA$SETADC is called.
The two formats for the LPA$SETADC call are as follows:
CALL LPA$SETADC (IBUF, [!FLAG], [ICHN], [NCHN], [INC], [IND])
or
IND=LPA$ SET ADC ( IBUF, [I FLAG] , [ ICHN] , [NCHN] , [INC] )

10-22

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Argument descriptions are as follows:
Returns the success or failure status:

IND

0
LPASSETIBF
LPA$SETADC call

was

not

called

prior

the

1 = LPA$SETADC call successful
IBUF

The IBUF array specified in the LPASSETIBF call

I FLAG

Reserved.
This
argument
compatibility only.

ICHN

Specifies the first channel number.
Range is O
through 255;
default is O. The ICHN argument
length is one longword.

present

for

If INC = O, ICHN is the address of a Random
Channel List. This address must be word-aligned.
NCHN

Specifies the number of samples taken
sequence. Default is 1.

INC

Specifies the channel increment.
Default is 1.
If INC is O, ICHN is the address of a Random
Channel List. The INC argument length is one
longword.

10.5.8

per

sample

LPA$SETIBF - Set IBUF Array For Sweeps

The LPA$SETIBF subroutine initializes the IBUF array for use with the
LPA$ADSWP, LPA$DISWP, LPA$DOSWP, LPA$DASWP, LPA$STPSWP, LPA$IWTBUF,
LPA$IGTBUF, LPA$IBFSTS, LPA$RLSBUF, LPA$INXTBF,
LPA$SETADC,
and
LPA$RMVBUF subroutines.
The format of the LPA$SETIBF call is as follows:
CALL LPA$SETIBF (IBUF, [IND], [LAMSKB] ,BUFO, [BUFl, ••• ,BUF7])
Arguments are as described in Section
additions:

10.5.1.2,

with

the

following

IBUF

Specifies a 50-longword array that is initialized
must
be
by
this
subroutine.
IBUF
longword-aligned.
(See Table 10-5 for additional
information on IBUF.)

IND

Returns the success or failure status:
Possible
causes
are:
0
Error in call.
IBUF array not
incorrect number of arguments;
longword-aligned;
buffer
addresses
not
equidistant.
l

LAMSKB

= IBUF initialized successfully

Specifies the name of a 4-word array. This array
allows the use of multiple LPAll-Ks within the
same program because the argument used to start
the sweep is specified by the LPA$LAMSKS call.
(See Section 10.5.n for a description of the
LPA$LAMSKS subroutine.)
10-23

LABORATORY PERIPHERAL ACCELERATOR DRIVER

BUFO, etc.

10.5.9

Specify the names of the buffers.
A maximum of
eight buffers can be specified.
At least two
buffers must be specified to provide continuous
sampling.
The LPAll-K driver requires that all
buffers be contiguous. To ensure this, LPA$SETIBF
verifies
that
all
buffer
addresses
are
equidistant. Buffers must be longword-aligned.

LPA$STPSWP - Stop In-progress Sweep

The LPA$STPSWP subroutine allows a user to stop a
progress.

sweep

that

The format of the LPA$STPSWP call is as follows:
CALL LPA$STPSWP (IBUF,[IWHEN], [IND])
Arguments are as described in Section
additions:

10.5.1.2,

with

the

following

in
the
LPA$DOSWP

LPA$ADSWP,
call that

IBUF

THE IBUF array specified
LPA$DASWP,
LPA$DISWP, or
initiated the sweep.

I WHEN

Specifies when to stop the sweep.
the following values:
O = Abort sweep
system service.

VAX/VMS defines

immediately.
Uses the $CANCEL
This is the default sweep stop.

1 = Stop sweep when the current buffer transaction
is completed.
(This is the preferred way to stop
requests.)
IND

Receives a success or failure code in the standard
VAX/VMS format:
1 = Success
nnn = VAX/VMS error code
system service

10.5.10

issued

LPA$CLOCKA - Clock A Control

The LPA$CLOCKA subroutine sets the clock rate for Clock A.
The format of the LPA$CLOCKA call is as follows:
CALL LPA$CLOCKA (IRATE,IPRSET, [IND], [NUM])

10-24

the

$CANCEL

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Arguments are as described in Section
additions:
IRATE

10.5.1.2,

Specifies the clock rate.
values must be specified:
0
1

2
3
4

n
7

with

the

following

the

following

One

Clock B overflow or no rate
1 MHz
100 kHz
10 kHZ
1 kHz
100 Hz
Schmidt trigger 1
Line frequency

IP RS ET

Specifies the clock preset value. Maximum of 16
bits.
The LPA$XRATE subroutine can be used to
calculate this value. The clock rate divided by
the clock preset value yields the clock overflow
rate.

IND

Receives a success or failure code as follows:
1 = Clock A set successfully
nnn = VAX/VMS error code indicating an I/O error

NUM

10.5.11

Specifies the number to be appended to the logical
name LPA11$.
If defaulted, NUM is O.
This
subroutine sets Clock A on the LPAll-K assigned to
LPA11$num.

LPA$CLOCKB - Clock B Control

The LPA$CLOCKB subroutine provides the user with control of the KWll-K
Clock B.
The format of the LPA$CLOCKB call is as follows:
CALL LPA$CLOCKB ([IRATE] ,IPRSET,MODE,[IND] ,[NUM])
Arguments are as described in Section
additions:
IRATE

10.5.1.2,

Specifies the clock rate.
values must be specified:
0
1
2
3
4

5
6
7

One

with

the

following

the

following

Stops Clock B
1 MHz
100 kHz
10 kHz
1 kHz
100 Hz
Schmidt trigger 3
Line frequency

If IRATE is 0 (default), the clock is stopped
the IPRSET and MODE arguments are ignored.
IP RS ET

and

Specifies the preset value by which the clock rate
is divided to yield the overflow rate. Maximum of
8 bits.
Overflow events can be used to drive
Clock A. The LPA$XRATE subroutine can be used to
calculate the IPRSET value.
10-25

LABORATORY PERIPHERAL ACCELERATOR DRIVER
MODE

Specifies options.
values:
1

VAX/VMS defines the

following

Clock B operates in noninterrupt mode.

2
The feed B to A bit in the Clock B status
register will be set (see Section 3.3 of the
LPAll-K Laboratory Peripheral Accelerator User's
Guide).
Receives a success or failure code as follows:

IND

1 = Clock B set successfully
nnn
NUM

10.5.12

= VAX/VMS error code indicating an I/O error

Specifies the number to be appended to the logical
name LPA11$.
If defaulted, NUM is o.
This
subroutine sets Clock B on the LPAll-K assigned to
LPA11$num.

LPA$XRATE - Compute Clock Rate and Preset Value

The LPA$XRATE subroutine computes the clock rate and preset value for
the
LPA$CLOCKA
and LPA$CLOCKB subroutines using the specified
intersample interval (AINTRVL).
The two formats for the LPA$XRATE call are as follows:
CALL LPA$XRATE (AINTRVL,IRATE,IPRSET,IFLAG)
or
ACTUAL=LPA$XRATE(AINTRVL,IRATE,IPRSET,IFLAG)
Arguments are as described in Section
additions:

10.5.1.2,

with

the

following

AINTRVL

Specifies the intersample time selected by the
user.
The time is expressed in decimal seconds.
Data type is floating point.

IRATE

Receives the computed clock rate as a value from 1
throuqh 5.

IP RS ET

Receives the computed clock preset value.

!FLAG

If the computation is for Clock A, !FLAG is O;
if
for Clock B, !FLAG is not 0 (the maximum preset
value is 255). The !FLAG argument length is one
byte.

ACTUAL

Receives the actual intersample time if called as
a function.
Data type is floating point. If
there are truncation and roundoff errors, this
time
can
be
different
from the specified
intersample time. Note that when LPA$XRATE is
called from VAX-11 FORTRAN programs as a function,
it must be explicitly declared a real function.
Otherwise,
LPA$XRATE
defaults to an integer
function.

10-20

LABORATORY PERIPHERAL ACCELERATOR DRIVER
If AINTRVL is too large or too small to be achieved,
ACTUAL are returned to O.

10.5.13

both

IRATE

and

LPA$IBFSTS - Return Buffer Status

The LPA$IBFSTS subroutine returns information on the buffers used in a
swee~.

The format of the LPA$IBFSTS call is as follows:
CALL LPA$IBFSTS (IBUF,ISTAT)
Argument descriptions are as follows:
in

call

The IBUF array specified
initiated the sweep.

!STAT

Specifies a longword array with as many elements
as
there are buffers involved in the sweep
(maximum of eight). LPA$IBFSTS fills each array
element with the status of the corresponding
buffer:
+2 = Buffer in device queue.
called for this buffer.

the

that

IBUF

LPASRLSBUF has

been

+l = Buffer in user queue. The LPAll-K has filled
(data input) or emptied (data output) this buffer.
0

Buffer is not in any queue.

-1 = Buffer is in the in-use queue, that is, it is
either being filled or emptied or is the next to
be filled or emptied by the LPAll-K.

10.5.14

LPA$IGTBUF - Return Buffer Number

The LPA$IGTBUF subroutine returns the number of the next buffer to be
processed by the application program, that is, the buffer at the head
of the user queue (see Figure 10-4). LPA$IGTBUF should be called by a
completion routine at AST level to determine the next buffer to
process. If an event flag was specified in the start sweep call,
LPA$IWTBUF, not LPA$IGTBUF, should be called.
The formats of the LPA$IGTBUF call are as follows:
CALL LPA$IGTBUF (IBUF,IBUFNO)
or
IBUFNO=LPA$IGTBUF(IBUF)
Arguments are as described in Section
additions:

10.5.1.2,

with
the

following
call

that

IBUF

The IBUF array specified
initiated the sweep.

IBUFNO

Returns the number of the next buffer to be filled
or emptied by the application program.

10-27

the

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-6 lists the possible combinations of IBUFNO and IOSB contents
on the return from a call to LPASIGTBUF. The first four words of the
IBUF array contain the IOSB. If IBUFNO is -1, the IOSB must be
checked to determine the reason.
Table 10-6
LPA$IGTBUF Call - IBUFNO and IOSB Contents

------.. ------------.
IBUFNO

IOSB ( 1)
_,, ___•«-----

-··----~

IOSB (3), (4)

IOSB (2)

.. - -.............. --·- !--·----··

---·M-·•••••••

Meaning

f--····•-""

(byte count)

Normal buffer complete.

-1

No buffers in queue.
Request still active.

-1

No buffers in queue.
Sweep terminated
normally.

-1

VAX/VMS
error code

LPAll-K
ready-out
and ma int.
registers
(only if
SS$ DEVREQERR ,
SS$=CTRLERR,
or
SS$ DEVCMDERR
is returned)

.._.____... _.

10.5.15

___

No buffers in queue.
Sweep terminated due to
error condition.
Section 10.n describes
the VAX/VMS error codes;
Appendix A of the
LPAll-K Laboratory
Peripheral Accelerator
User's Guide lists
the LPAll-K error codes •

.__..___ ... --·-····..-··---------·

LPA$INXTBF - Set Next Buffer to Use

The LPA$INXTBF subroutine alters the normal buffer selection algorithm
to allow the user to specify the next buffer to be filled or emptied.
The specified buffer is reinserted at the head of the device queue.
The two formats of the LPA$INXTBF call are as follows:
CALL .LPA$INXTBF (IBUF,IBUFNO,IND)
or
IND=LPA$INXTBF(IBUF,IBUFNO)
Arguments are as described in Section
additions:

10.5.1.2,

with
in

the

following
call

that

IBUF

The IBUF array specified
initiated the sweep.

IBUFNO

Specifies the number of the next buffer to be
filled or emptied. The buffer must already be in
the device queue.

IND

Returns the result of the call:
0

Specified buffer was not in the device queue

Next buffer was successfully set

10-28

LABORATORY PERIPHERAL ACCELERATOR DRIVER

10.5.16

LPA$IWTBUF - Return Next Buffer or Wait

The LPA$IWTBUF subroutine returns the next buffer to be processed by
the application program, that is, the buffer at the head of the user
queue. If the user queue is empty, LPA$IWTBUF waits until a buffer is
available.
If a completion routine was specified in the call that
initiated the sweep, LPA$IGTBUF, not LPA$IWTBUF, should be called.
The two formats of the LPA$IWTBUF call are as follows:
CALL LPA$IWTBUF (IBUF,[IEFN] ,IBUFNO)
or
IBUFNO=LPA$IWTBUF(IBUF,[IEFN])
Arguments are as described in Section
additions:

10.5.1.2,

with
in

the

following
call

that

IBUF

The IBUF array specified
initiated the sweep.

IEFN

Not used.
This
argument
is
present
for
compatibility only.
(The event flag is the one
specified in the start sweep call.)

IBUFNO

Returns the number of the next buffer to be filled
or emptied by the application program.

Table 10-7 lists the possible combinations of IBUFNO and IOSB contents
on the return from a call to LPA$IWTBUF. The first four words of the
IBUF array contain the IOSB. If IBUFNO is -1, the IOSB must be
checked to determine the reason.
Table 10-7
LPA$IWTBUF Call - IBUFNO and IOSB Contents
IBUFNO

IOSB(l)

IOSB(2)

IOSB(3), (4)

Meaning

(byte count)

Normal buffer complete.

-1

No buffers in queue.
Sweep terminated
no rma 11 y.

-1

VAX/VMS
error code

LPAll-K
ready-out
and maint.
registers
(only if
SS$ DEVREQERR,
SS$=CTRLERR,

or
SS$ DEVCMDERR

is returned)

10-29

No buffers in queue.
Sweep terminated due to
error condition.
Section 10.n describes
the VAX/VMS error codes;
Appendix A of the LPAll-K
Laboratory Peripheral
Accelerator User's Guide
lists the LPAll-K error
codes.

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.5.17

LPA$RLSBUF - Release Data Buffer

The LPA$RLSBUF subroutine declares one or more buffers available to be
filled or emptied by the LPAll-K. LPA$RLSBUF inserts the buffer at
the tail of the device queue (see Figure 10-4).
The format of the LPA$RLSBUF call is as follows:
CALL LPA$RLSBUF (IBUF,[IND] ,INDEXO,INDEXl, ••• ,INDEXN)
Arguments are as described in Section
additions:

10.5.1.2,

with
in

the

IBUF

The IBUF array specified
initiated the sweep.

the

IND

Returns the success or failure status:

following
call

that

0 = Illegal buffer number or incorrect number of
arguments specified, or a double buffer overrun
occurred. A double buffer overrun can occur if
buffer overrun was specified as a nonfatal error,
a buffer overrun occurs, and buffer 0 was not
released {probably on the user queue after a
previous buff er overrun) • LPA$RLSBUF can return a
double buffer overrun error only if buffer overrun
was specified as a nonfatal error.
1 = Buffer(s) released successfully
INDEXO, etc.

Specify the indexes (0-7) of the
released.
A maximum of eight
specified.

buffers
indexes

to be
can be

The LPA$RLSBUF subroutine must be called to release a buffer (or
buffers)
to the device queue before the sweep is initiated.
(See
Section 10.5.1.1 for a discussion on buffer management.) Note that
LPA$RLSBUF does not verify whether or not the specified buffers are
already in a queue. If a buffer is released when it is already in a
queue, the queue pointers will be invalidated.
This can cause
unpredictable results.
If buffer overrun is specified as a nonfatal error, buffer 0 should
not be released before the sweep is initiated. However, if either
LPA$IGTBUF or LPA$IWTBUF returns buffer O, it should be released.
Note that, in this case, buffer 0 is set aside (not placed on a queue)
until the buffer overrun occurs.
If a buffer overrun occurs and
buffer 0 was not released, the LPA$RLSBUF routine returns an error the
next time buffer 0 is released.

10.5.18

LPA$RMVBUF - Remove Buffer from Device Queue

The LPASRMVBUF subroutine removes a buffer from the device queue.
The format of the LPA$RMVBUF call is as follows:
CALL LPA$RMVBUF (IBUF,IBUFNO, [IND])

10-30

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Arguments are as described in Section
additions:

10.5.1.2,

with

the

following

IBUF

The IBUF array specified
initiated the sweep.

call

that

IBUFNO

Specifies the number of the buffer to remove
the device queue.

from

IND

Returns the success or failure status:
0

the

Buff er not found in the device queue

1
Buffer successfully removed
queue

the

device

The LPA$CVADF subroutine converts A/D input values to floating
numbers. LPA$CVADF is provided for compatibility reasons.

point

10.5.19

from

LPA$CVADF - Convert A/D Input to Floating Point

The formats of the LPA$CVADF call are as follows:
CALL LPA$CVADF (IVAL,VAL)
or
VAL=LPA$CVADF(IVAL)
Argument descriptions are as follows:
!VAL

Contains the value (bits 11:0) read from
input. Bits 15:12 are O.

VAL

Receives the floating point value.

10.5.20

the

A/D

LPA$FLT16 - Convert Unsigned 16-bit Integer to Floating Point

The LPA$FLP16 subroutine converts unsigned 16-bit integers to floating
point. LPA$FLT16 is provided for compatibility reasons.
The formats of the LPA$FLT16 call are as follows:
CALL LPA$FLT16 (IVAL,VAL)
or
VAL=LPA$FLT16(IVAL)
Argument descriptions are as follows:
!VAL

An unsigned 16-bit integer.

VAL

Receives the converted value.

10-31

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.5.21

LPA$LOADMC - Load Microcode and Initialize LPAll-K

The LPA$LOADMC subroutine provides a program interface to the LPAll-K
microcode loader.
LPA$LOADMC sends a load request through a mailbox
to the loader process to load microcode and initialize an LPAll-K
(Section 10.7.1 describes the microcode loader process).
The format of the LPA$LOADMC call is as follows:
CALL LPA$LOADMC {[ITYPE] [,NUM] [,IND] [,!ERROR])
Argument descriptions are as follows:
I TYPE

The type of microcode to be
defines the following values:
Value

Meaning

Multirequest mode

Dedicated A/D mode

Dedicated D/A mode

loaded.

VAX/VMS

If the ITYPE argument is defaulted,
mode microcode is loaded.

multirequest

NUM

The number to be appended to the
LPA11$. If defaulted, NUM is o.

logical

IND

Receives the completion status:

name

1 = Microcode loaded successfully.
nnn = VAX/VMS error code
I ERROR

10.6

Provides additional error information.
Receives
the
second
longword of the IOSB if either
SS$ CTRLERR, SS$ DEVCMDERR, or SS$ DEVREQERR is
returned in IND.
Otherwise, the- contents of
!ERROR is undefined.

I/O STATUS BLOCK

The I/O status block format for
the
load
microcode,
start
microprocessor, initialize LPAll-K, set clock, and start data transfer
request QIO functions is shown in Figure 10-5.
0

16 15

byte count

status

LPA11·K
maintenance status

LPA 11 ·K ready-out

Figure 10-5

I/O Functions IOSB Content

10-32

LABORATORY PERIPHERAL ACCELERATOR DRIVER
VAX/VMS status values and the byte count are returned in the first
longword.
Status values are defined by the $SSDEF macro. The byte
count is the number of bytes transferred by a IO$ LOADMCODE request.
If SS$ CTRLERR, SS$ DEVCMDERR, or SS$ DEVREQERR is returned in the
status word,
the second longword contains the LPAll-K Ready-Out
Register and LPAll-K Maintenance Status Register values present at the
completion of the request. The high byte of the Ready-Out Register
contains the specific LPAll-K error code
(see Appendix A of the
LPAll-K Laboratory Peripheral Accelerator User's Guide}.
Table 10-8
lists the status returns for LPAll-K I/O functions.
If high-level language library procedures are used, the status returns
listed in Table 10-8 can be returned from the resultant QIO functions.
Since buffers are filled by these procedures asynchronously,
two I/O
status blocks are provided in the IBUF array:
one for the high-level
language procedures and one for the LPAll-K driver.
The first four
words of the IBUF array contain the IOSB for the high-level language
procedures.
Table 10-8
LPAll-K Status Returns for I/O Functions
Status

Meaning

SS$_ABORT

Request aborted.
A request in progress was
cancelled by the $CANCEL system service.
(Only
for start data transfer request functions.}

SS$ BUFNOTALIGN

Alignment error.
If this error occurs for an
initialize
LPAll-K
request,
the initialize
command table was not word-aligned.
If this
error occurs for a start data transfer request,
there are several possible causes:
•

User status word (USW} not word-aligned

•

Buffer area not longword-aligned

•

Random Channel List (RCL) not word-aligned

SS$ CANCEL

Request cancelled by the $CANCEL system service
before it started.
(Only for the initialize
LPAll-K, set clock,
and start data transfer
request functions.)

SS$ CTRLERR

Controller
error.
(Only
for
the
start
microprocessor,
initialize LPAll-K, set clock,
and start data transfer request functions.) This
is a fatal error that affects all LPAll-K
activity.
If this error occurs, the LPAll-K
terminates all active requests. The third and
fourth words of the IOSB contain the LPAll-K
Ready-out
Status
Register
and Maintenance
Register contents.
In particular, the high byte
of the third word contains the specific LPAll-K
error code
(see Appendix A in the LPAll-K
Laboratory Peripheral Accelerator User's Guide).
(continued on next page)

10-33

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-8 (Cont.)
LPAll-K Status Returns for I/O Functions
Status

Meaning

SS$ DATACHECK

Data check error.
(Only for the load microcode
function.)
A mismatch between the microcode in
memory and the microcode loaded into the LPAll-K
was detected.
The second word of the IOSB
contains the number of
bytes
successfully
loaded.

SS$ DEVACTIVE

Device is active.
(Only for the load microcode
and
start
microprocessor
functions.)
The
microcode cannot be loaded or the microprocessor
cannot be started because there is an active
data transfer request.

SS$ DEVCMDERR

LPAll-K command error.
(Only for the initialize
LPAll-K, set clock, and start data transfer
request functions.)
This error is associated
with the issuance of a new LPAll-K command. The
third and fourth words of the IOSB contain the
LPAll-K
Ready-Out
Status
Register
and
Maintenance Register contents.
In particular,
the high byte of the third word contains the
specific LPAll-K error code.
(See Appendix A in
the LPAll-K Laboratory Peripheral Accelerator
User's Guide).

SS$_DEVREQERR

LPAll-K user request error.
(Only for start
data transfer requests.) The third and fourth
words of the IOSB contain the LPAll-K Ready-Out
Status
Register
and
Maintenance
Register
contents. In particular, the high byte of the
third word contains the specific LPAll-K error
code.
(See Appendix A in the LPAll-K Laboratory
Peripheral Accelerator User's Guide).

SS$_EXQUOTA

AST quota exceeded.
(Only for start
data
transfer requests.) An AST cannot he queued for
a buffer full/empty AST. Normally, a start data
transfer request can require no more than three
AST blocks at a time.

SS$ INSFBUFDP

A UBA-buf f ered datapath was not
allocation.
(Only for start
requests in dedicated mode.)

SS$ INSFMAPREG

Insufficient UBA map registers to map
the
command table or buffer areas.
(Only for the
initialize LPAll-K and start data
transfer
request functions.)
If the map registers were
preallocated when the driver was loaded, the
preallocation should be increased.

SS$ INSFMEM

Insufficient dynamic memory to start request or
allocate an AST block.
(Only for start data
transfer requests.)

available for
data transfer

(continued on next page)

10-34

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 10-8 (Cont.)
LPAll-K Status Returns for I/O Functions
Status
SS$ IVBUFLEN

Meaning
Incorrect length. If this error occurs for an
initialize
LPAll-K
request, the initialize
command table length is not the required 278
bytes.
If this error occurs for a start data
transfer request, there are several possible
causes:
•

Command table length is not the required
bytes

•

Buffer area size is not evenly divisible
the number of buffers assigned

•

Individual buffer size is O

•

Individual buffer size is not a multiple of
2 for a multirequest mode request, or 4 for
a dedicated mode request

•

Random Channel List length is
multiple of 2

•

Bit 15 in the last word
Channel List is not set

0
of

not

the

Random

SS$ IVMODE

Invalid mode.
(Only for the initialize LPAll-K
function.)
The first three bits (2:0) of the
first word in the command table, that is, the
mode word, are not O.

SS$ MCNOTVALID

Microcode has not been successfully loaded.
(Only for the start microprocessor, initialize
LPAll-K, set clock, and start data transfer
request functions.)

SS$ PARITY

Parity error.
(Only for start data transfer
request
in deicated mode.) A parity error
occurred in a USA-buffered datapath.

SS$ POWERFAIL

A power failure occurred while a request was
active.
(Only for the start microprocessor,
initialize LPAll-K, set clock, and start data
transfer request functions.)

SS$ TIMEOUT

Device
timeout.
(Only
for
the
start
microprocessor,
initialize LPAll-K, set clock,
and start data transfer request functions.)
An
interrupt was not received within one second
after the request was issued.

10-35

LABORATORY PERIPHERAL ACCELERATOR DRIVER

10.7

LOADING LPAll-K MICROCODE

The microcode loading and device initialization routines automatically
load microcode on system initialization (if specified in the system
manager's startup file) and on power recovery.
These routines also
allow a nonprivileged user to load microcode and restart the system.
The LPAll-K loader and initialization routines consist of three parts:
•

A microcode loader process which loads any of the three
microcode versions, initializes the LPAll-K, and sets the
clock rate. Loading is initiated by either a mailbox request
or a power recovery AST.
This process requires permanent
mailbox (PRMMBX) and physical I/O privileges.

operator process which
• An
indirect file commands to

accepts operator commands
or
load microcode and initialize an
LPAll-K. This process uses a mailbox to send a load request
to the loader process; temporary mailbox (TMPMBX) privilege
is required.

•

10.7.1

An LPAll-K procedure library routine that provides a program
interface to the LPAll-K microcode loader. The procedure
sends a load request through a mailbox to the loader process
to load microcode and initialize an LPAll-K. Section 10.5.21
describes this routine in greater detail.

Microcode Loader Process

The microcode loader process loads microcode, initializes a specific
LPAll-K, and sets the clock at the default rate (10 kHz interrupt
rate). A bit set in a controller bitmap indicates that the specified
controller was loaded.
The process specifies a power recovery AST,
creates a mailbox whose name {LPASLOADER) is entered in the system
logical name table, and then hibernates.
The correct device configuration is determined automatically.
When
LPAll-K initialization is performed, every possible device {see Table
10-1) is specified as present on the LPAll-K. If the LPAll-K returns
a device not found error, the LPAll-K is reinitialized with that
device omitted.
On receipt of a power recovery AST, the loader process examines the
controller bitmap to determine which LPAll-Ks have been loaded. For
each LPAll-K, the loader process performs the following functions:
•

Obtains device characteristics

•

Reloads the microcode previously loaded

•

Reinitializes the LPAll-K

•

Sets Clock A to the previous rate and preset value

10-36

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.7.2

Operator Process

The operator process loads microcode and initializes an LPAll-K
through the use of either terminal or indirect file commands. The
command input syntax is as follows:
devname/type
Devname is the device name of the LPAll-K to be loaded.
A logical
name can be specified.
However, only one level of logical name
translation is performed. If devname is omitted, LAAO is the default
name.
If /type appears, it specifies one of three types of microcode
to load:
/MULTI REQUEST = multirequest mode
/ANALOG DIGITAL
dedicated A/D mode
/DIGITAL_ANALOG = dedicated D/A mode
If /type is omitted, /MULTI_REQUEST is the default.
After receiving the command, the operator process formats a message
and sends it to the loader process. Completion status is returned
through a return mailbox.

10.8

RSX-llM VERSION 3.1 AND VAX/VMS DIFFERENCES

This section lists those areas where the VAX/VMS and RSX-llM Version
3.1 LPAll-K high-level language support routines differ. The RSX-llM
I/O Drivers Reference Manual provides a detailed description of the
RSX-llM LPAll-K support routines. The exact differences between the
VAX/VMS and RSX-llM routines can be determined by comparing the
descriptions in the RSX-llM manual with the descriptions for the
VAX/VMS routines in the preceding sections of this guide.

10.8.1

Alignment and Length

In VAX/VMS:
•

Buffers must be contiguous.

•

Buffers must be longword-aligned.

•

The Random Channel List must be word-aligned.

•

The IBUF array length
longword-aligned.

10-37

longwords

and

must

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.8.2

Status Returns

In VAX/VMS:
•

The I/O Status Block length is 8
errors are different.

•

Several routines return:
1 -

bytes;

numeric

values

Success

0 - Failure detected in support routine

nnn - VAX/VMS
service.

10.8.3

status

code.

Failure

detected

system

Sweep Routines

In VAX/VMS:
•

If an event flag is specified, it must be
construction.

•

A tenth argument, IND, has been added to return the success or
failure status.

10.8.4

within

%VAL(

General

In VAX/VMS:
LUN argument is not used.
Instead, the NUM argument
• The
specifies the number to be appended to the logical name
LPA11$.
•

All routine names have the prefix LPA$.

•

In the LPA$SETIBF routine, buffer addresses
contiguity.

•

In the LPA$LAMSKS routine, the IUNIT argument is not used.

•

In the LPA$IWTBUF routine, the IEFN argument is not used.
event flag specified in the sweep routine is used.

are

combinations of IBUFNO and I/O Status
• The
returned
by the LPA$IWTBUF and LPA$IGTBUF

checked

for

The

Block values
routines are

different.

10.9

PROGRAMMING EXAMPLES

The following program examples use LPAll-K
procedures and LPAll-K Queue I/O functions.

high

level

Appendix B of the VAX/VMS Real-Time User's Guide contains
on LPAll-K programming --and design cons ide·r-at ions.

10-38

language

information

LABORATORY PERIPHERAL ACCELERATOR DRIVER
10.9.l

LPAll-K High Level Language Program (Program A)

This program is an example of how the LPAll-K high level language
procedures perform an A/D sweep using three buffers. The program uses
default arguments whenever possible to illustrate the
simplest
possible calls. The program assumes that dedicated mode microcode has
previously been loaded into the LPAll-K.
Table 10-9 lists the
variables used in this program.
Table 10-9
Program A Variables
Variable

Description

BUFFER

The data buffer array.
BUFFER is a
guarantee longword-alignment.

IBUF

The LPAll-K high level language
IBUF array for local storage.

BUFNUM

BUFNUM contains the buffer number
returned
by
LPA$IWTBUF.
In this example, the possible values are
0, 1, and 2.

!STAT

!STAT contains the status return from the high
language calls.

common

area

procedures

use

the

'--------'------------------------------------

level

_________,

*******************************************************************

PROGRAM A

c
c

**************************************~***************************

INTEGER* 2
INTEGER*4

BUFFER(l000,0:2) ,IOSB(4)
IBUF(50) ,ISTAT,BUFNUM

COMMON/AREAl/BUFFER
EQUIVALENCE

(IOSB(l) ,IBUF(l))

c
C

c
c

c
C
C

SET CLOCK RATE TO 100 KHZ, CLOCK PRESET TO -10
CALL LPA$CLOCKA(2,-10,ISTAT)
IF (.NOT. !STAT) GO TO 950
INITIALIZE IBUF ARRAY FOR SWEEP
CALL LPA$SETIBF ( IBUF, I STAT,, BUFFER ( l, 0) , BUFFER ( l, l) , BUFFER ( l, 2))
IF (.NOT. !STAT) GO TO 950
RELEASE ALL THE BUFFERS. NOTE USE OF BUFFER NUMBERS RATHER THAN
BUFFER NAMES.

c
c
C

CALL LPA$RLSBUF(IBUF,ISTAT,O,l,2)
IF (.NOT. !STAT) GO TO 950
START A/D SWEEP

10-39

LABORATORY PERIPHERAL ACCELERATOR DRIVER
CALL LPA$ADSWP(IBUF,1000,50,,,,,,,ISTAT)
IF (.NOT. !STAT) GO TO 950

c
C
C

GET NEXT BUFFER FILLED WITH DATA.
IF BUFNUM IS NEGATIVE, THERE
ARE NO MORE BUFFERS AND THE SWEEP IS STOPPED.
BUFNUM = LPA$IWTBUF(IBUF)
IF (BUFNUM .LT. 0) GO TO 800

100

c
C

PROCESS DATA IN BUFFER(l,BUFNUM) TO BUFFER (1000,BUFNUM)

(Application-dependent code is inserted at this point)

RELEASE BUFFER TO BE FILLED AGAIN

c
200

CALL LPA$RLSBUF(IBUF,ISTAT,BUFNUM)
IF (.NOT. !STAT) GO TO 950
GO TO 100

c
C
C
C

THERE ARE NO MORE BUFFERS TO PROCESS. CHECK TO ENSURE THAT THE
SWEEP ENDED SUCCESSFULLY. IOSB(l) CONTAINS EITHER 1 OR A
VAX/VMS STATUS CODE.

c
800

IF (.NOT. IOSB(l)) CALL LIB$STOP(%VAL(IOSB(l)))
PRINT *,'SUCCESSFUL COMPLETION'
GO TO 2000

c
C
C

ERROR RETURN FROM SUBROUTINE. !STAT CONTAINS EITHER 0 OR
VAX/VMS ERROR CODE.

950

IF (!STAT .NE. 0) CALL LIB$STOP(%VAL(ISTAT))
PRINT
*,'ERROR IN LPAll-K SUBROUTINE CALL'
STOP
END

2000

*******************************************************************

10.9.2

LPAll-K High-level Language Program (Program B)

This program is a more complex example of LPAll-K operations performed
by
the
LPAll-K high-level language procedures.
The following
operations are demonstrated:
•

Program-requested loading of LPAll-K microcode

•

Setting the clock at a specified rate

•

Use of nondefault arguments whenever possible

•

An A/D sweep that uses an event flag

•

A D/A sweep that uses a completion routine

•

Buffer overrun set (buffer overrun is a non-fatal error)

•

Random Channel List addressing

•

Sequential Channel addressing
10-40

LABORATORY PERIPHERAL ACCELERATOR DRIVER

Table 10-10 lists the variables used in this program.
Table 10-10
Program B Variables
Variable

Description

An array of buffers for an A/D sweep
500 words each)

buffers

An array of buffers for a D/A
2000 words each)

sweep

buffers

IBUFAD

The IBUF array for an A/D sweep

I BU FDA

The IBUF array for a D/A sweep

RCL

The array containing the Random Channel List

ADIOSB

The array that contains the I/O status block for the
A/D sweep. Equivalenced to the beginning of IBUFAD.

DAIOSB

The array that contains the I/O status block for the
D/A sweep. Equivalenced to the beginning of IBUFDA.

I STAT

Contains the status
language calls

return

from

the

high-level

·--T~~

*******************************************************************

PROGRAM B

*******************************************************************

EXTERNAL FILLBF
REAL*4 LPA$XRATE
INTEGER*2 AD(500,0:7) ,DA(2000,0:l) ,RCL(5) ,MODE,IPRSET
INTEGER*2 ADIOSB(4) ,DAIOSB(4)
INTEGER*4 IBUFAD(50),IBUFDA(50) ,LAMSKB(2)
INTEGER*4 ISTAT,IERROR,IRATE,BUFNUM
REAL*4 PERIOD
COMMON

/SWEEP/AD,DA,IBUFAD,IBUFDA

EQUIVALENCE (IBUFAD(l) ,ADIOSB(l)) ,(IBUFDA(l) ,DAIOSB(l))

c
C
C

PARAMETER MULTI=l, HBIT='8000'X, LSTCHN=HBIT+7
SET UP RANDOM CHANNEL LIST.
15 SET.

NOTE THAT THE LAST WORD MUST HAVE BIT

DATA RCL/2,6,3,4,LSTCHN/

10-41

LABORATORY PERIPHERAL ACCELERATOR DRIVER

c
c

*******************************************************************

C
C

LOAD MULTIREQUEST MODE MICROCODE AND SET THE CLOCK OVERFLOW RATE
TO 5 KHZ

c
c

*******************************************************************

LOAD MICROCODE ON LPAll-K ASSIGNED TO LPA11$3

c
C
C

CALL LPA$LOADMC(MULTI,3,ISTAT,IERROR)
IF (.NOT. !STAT) GO TO 5000
COMPUTE CLOCK RATE AND PRESET.
ASSIGNED TO LPA11$3.

SET CLOCK 'A' ON LPAll-K

PERIOD = LPA$XRATE(.0002,IRATE,IPRSET,O)
IF (PERIOD .EQ. 0.0) GO TO 5500
CALL LPA$CLOCKA(IRATE,IPRSET,ISTAT,3)
IF (.NOT. ISTAT) GO TO 5000

*******************************************************************

SET UP FOR A/D SWEEP

c
c
c

*******************************************************************

C
C

INITIALIZE IBUF ARRAY. NOTE THE USE OF THE LAMSKB ARGUMENT BECAUSE
THE LPAll-K ASSIGNED TO LPA11$3 IS USED.

c
CALL LPA$SETIBF(IBUFAD,ISTAT,LAMSKB,AD(l,O) ,AD(l,l) ,AD(l,2) I
1
AD ( 1 , 3 ) , AD <1 , 4 ) , AD ( 1 , 5 ) , AD ( 1 , n) , AD <1 , 7 ) )
IF (.NOT. !STAT) GO TO 5000

c
C
C

c
c
c
C

CALL LPA$LAMSKS(LAMSKB,3)
SET UP RANDOM CHANNEL LIST SAMPLING
SEQUENCE)

(20 SAMPLES IN A SAMPLE

CALL LPA$SETADC(IBUFAD,,RCL,20,0,ISTAT)
IF (.NOT. !STAT) GO TO 5000
RELEASE BUFFERS FOR A/D SWEEP. NOTE THAT BUFFER 0 rs NOT
RELEASED BECAUSE BUFFER OVERRUN WILL BE SPECIFIED AS NON-FATAL.

c
CALL LPA$RLSBUF(IBUFAD,ISTAT,l,2,3,4,5,~,7)
IF (.NOT. !STAT) GO TO 5000

c
c

*******************************************************************

SET UP FOR D/A SWEEP

c
c
c

*******************************************************************

C
C

NOTE THAT THE SAME LAMSKB ARRAY CAN BE USED BECAUSE THE LAMSKB
CONTENTS APPLY TO BOTH A/D AND D/A SWEEPS

c
CALL LPA$SETIBF(IBUFDA,ISTAT,LAMSKB,DA(l,O) ,DA(l,l))
IF (.NOT. !STAT) GO TO 5000

c
C
C
C
C

SET UP SAMPLING PARAMETERS AS FOLLOWS:
INITIAL CHANNEL = 1.
NUMBER OF CHANNELS SAMPLED EACH SAMPLE SEQUENCE = 2, CHANNEL
INCREMENT = 2, THAT IS, SAMPLE CHANNELS 1 AND 3 EACH SAMPLE
SEQUENCE.

10-42

LABORATORY PERIPHERAL ACCELERATOR DRIVER

c
CALL LPA$SETADC(IBUFDA,,l,2,2,ISTAT)
IF (.NOT. !STAT) GO TO 5000

c
C

FILL BUFFERS WITH DATA FOR OUTPUT TO D/A

(Application dependent code is inserted here to fill buffers
DA(l,O) through DA(2000,0) and DA(l,l) through DA(2000,l) with data)

c
C

RELEASE BUFFERS FOR D/A SWEEP
CALL LPA$RLSBUF (IBUFDA,ISTAT,O,l)
IF (.NOT. !STAT) GO TO 5000

c
c

*****************************************************************

START BOTH SWEEPS

c
c
c

C
C
C
C

*****************************************************************
START A/D SWEEP. MODE BITS SPECIFY BUFFER OVERRUN IS NON-FATAL AND
MULTIREQUEST MODE. SWEEP ARGUMENTS SPECIFY 500 SAMPLES/BUFFER,
INDEFINITE SAMPLING, DWELL = 10 CLOCK OVERFLOWS, SYNCHRONIZE USING
EVENT FLAG 15, AND A DELAY OF 50 CLOCK OVERFLOWS.

c
C
C
C
C
C

MODE = 16384 + 64
CALL LPA$ADSWP(IBUFAD,500,0,MODE,10,%VAL(l5) ,50,,,ISTAT)
IF (.NOT. !STAT) GO TO 5000
START D/A SWEEP. MODE SPECIFIES MULTIREQUEST MODE. OTHER
ARGUMENTS SPECIFY 2000 SAMPLES/BUFFER, FILL 15 BUFFERS, DWELL = 25
CLOCK OVERFLOWS, SYNCHRONIZE BY CALLING THE COMPLETION ROUTINE
'FILLBF', AND DELAY = 10 CLOCK OVERFLOWS.
(SEE THE FILLBF LISTING
AFTER THE PROGRAM B LISTING.)
MODE = 64
CALL LPA$DASWP(IBUFDA,2000,15,MODE,25,FILLBF,10,,,ISTAT)
IF (.NOT. !STAT) GO TO 5000

c
c

*******************************************************************

C
C

WAIT FOR AN A/D BUFFER AND THEN PROCESS THE DATA IT CONTAINS. D/A
BUFFERS ARE FILLED ASYNCHRONOUSLY BY THE COMPLETION ROUTINE FILLBF.

c
c
c

C
C

c
100

c
C

*******************************************************************
WAIT FOR A BUFFER TO BE FILLED BY A/D.
IF BUFNUM IS LESS THAN
ZERO, THE SWEEP HAS STOPPED (EITHER SUCCESSFULLY OR WITH AN ERROR).
BUFNUM = LPA$IWTBUF(IBUFAD)
IF (BUFNUM .LT. 0) GO TO 1000
THERE IS A/D DATA IN AD(l,BUFNUM) THROUGH AD(500,BUFNUM)

10-43

LABORATORY PERIPHERAL ACCELERATOR DRIVER
(Process the A/D data with the application dependent code inserted
here)

c
C
C
C
C

ASSUME SWEEP SHOULD BE STOPPED WHEN THE LAST SAMPLE IN BUFFER
EQUALS O. NOTE THAT THE SWEEP ACTUALLY STOPS WHEN THE BUFFER
CURRENTLY BEING FILLED IS FULL. ALSO NOTE THAT LPASIWTBUF
CONTINUES TO BE CALLED UNTIL THERE ARE NO MORE BUFFERS TO PROCESS.
IF (AD(500,BUFNUM) .NE. 0) GO TO 200
CALL LPA$STPSWP(IBUFAD,l,ISTAT)
IF (.NOT. !STAT) GO TO 5000

c
C
C

AFTER THE DATA HAS BEEN PROCESSED, THE BUFFER IS RELEASED TO BE
FILLED AGAIN. THEN THE NEXT BUFFER IS OBTAINED FROM A/D.

c
200

c
c
c
c
c

CALL LPA$RLSBUF(IBUFAD,ISTAT,BUFNUM)
IF (.NOT. !STAT) GO TO 5000
GO TO 100
ENTER HERE WHEN A/D SWEEP HAS ENDED. CHECK FOR ERROR OR
SUCCESSFUL END. (NOTE: ASSUME THAT THE D/A SWEEP HAS ALREADY
ENDED - SEE COMPLETION ROUTINE FILLBF)

1000

c
c
c

c
c

IF (ADIOSB ( l)) GO TO 6000
CALL LIB$STOP(%VAL(ADIOSB(l)))

ENTER HERE IF THERE WAS AN ERROR RETURNED FROM ONE OF THE
LPAll-K HIGH LEVEL LANGUAGE CALLS. !STAT CONTAIN~ EITHER 0
OR A VAX/VMS STATUS CODE.

5000
5500

IF (!STAT .NE. 0) CALL LIBSSTOP (%VAL(ISTAT))
PRINT *,'ERROR IN LPAll-K SUBROUTINE CALL'
GO TO 7000

6000
7000

PRINT *,'SUCCESSFUL COMPLETION'
STOP
END

c
c

*******************************************************************

SUBROUTINE FILLBF

c
c
c

*******************************************************************

C THE FILLBF SUBROUTINE IS CALLED WHENEVER THE D/A HAS EMPTIED A
C BUFFER, AND THAT BUFFER IS AVAILABLE TO BE REFILLED. THIS
C SUBROUTINE GETS THE BUFFER, FILLS IT, AND RELEASES IT BACK TO THE
C LPAll-K. NOTE THAT THE D/A SWEEP IS STOPPED AUTOMATICALLY AFTER
C 15 BUFFERS HAVE BEEN FILLED. ALSO NOTE THAT FILLBF IS CALLED BY
C . AN AST HANDLER. IT IS THEREFORE CALLED ASYNCHRONOUSLY FROM THE
C MAIN PROGRAM AT AST LEVEL. CARE SHOULD BE EXERCISED WHEN ACCESSING
C VARIABLES THAT ARE COMMON TO BOTH LEVELS.

INTEGER*2 AD(500,0:7) ,DA(2000,0:l) ,DAIOSB(4)
INTEGER*4 IBUFAD(50) ,IBUFDA(50) ,BUFNUM,ISTAT
EQUIVALENCE
(IBUFDA(l),DAIOSB(l))
COMMON /SWEEP/AD,DA,IBUFAD,IBUFDA

10-44

LABORATORY PERIPHERAL ACCELERATOR DRIVER

c
C

GET BUFFER NUMBER OF NEXT BUFFER TO FILL
BUFNUM = LPA$IGTBUF(IBUFDA)
IF (BUFNUM .LT. 0) GO TO 3000

c
C

FILL BUFFER WITH DATA FOR OUTPUT TO D/A

(Application dependent code is inserted here to fill buffer
DA(l,BUFNUM) through DA(2000,BUFNUM) with data)

c
C

RELEASE BUFFER
CALL LPA$RLSBUF(IBUFDA,ISTAT,BUFNUM)
GO TO 4000

c
C

CHECK FOR SUCCESSFUL END OF SWEEP

c
3000

IF(DAIOSB(l)) GO TO 4000

c
C

ERROR IN SWEEP
CALL LIB$STOP(%VAL(DAIOSB(l)))

4000

RETURN
END

c *******************************************************************

10.9.3

LPAll-K QIO Functions Program (Program C)

This sample program uses QIO functions to start an A/D data transfer
from an LPAll-K.
(The program assumes multirequest mode microcode has
been loaded.) Sequential channel addressing is used.
The data
transfer is stopped after 100 buffers have been filled;
no action is
taken with the data as the buffers are filled. Note that this program
starts the data transfer and then waits until the QIO operation
completes.

*******************************************************************
PROGRAM C

*******************************************************************

IOSB:
COUNT:

.TITLE
.IDENT

LPAll-K EXAMPLE PROGRAM
/VOl/

.PSECT

LADATA,LONG

• BLKQ
• LONG

1
0

I/O STATUS BLOCK
COUNT OF BUFFERS FILLED

10-45

LABORATORY PERIPHERAL ACCELERATOR DRIVER

CBUFF:

USW:

.WORD

"'X20A

.WORD

.LONG
.LONG
.LONG
.LONG

4000
DATA BUFFERO
0

.LONG

.WORD
.BYTE
.BYTE
.WORD

10
0
l
16

.WORD
.BYTE
.BYTE
.WORD
.WORD
.WORD

l
0
0
0
0
0

COMMAND BUFFER FOR START
DATA QIO
MODE = SEQUENTIAL CHANNEL
ADDRESSING, A/D, MULTIREQUEST MODE
VALID BUFFER MASK (4
BUFFERS)
USER STATUS WORD ADDRESS
AGGREGATE BUFFER LENGTH
ADDRESS OF DATA BUFFERS
NO RANDOM CHANNEL LIST
LENGTH
NO RANDOM CHANNEL LIST
ADDRESS
DELAY
START CHANNEL
CHANNEL INCREMENT
NUMBER OF SAMPLES IN
SAMPLE SEQUENCE
DWELL
START WORD NUMBER
EVENT MARK WORD
START WORD MASK
EVENT MARK MASK
FILLS OUT COMMAND BUFFER

.WORD

USER STATUS WORD

.ALIGN

LONG

DATA BUFFERO:
DATA-BUFFER!:
DATA-BUFFER2:
DATA-BUFFER3:

usw

.BLKW
.BLKW
.BLKW
.BLKW

;BUFFERS MUST BE
LONGWORD ALIGNED
500
500
500
500

DEVNAME:

.LONG

4,LANAME

CHANNEL:

.BLKW

LANAME:

.ASCII

/LAAO/

.PSECT

LACODE,NOWRT

START:

DATA BUFFERS

CONTAINS CHANNEL NUMBER

.WORD
0
$ASSIGN S DEVNAME,CHANNEL
- R0,5$
BLBS
BRW
ERROR

ASSIGN CHANNEL
NO ERROR
ERROR

5$:
$QIOW_S ,CHANNEL,#IO$ SETCLOCK,IOSB,,,,#l,#"'Xl43,#-500
BLBC
RO,ERROR
MOVZWL IOSB,RO
BLBC
RO,ERROR
CLRW

SET CLOCK OVERFLOW RATE
TO 2 KHZ. (1 MHZ RATE
i DIVIDED BY 500 PRESET)

usw

MOVL
#100 ,COUNT
$QIOW_ s ,CHANNEL, #IO$ STARTDATA,-

10-46

ERROR
PICK UP I/O STATUS
ERROR
START DATA TRANSFER
CLEAR USW (START WITH
BUFFER 0)
FILL 100 BUFFERS

LABORATORY PERIPHERAL ACCELERATOR DRIVER

BLBC

IOSB,,,CBUFF,#40,#BFRAST
RO,ERROR

ERROR

NOTE THAT THE QIO WAITS UNTIL IT FINISHES. NORMALLY, THE DATA IS
PROCESSED HERE AS THE BUFFERS ARE FILLED. CHECK FOR ERROR WHEN
THE QIO COMPLETES.
MOVZWL
BLBC
RET

IOSB,RO
RO,ERROR

PICK UP I/O STATUS
ERROR
ALL DONE - EXIT

ERROR:
PUSHL
CALLS

ENTER HERE IF ERROR.
STATUS IN RO.
PUSH ONTO STACK
SIGNAL ERROR

RO
#1 ,LIB$STOP

BFRAST:

10$:

20$:

BUFFER AST ROUTINE.
BFRAST IS CALLED WHENEVER
A BUFFER IS FILLED.
.WORD
INCB
CMPZV

0
USW+l
#0,#3,USW+l,#3

ADD 1 TO BUFFER NUMBER
HANDLE WRAPAROUND

BLEQ
CLRB

10$
USW+l

USE BUFFER 0

DECL
BGTR
BISB

COUNT
20$
#"X40, USW+l

BICB
RET

rxso ,usw+1

.END

START

DECREMENT BUFFER COUNT
ENOUGH BUFFERS FILLED SET STOP BIT
CLEAR DONE BIT

*******************************************************************

10-47

CHAPTER 11
DR32 INTERFACE DRIVER

11.1

SUPPORTED DEVICE

The DR32 is an interface adapter that connects the internal memory bus
of a VAX-11 processor to a user-accessible bus called the DR32 Device
Interconnect (DOI). Two DR32s can be connected to form a VAX-11
processor-to-processor link.
Figure 11-1 shows the relationship of
the DR32 to the VAX 11/780 and the DOI.
As a general purpose data port, the DR32 is cap~ble of moving
continuous streams of data to or from memory at high speed. Data from
a user device to disk storage must go through an intermediate buffer
in main memory.

11.1.1

DR32 Device Interconnect

The DR32 Device Interconnect (DOI) is a bidirectional path for the
transfer of data and control signals. Control signals sent over the
DOI are asynchronous and interlocked; data transfeYs are synchronized
with clock signals. Any connection to the DOI is called a DR-device.
The DDI provides a point-to-point connection between two DR-devices,
one of which must be a VAX-11 processor. The DR-device connected to
the external end of the DDI is called the far end DR-device.

11-1

DR32 INTERFACE DRIVER
r------~;~~~~-----~

MEMORY

i---

VAX 11/780
PROCESSOR

1----

DR32

MASS BUS

MBA

DR-32 DEVICE
INTERCONNECT .....

(DOI)

(FAR END)
DR-DEVICE

i----

SBI

UNIBUS

UBA

I----

L-----------------~
Figure 11-1

11.2

Basic DR32 Configuration

DR32 FEATURES AND CAPABILITIES

The DR32 provides the following features and capabilities:
•

32-bit parallel data transfers

•

High bandwidth (6 megabytes/second

the

DD!

with

VAX

11/780)

•

Word or byte alignment of data

•

Half-duplex operation

•

Hardware-supported (I/O driver-independent) memory mapping

•

Separate Control and Data Interconnects

•

Command and data chaining

•

Direct software link hetween the DR32 and the user process

•

Synchronization of the user program with DR32 data transfers

•

Transfers initiated by an external device

The following sections describe the capabilities.

11-2

DR32 INTERFACE DRIVER
11.2.l

Command and Data Chaining

Command chaining is the execution of commands without software
intervention for each command. Commands are chained in the sense that
they follow each other on a queue. After a QIO function starts the
DR32, any number of DR32 commands can be executed during that QIO
operation. This process continues until the transfer is halted
(a
command packet is fetched that specifies a halt command) or an error
occurs.
Command packets can specify data chaining. In data chaining, a number
of main memory buffers appear as one large buffer to the far end
DR-device. Data chaining is completely transparent to this device;
transfers are seen as a continuous stream of data. Chained buffers
can be of arbitrary byte alignment and length.
The length of a
transfer appears to the far end DR-device to be the total of all the
byte counts in the chain, and since chains in the DR32 can be of
unlimited length, the device sees the byte count as potentially
infinite.

11.2.2

Far End DR-device Initiated Transfers

The DR32 provides the capability for the far end DR-device to initiate
data transfers to the VAX-11 memory, that is, it provides for random
access mode. Random access consists of data transfers to or from the
VAX-11 memory without notification of the VAX-11 processor. This mode
is used when two DR32s are connected to form a processor-to-processor
link.
You can discontinue random access by specifying a command
packet with random access disabled. It can also be discontinued by an
abort from either the controlling process or the far end DR-device.

11.2.3

Power Failure

If power fails on the DR32 but not on the system, the DR32 driver
aborts
the
active data transfer and returns the status code
SS$ POWERFAIL in the I/O status block.
If a system power-failure
occurs, the DR32 driver completes the active data transfer when power
is recovered and returns the status code SS$ POWERFAIL.

11.2.4

Interrupts

The DR32 can interrupt the
reasons:

DR32

driver

for

any

the

following

•

An abort has occurred.

The QIO is completed.

•

A DR32 power-down or power-up sequence has occurred

•

An unsolicited control message has been sent to the DR32.
If
this command packet's interrupt control field is properly set
up, a packet AST interrupt occurs. The interrupt occurs after
the command packet obtained from FREEQ is placed on TERMQ.

•

The DR32 enters the halt state.

11-3

The QIO is completed.

DR32 INTERFACE DRIVER

11.3

•

A command packet that specifies an unconditional interrupt has
been placed onto TERMQ. The result is a packet AST.

•

A command packet with the "interrupt when TERMQ empty" bit set
was placed on an empty TERMQ. The result is a packet AST.

DEVICE INFORMATION

Users. can obtain information on the DR32 by using the $GETCHN and
$GETDEV
system services (see Section 1.10).
The DR32-specific
three
longwords
of
a
information is returned in the first
user-specified buffer, as shown in Figure 11-2 (Figure 1-9 shows the
entire buffer).

16 15

device characteristics

type

data rate

Figure 11-2

class

DR32 Information

The first longword contains device-independent information.
second and third longwords contain device-dependent data.

The

Table 11-1 lists the device-independent
the first longword.

characteristics

Table 11-1
Device-Independent Characteristics
Dynamic Bitl
(Conditionally Set)
DEV$M AVL

Meaning

Device is available

Static Bitsl
(Always Set)
DEV$M IDV

Input device

DEV$M ODV

Output device

DEV$M RTM

Real time device

1. Defined by the $DEVDEF macro.

11-4

returned

DR32 INTERFACE DRIVER
The second longword contains information on the device class and type.
The device class for the DR32 is DC$ REALTIME and the device type for
the DR780 is DT$ DR780. The $XFDEF macro defines these values.
The low order byte of the third longword contains the last
value loaded into the DR32 data rate register.

11.4

data

rate

PROGRAMMING INTERFACE

The DR32 is supported by a device driver, a high-level language
procedure library of support routines, and a program for microcode
loading.
After issuing a IO$ STARTDATA QIO to the DR32 driver, application
programs communicate directly with the DR32 by inserting command
packets onto queues. This direct link between the application program
and the DR32 provides faster.communication by avoiding the necessity
of going through the I/O driver.
Two interfaces are provided for accessing the DR32: a QIO interface
and a support routine interface. The QIO interface requires that the
application program build command packets and insert them onto the
DR32 queues.
The support routine interface, on the other hand,
provides procedures for these functions and, in addition, performs
housekeeping functions, such as maintaining command memory.
The support routine interface was designed to be called
from
high-level languages, such as FORTRAN, where the data manipulation
required by the QIO interface might be awkward. Note, however, that
the user of the support routines must be equally as sophisticated as
the user of the QIO interface in terms of knowledge of the DR32 and
the meaning of the fields in the command packets.

11.4.1

DR32 - Application Program Interface

The application program interfaces with ihe DR32 through two memory
areas. These areas are called the command block and the buffer block.
The addresses and sizes of the blocks are determined by
the
application program and passed to the DR32 driver as arguments to the
IO$ STARTDATA function.
This QIO function starts the DR32 (see
Section 11.4.5.2). Both blocks are locked into memory while the DR32
is active. The buffer block defines the area of memory that is
accessible to the DR32 for the transfer of data between the far end
DR-device and the DR32. The command block contains the headers for
the three queues that provide the communication path between the DR32
and the application program, and space in which to build command
packets.
The interface between the DR32 and the application program contains
three queues: the input queue (INPTQ), the termination queue (TERMQ),
and the free queue (FREEQ). Information is transferred between the
DR32 and the far end DR-device through the use of command packets.
The three queue structures control the flow of command packets to and
from the DR32.
The application program builds a command packet and
inserts it onto INPTQ. The DR32 removes the packet, executes the
specified command, enters some status information, and then inserts
the packet onto TERMQ. Unsolicited input from the far end DR-device
is placed in packets removed from FREEQ and inserted onto TERMQ.

11-5

DR32 INTERFACE DRIVER
The INPTQ, TERMQ, and FREEQ headers are located in the first six
longwords of the command block.
Since the queues are self-relative,
that is, they use the VAX-11
self-relative queue instructions,
the
headers must be quadword aligned.
The application program must
initialize all queue headers.
Figure 11-3 shows the position of the
queue headers
in the command block.
Section 11.4.2 describes queue
processing in greater detail.

input queue forward link (INPTQ head)

input queue backward link (INPTQ tail)

termination queue forward link (TERMQ head)

termination queue backward link (TERMQ tail)

free queue forward link (FREEQ head)

free queue backward link (FREEQ tail)

-~·

command packet space

Figure 11-3

11.4.2

Command Block (Queue Headers)

Queue Processing

Three queue structures control the flow of command packets to and from
the DR32:
•

Input queue (INPTQ)

•

Termination queue (TERMQ)

•

Free queue (FREEQ)

The DR32 removes command packets from the heads of FREEQ and INPTQ and
inserts command packets onto the tail of TERMQ.
For command sequences
initiated by the application program, the DR32 removes command packets
from the head of INPTQ, processes them, and returns them to the tail
of TERMQ.
Queue processing
is performed by the DR32 with the
equivalent of the INSQTI and REMQHI instructions.
To remove a packet
from INPTQ, the DR32 executes the equivalent of REMQHI HDR, CMDPTR
where CMDPTR is a DR32
register used as a pointer to the current
command packet and HDR specifies the INPTQ header.
To insert a packet
onto TERMQ,
the DR32 executes the equivalent of INSQTI CMDPTR, HDR.
The user process performs similar operations with the
queues,
inserting packets onto the head or tail of INPTQ and normally removing
packets from the head of TERMQ.

11-6

DR32 INTERFACE DRIVER
If any of the queues are currently being accessed
program's interlocked queue instructions will
following reasons:

by the DR32, the
fail for one of the

The DR32 is currently removing a packet from INPTQ or FREEQ,
or inserting a packet onto TERMQ, and the operation will be
completed shortly.

The DR32 detects an error condition, for example,
an
unaligned queue, that prevents it from completing the queue
operation. In this case, the transfer is aborted and the I/O
status block contains the error that caused the abort.

To distinguish between these two conditions, the application program
must include a queue retry mechanism that retries the queue operation
a reasonable number of times, for example 25, before determining that
an error condition exists. An example of a queue retry mechanism is
shown in the program example (see Section 11.7).
If the DR32 discerns that any of the queues are interlocked,
retries the operation until it completes or the DR32 is aborted.

11.4.2.l Initiating Command Sequences - If a command packet
is
inserted onto an empty INPTQ, the application program must notify the
DR32 of this event. This is accomplished by setting bit O in a DR32
register, the GO bit.
The IO$ STARTDATA QIO returns the GO bit's
address to the application program. After notification by the GO bit
that there are command packets on its INPTQ, the DR32 continues to
process the packets until INPTQ is empty.
The GO bit can be safely set at any time.
While processing command
packets, the DR32 ignores the GO bit. If the GO bit is set when the
DR32 is idle, the DR32 will attempt to remove a command packet from
INPTQ. If INPTQ is empty at this time, the DR32 clears the GO bit and
returns to the idle state.

11.4.2.2 Device-Initiated Command Sequences - If the DR-device that
interfaces the far end of the DDI is capable of transmitting
unsolicited control messages, messages of this type can be transmitted
to the local DR32.
These messages are not synchronized to the
application program command flow. Therefore, the DR32 uses a third
queue,
FREEQ,
to
handle unsolicited messages.
Normally, the
application program inserts a number of empty command packets onto
FREEQ to allow the external device to transmit control messages.
If a control message is received from the far end DR-device, the DR32
removes an empty command packet from the head of FREEQ, fills the
device message field of this packet with the control message and, when
the transmission is completed, inserts the packet onto the tail of
TERMQ.
(The device message field in this command packet must be large
enough for the entire message or a length error will occur.) The
application program then removes the packet from TERMQ.
If the
command packet is from FREEQ, the XF$M PKT FREQPK bit in the DR32
Status Longword is set.
Figure 11-4 shows the DR32 queue flow.

11-7

DR32 INTERFACE DRIVER

unsolicited control messages

INSQTI CMDPTR,HDR

DR32

,----,
1

REMQHI HDR,CMDPTR

HEAD

TAIL

I
I
I

INPUT
QUEUE
(INPTQ)

FREE
QUEUE
(FREEQ)

I
TERMINATION
QUEUE
(TERMQ)

I
I
TAIL

HEAD

l_J

I
I

Figure 11-4

11.4.3

CONTROLLING
PROCESS

DR32 Command Packet Queue Flow

Command Packets

To provide for direct communication between the controlling process
and the DR32, the DR32 fetches commands from user-constructed command
packets located in main memory.
Command packets contain commands for
the DR32,
such as the direction of transfer, and/or messages to be
sent to the far end DR-device. The DR32 is simply the conveyer of
these messages;
it does not examine or add to their content. The
controlling process builds command packets and manipulates the three
queues,
using the four VAX-11
self-relative queue instructions.
Figure 11-5 shows the contents of a DR32 command packet.

11-8

DR32 INTERFACE DRIVER
31

interrupt
control

29 28

I I
len
err

27 26

contml
select

24 23

20 19

l I
00

w 0000

16 15

self-relative forward link

self-relative backward link

device control code ..

length of log area

--------length of device message

byte count

-----virtual address of buffer

residual memory byte count

residual DDI byte count

-28

DR32 status longword

32
DR-device messa g e

{ , _ _ _ _ _ _ - ' - - - - - - - - l o g a r e a_ _ _
*Bits 31:24 =Packet Control Byte
**Bits 23: 16 =Command Control Byte

Figure 11-5

DR32 Command Packet

11.4.3.1 Length of Device Message Field - This field describes the
length of the DR-device message in byte&. The message length must be
less than 256 bytes. Note, however, that the length of device message
field itself must always be an integral number of quadwords long. For
example, if the application program requires a 5-byte device message,
it must write a 5 in the length of device message field, but allocate
8 bytes for the device message field itself. In this case, the last
three bytes of the field are ignored by the DR32 when transmitting a
message, or written as zeros when receiving a message:

DR32 status longword (DSL)

(ignored or all O's)

log area

11-9

:XF$8_PKT_DEVMSG

DR32 INTERFACE DRIVER
The symbolic offset
XF$B PKT MSGLEN.

for

the

length

device

message

field

11.4.3.2 Length of Log Area Field - This field describes the length
of the log area in bytes. The length specified must be less than 250
bytes. Note, however, that the length of log area field
itself must
be an integral number of quadwords long.
For example,
if the
application program requires a 5-byte log area field, it must write a
5 in the length of log area field, but allocate 8 bytes for the log
area field itself.
In this case, the last three bytes of the field
are written as zeros when receiving a log message (log messages are
always received). The symbolic offset for
the length of log area
field is XF$B PKT LOGLEN.

11.4.3.3 Device Control Code Field - The device
control
field
describes the function performed by the DR32. The field occupies the
lower half of the command control byte (bits lo through 23).
VAX/VMS
defines the following values:
Symbol
XF$K PKT RD
XF$K-PKT-RDCHN
XF$K-PKT-WRT
XF$K-PKT-WRTCHN
XF$K-PKT-WRTCM
XF$K PKT SETTST
XF$K-PKT-CLRTST
XF$K-PKT-NOP
XF$K-PKT-DIAGRI
XF$K-PKT-DIAGWI
XF$K-PKT-DIAGRD
XF$K-PKT-DIAGWC
XF$K-PKT-SETRND
XFSK-PKT-CLRRND
XF$K-PKT-HALT

Value

Function

Read device
Read device chained
Write device
Write device chained
Write device control message
(reserved)
Set self-test
Clear self-test
No-op
Diagnostic read internal
Diagnostic write internal
Diagnostic read DDI
Diagnostic write control message
Set random enable
Clear random enable
Set HALT

1
2

3
4
5
6
7

8
9

11
12
13
14
15

Table 11-2 describes the functions performed by the
control codes.

11-10

different

device

DR32 INTERFACE DRIVER
Table 11 .... 2
Device Control Code Descriptions
Function

Meaning

! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - " " " ________
Read Device

This function specifies a data transfer from
the far end DR-device to the DR32. The
control select field (see Section 11.4.3.4)
describes the information to be transferred
prior to the initiation
of
the
data
transfer.

Read Device
Chained

This function specifies a data transfer from
the far end DR-device to the DR32. The DR32
data chains to the buffer specified in the
next command packet in INPTQ.
A command
packet that specifies read device chained
must be followed by a command packet that
specifies either read device chained or read
device.
All other device control codes
cause an abort. If read device chained is
specified, the chain continues. However, if
read
device is specified, that command
packet is the last packet in the chain.

Write Device and
Write Device
Chained

These functions specify data transfers from
the DR32 to the far end DR-device. Otherwise, they are similar to Read Device and
Read Device Chained.

Write Device
Control Message

This function specifies the transfer of a
control message to the far end DR-device.
This message is contained in the device
message field of this command packet.
The
Write
Device
Control
Message function
directs the controlling DR32 to ignore the
byte count and virtual address fields in
this command packet.

Set Self-Test

This function directs the DR32 to set an
internal self test flag and to set a disable
signal on the DDI. This signal informs the
far end DR-device that the DR32 is in
self-test mode. In this condition the DR32
can no longer communicate with the far end
DR-device.

Clear Self-Test

This function directs the DR32 to clear the
internal self test flag set by the Set Self
Test function and return to the normal mode
of operation.

Op~ration

The NOP function specifically does nothing.

(continued on next page)

11-11

DR32 INTERFACE DRIVER
Table 11-2 (Cont.)
Device Control Code Descriptions
Function

Meaning

Diagnostic Read
Internal

This function directs the DR32 to fill the
memory buffer, which is described by the
virtual address and byte count specified in
the current command packet, with the data
that is stored in the DR32 data silo. The
buffer is filled in a cyclic manner.
For
example, on the DR780 every 128-byte section
of the buffer receives the silo data.
The
amount of data stored in the buffer equals
the DDI byte count minus the SBI byte count.
The DDI byte count is equal to the original
byte count.
No data transmission takes place on the
for this function.

DDI

On the DR780, the Diagnostic Read Internal
function destroys the first four bytes in
the silo before storing the data in the
buffer.
Diagnostic Write
Internal

This function, together with the Diagnostic
Read Internal function, is used to test the
DR32
read
and
write capability.
The
Diagnostic Write Internal function directs
the DR32 to store data, which is contained
in the memory buffer described by
the
current command packet, in the DR32 data
silo,
a
fifo-type
buffer.
No
data
transmission takes place on the DDI for this
function.
The Diagnostic Write Internal
function
terminates when either of the
following conditions occur:
•

The memory buffer is empty (the SBI
byte count is 0).

•

An abort has occurred.

At the time the function terminates, the
amount of data in the silo equals the DDI
byte count minus the SBI memory byte count
(Sections 11.4.3.9 and 11.4.3.·10 describe
these values).
Diagnostic Read
DDI

This function tests transmissions over the
data portion of the DDI. The DR32 must be
in the self-test mode.
If not, an abort
will occur. On the DR780, the Diagnostic
Read DDI function transmits the contents of
DR32 data silo locations O - 127 over the
DDI
and returns the data to the same
locations. If data transmission is normal,
that is, without errors, the residual memory
count is equal to the original byte count,
the
residual DDI count is O, and the
contents of the silo remain unchanged.
(continued on next page)
11-12

DR32 INTERFACE DRIVER

Table 11-2 (Cont.)
Device Control Code Descriptions
Function

Meaning

Diagnostic Write
Control Message

This function tests transmissions over the
control portion of the DDI. The DR32 must
be in self-test mode. If not, an abort will
occur. The Diagnostic Write Control Message
function directs the DR32 to remove the
command packet on FREEQ and check the length
of message field.
Then the first byte of
the message in the command packet on INPTQ
is transmitted and read back on the control
portion of the DDI.
This byte is then
written into the message space of the packet
from FREEQ. The updated packet from FREEQ
is inserted onto TERMQ and is followed by
the packet from INPTQ.

Set Random Enable
and Clear Random
Enable

The Set Random Enable function directs the
DR32 to accept read and write commands sent
by the far end DR-device. Range checking is
performed
to verify that all addresses
specified by the far end DR-device for
access are within the buffer block. Far end
DR-device initiated transfers to or from the
VAX-11
memory
are
conducted
without
notification of the VAX-11 processor or the
application program.
The Clear Random Enable function directs the
DR32 to reject far end DR~device initiated
transfers.
Random access mode must be enabled when the
DR32 is used in a processor-to-processor
link.

Set HALT

This function places the DR32 in a halt
state.
The
Set
Halt function always
generates a packet interrupt regardless of
the value in the interrupt control field
(see Section 11.4.3.n). If an AST routine
was requested on completion of the QIO
function
(see
Sections
11.4.5.2
and
11.4.n.2), the routine is called after the
command packet containing the Set
HALT
function has been processed by the DR32.

The following symbolic offsets are defined for the device control code
field:
Symbol

XF$B PKT CMDCTL

XF$V PKT FUNC
XF$S-PKT-FUNC

Meaning

Byte offset from the beginning of the command
packet
Bit offset from XF$B PKT CMDCTL
Size of this bit field

11-13

DR32 INTERFACE DRIVER
11.4.3.4 Control Select Field - This field describes what part of the
command packet will be transmitted to the far end DR-device. The
control select field is examined only for the read device, read device
chained, write device, and write device chained functions;
for all
others, it is ignored. VAX/VMS defines the following values:
Symbol

Value

Function

XF$K PKT NOTRAN

No transmission. Nothing is transmitted over
the control portion of the DDI. However, if
the command packet specifies a data transfer,
data can be transmitted over the data portion
of the DOI. The primary use of this code is
during data chaining.

XF$K PKT CB

Command control byte (bits 23:1'1) only. This
code
directs
the DR32 to transmit the
contents of the command control byte, which
includes the device control code field, to
the far end DR-device.
This code is used
primarily at the start of data chains or
nondata chain commands.

XF$K PKT CBDM

Command control byte and device message.
This code directs the DR32 to transmit the
command control byte, and then the device
message.
The primary use of this code is
when an interface requires more than one byte
of command.

XF$K PKT CBDMBC

Command control byte, device message, and
byte count.
This code directs the DR32 to
transmit the command control byte, the device
message, and the byte count (in that order).
The primary use of this code is during
processor-to-processor link operations. In
this case the device message must be exactly
four bytes in length and contain the virtual
address of the buffer in the
far
end
processor's memory.

The following symbolic offsets are
field:

defined

for

the

control

select

Symbol

Meaning

XF$B PKT PKTCTL

Byte offset from the beginning of the command
packet
Bit offset from XF$B PKT PKTCTL
Size of this bit fieid

XF$V PKT CISEL
XF$S-PKT-CISEL

11.4.3.5 Suppress Length Error Field - This function prevents the
DR32 from aborting if the data transfer on the DDI is terminated by
the far end DR-device before the DDI byte counter has reached zero.

11-14

DR32 INTERFACE DRIVER

The following symbolic offsets are defined
error field:

for

the

suppress

length

Symbol

Meaning

XF$B PKT PKTCTL

Byte offset from the beginning of the command
packet
Bit offset from XF$B PKT PKTCTL
Size of this bit field

XF$V PKT SLNERR
XF$S-PKT-SLNERR

11.4.3.6 Interrupt Control
Field - This
field
determines
the
conditions under which an interrupt is generated, on a packet by
packet basis, when the DR32 places this command packet onto TERMQ.
Depending on the conditions specified in the IO$ STARTDATA call, the
interrupt can set an event flag and/or call an AST-routine.
Function

Symbol

Value

XF$K PKT UNCOND

Interrupt unconditionally

XF$K PKT_TMQMT

Interrupt only if TERMQ was previously
empty

XF$K PKT NOINT

2,3

No interrupt

If the function is Set Halt, this field is ignored.
The Set Halt
function unconditionally causes a packet interrupt. The following
symbolic offsets are defined for the interrupt control field:
Symbol

Meaning

XF$B PKT PKTCTL

Byte offset from the beginning of the command
packet
Bit offset from XF$B PKT PKTCTL
Size of this bit fieid

XF$V PKT INTCTL
XF$ S-PKT-INTCTL

11.4.3.7 Byte Count Field - This field specifies the size in bytes of
the data buffer for this data transfer. Together with the virtual
address of buffer field, this field describes the buffer in the buffer
block that the DR32 will read from or write into.
The following symbolic offset is defined for the byte count field:
Symbol

Meaning

XF$B PKT BFRSIZ

Byte offset from the beginning of the command
packet

11.4.3.8 Virtual Address of Buffer Field - This field specifies the
virtual address of the data buffer for this data transfer. Together
with the byte count field, this field describes the buffer in the
buffer block that the DR32 will read from or write into.

11-15

DR32 INTERFACE DRIVER
The following symbolic offset is defined for the
buffer field:

virtual

address

Symbol

Meaning

XF$B PKT BFRADR

Byte offset from the beginning of the command
packet

11.4.3.9 Residual Memory Byte Count Field - After completion of a
read device, read device chained, write device, write device chained,
diagnostic read internal, diagnostic write internal, or diagnostic
read DDI command specified in this command packet, the DR32 places the
packet onto TERMQ for return to the controlling process.
At that
time, this field will contain a byte count. The difference between
the count specified in the byte count field and the count in this
field represents the number of bytes transferred to or from main
memory, depending on the direction of transfer.
The following symbolic offset is defined for the residual memory
count field:

byte

Symbol

Meaning

XF$L PKT RMBCNT

Byte offset from the beginning of the command
packet

(See also the descriptions of the Diagnostic Read
Diagnostic Write Internal functions in Table 11-2.)

Internal

and

11.4.3.10 Residual DDI Byte Count Field - After completion of a read
device, read device chained, write device, write device chained,
diagnostic read internal, diagnostic write internal, or diagnostic
read DDI command specified in this command packet, the DR32 places the
packet onto TERMQ for return to the controlling process.
At that
time, this field contains a byte count. The difference between the
count specified in the byte count field and the count in this field
represents the number of bytes transferred to or from the far end
DR-device over the DDI, depending on the direction of transfer.
The following symbolic offset is defined for
count field:

the

residual

DD!

byte

Symbol

Meaning

XF$L PKT RDBCNT

Byte offset from the beginning of the command
packet

(See also the descriptions of the Diagnostic Read
Diagnostic Write Internal functions in Table 11-2.)

11-10

Internal

and

DR32 INTERFACE DRIVER
(DSL} - The DR32
stores the final
11.4.3.11 DR32 Status Longword
status for a command packet in the DR32 status longword before
inserting the packet onto TERMQ. The longword contains two distinct
status fields:
24 23

16 15

0
16 bits of status

DOI status

Table 11-3 lists the names for the status bits returned
status longword.

the

DR32

Table 11-3
DR32 Status Longword (DSL) Status Bits
Name

Meaning
lo bits of status

XF$V PKT SUCCESS
XF$M-PKT-SUCCESS

If set,
the command was performed
cessfully.
If not set,
one
of
following bits must be set:

sucthe

XF$M PKT INVPTE
XF$M-PKT-RNGERR
XF$M-PKT-UNGERR
XF$ M-PKT-INVPKT
XF$M-PKT-FREQMT
XF$ M-PKT-DD ID IS
XF$M-PKT-INVDDI
XF$M-PKT-LENERR
XF$M-PKT-DRVABT
XF$M-PKT-PARERR
XF$M-PKT-DDIERR
XF$V PKT CMDSTD
XF$M-PKT-CMDSTD

If set,
the command
packet was started.

XF$V PKT INVPTE
XF$M-PKT-INVPTE

this

If set, the DR32 accessed an
table entry.

invalid

page

XF$V PKT FREQPK
XF$M-PKT=FREQPK

If set, this
from FREEQ.

was

XF$V PKT DDIDIS
XF$M-PKT-DDIDIS.

If set, the far end DR-device is disabled.

XF$V PKT SLFTST
XF$M-PKT-SLFTST.

If set, the DR32 is in self-test mode.

XF$V PKT RNGERR
XF$M-PKT-RNGERR

Range error.
If set,
a user-provided.
address was outside the command block or
buff er block •

packet

removed

__________ _______

.__

command

specified

__._

··--··--------~-~-----__....

11-17

(continued on next page)

DR32 INTERFACE DRIVER

Table 11-3 (Cont.)
DR32 Status Longword (DSL) Status Bits
Name

Meaning

---------------------+----------------------------~

XF$V PKT UNQERR
XF$M~)KT=UNQERR

If set, a queue element was not
a quadword boundary.

aligned on

XF$V PKT INVPKT
XF$M PKT-INVPKT

If set, this packet was
command packet.

valid

X1',$V PKT FREQMT
XF$M-PKT=FREQMT

If set, a message was received from the far
end DR-device and FREEQ was empty.

XF$V PKT RNDENB
XF$M-PKT-RNDENB

If set, random access mode is enabled.

XF$V PKT INVDDI
XF$M-PKT-INVDDI

If set, a protocol
DDI.

XF$V PKT LENERR
XF$M PKT-LENERR

If set, the far end DR-device
terminated
the data transfer before the
required
number of bytes were sent, or a message was
received from the far end DR-device and the
device message field in the command packet
at the head of FREEQ was not large enough
to hold it.

XF$V PKT DRVABT
XF$M-PKT-DRVABT

The I/O driver aborted
the
transfer.
Usually the result of
a
Cancel
I/O
($CANCEL) system service request.

XF$V PKT PARERR
XF$M-PKT-PARERR

A parity error occurred on
control portion of the DDI.

error

not a

occurred

the

DR32

on the

data

t--------·. - - - - - - - · - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DOI Status
XF$V PKT DDISTS
XF$S-PKT-DDISTS

DDI status. This field is the 1-byte DDI
register 0 of the far end DR-device.
The
following three bits are offsets to this
field.

XF$V PKT NEXREG
XF$M-PKT-NEXREG

An attempt was made to access a nonexistent register in the far end DR-device.

XF$V PKT LOG
XF$M-PKT-LOG

The far end DR-device registers are
in the log area.

XF$V PKT DDIERR
XF$M-PKT-DDIERR

An error occurred on the far end DR-device.

__________ __ ______
..

stored

..,,. ---------'---------~--~------------~---------~

11.4.3.12 Device Message
Field - This
field
contains
control
information to be sent to the far end DR-device. It is used when more
than one byte of command is required. The number of bytes in the
device message is specified in the length of device message field (see
Section 11.4.3.1).
(The number of bytes allocated for the length of
device message field must be rounded up to an integral number of
quadwords.)

11-18

DR32 INTERFACE DRIVER
If the far end DR-device is a DR32 that is connected to another
processor, a device message can be sent only if the function specified
in the device control code field of this command packet is read
device, read device chained, write device, write device chained, or
write device control message.
In the case of a write device control message, the data in the device
message field is treated as unsolicited input and written into the
device message field of a command packet taken from the far end DR32's
FREEQ.
In the case of a read or write (either chained or unchained) function,
the only message allowed is the address of the buffer in the far end
processor that either contains or will receive the data to be
transferred.
This device message must be exactly four bytes in
length.
In this case the device message is not stored in the command
packet from the far end DR32's FREEQ, but is used by the far end DR32
to perform the data transfer.
The device message field is also used in command
FREEQ to convey unsolicited control messages
DR-device.

packets placed on
from the far end

The symbolic offset for the device message field is XF$B PKT DEVMSG.

11.4.3.13 Log Area Field - This field receives the return status and
other information from the far end DR-device's DDI registers. Logging
must be initiated by the far end DR-device. The presence of a log
area does not automatically cause logging to occur.
If the DR32 is connected in a processor-to-processor
the log area field is not used.

11.4.4

configuration,

DR32 Microcode Loader

The DR32 microcode loader program XFLOADER must be executed prior to
using
the
DR32.
Running XFLOADER requires CMKRNL and LOG IO
privileges. Typically, a command to run XFLOADER is placed in the
site-specific
system starting file.
XFLOADER locates the file
containing the DR32 microcode in the following manner:
1.

XFLOADER attempts to open a file using the logical name
XFc$WCS, where "c" is the DR32 controller designator. For
example, to load microcode on device XFAO, XFLOADER attempts
to open a file with the logical name XFA$WCS.

If the opening procedure described in Step 1 fails, XFLOADER
attempts to open the file SYS$SYSTEM:XF780.ULD which is the
default location and filename for the DR780 microcode.

11-19

DR32 INTERFACE DRIVER

After loading microcode into all available DR32s,
exits or hibernates, according to the following:

XFLOADER

either

•

If XFLOADER was run with an ordinary RUN command, that is, RUN
XFLOADER, it exits after loading microcode.

•

If XFLOADER was run as a separate process, as with the command
RUN/UIC=[l,l]/PROCESS=XFLOADER SYS$SYSTEM:XFLOADER
then it hibernates after loading microcode.
In this case,
XFLOADER automatically reloads microcode into the DR32s after
a power recovery.

XFLOADER performs a load microcode QIO to the DR32 driver.

11.4.5

DR32 I/O Function Codes

The DR32 I/O functions are:
•

Load microcode into the DR32.

•

Start a DR32 data transfer.

Normally, the controlling process stops data transfers with a Set HALT
command packet.
However, the Cancel I/O on Channel ($CANCEL) system
service can be used to abort data transfers and complete the I/O
operation.

11.4.5.l Load Microcode - This I/O function resets the DR32 and loads
an image of DR32 microcode. The load microcode function also sets the
DR32 data rate to the last specified value. Physical I/O privilege is
required. VAX/VMS defines a single function code:
IO$ LOADMCODE - load microcode
The load microcode
arguments:

function

takes

two

device/function-dependent

•

Pl = ·the starting virtual address of the microcode image
is to be loaded into the DR32

that

•

P2 = the number of bytes to be loaded (maximum of 5120 for the
DR780)

If any data transfer requests are active at the time a load microcode
request is issued, the load request is rejected and ssS_DEVACTIVE is
returned in the I/O status block.
The microcode is verified by addressing each microword and checking
for a parity error.
(The microcode is not compared to the buffer
image.) If there are no parity errors, then the microcode was loaded
successfully and the driver sets the microcode valid bit in one of the
DR32 registers. If there is a parity error, SS$ PARITY is ·returned in
the I/O status block.
(The valid bit is cleared by the reset
operation.)
In addition to SSS PARITY, three other status codes can be returned in
the I/O status block: ssS_NORMAL, SS$_DEVACTIVE, and SSS POWERFAIL.

11-20

DR32 INTERFACE DRIVER
11.4.5.2 Start Data Transfer - This function specifies a command
table that holds the parameters required to start the DR32. In
addition to several other parameters, the command table contains the
size and address of the command and buffer blocks, and the address of
a command packet AST routine. No user privilege is required. VAX/VMS
defines a single function code:
IO$ STARTDATA - start data transfer
The start data transfer function takes one function modifier:
IO$M_SETEVF - set event flag
If IO$M SETEVF is included with the function code, the specified event
flag is set whenever a command packet interrupt occurs, and when the
start data transfer QIO is completed.
If IO$M SETEVF is
not
specified, the event flag is set only when the QIO is-completed.
IO$M SETEVF should not be used with the $QIOW macro because the
will-return after the event flag is set the first time.
The start data transfer function takes
arguments:

two

$QIOW

device/function-dependent

•

Pl = the starting virtual address of the Data Transfer Command
Table in the user's process

•

P2 = the length in bytes (always 32) of the Data Transfer
Command Table.
(The symbolic name is XF$K CMT LENGTH.)

The format of the Data Transfer Command Table is shown in Figure
(offsets are shown in parentheses).

11-~

command block size (XF$L_CMT _CBLKSZ)
4

command block address (XF$L_CMT _CBLKAD)

8
buffer block size (XF$L_CMT _BBLKSIZ)

12
buffer block address (XF$L_CMT _BBLKAD)

16
command packet AST routine address (XF$L_CMT_PASTAD)

20
command packet AST parameter (XF$L_CMT _PASTPM)
24

flags
(XF$B_CMT _FLAGS)

data rate
(XF$B_CMT _RATE)
28

address of the location to store the GO bit address
(XF$L_CMT _GBITAD)

Figure 11-6

Data Transfer Command Table

11-21

DR32 INTERFACE DRIVER
Since the command block contains the queue headers for INPTQ, TERMQ,
and FREEQ, its address in the second longword must be quadword
aligned.
The command packet AST routine specified in the fifth longword is
called whenever the DR32 signals a command packet interrupt. A
command packet AST should be distinguished from a QIO AST (astadrs
argument).
A command packet interrupt occurs whenever the DR32
completes a function and returns a packet that specifies an interrupt
(see Section 11.4.3.6) by inserting it onto TERMQ. The astadrs
argument address is called when the QIO is completed. If either the
command packet AST address or the astadrs address is O, the respective
AST is not delivered. If the command packet specifies the Set HALT
function, a command packet interrupt occurs regardless of the state of
the packet interrupt bits.
The seventh longword contains the data rate byte and a flags byte.
The data rate byte controls the DR32 clock rate. The data rate value
is considered to be an unsigned integer.
For the DR780, the relationship between the value of the data
byte and the actual data rate is given by the following formula:

rate

40
Data rate (in megabytes/sec)
(256 - value of data rate byte)
For example, a data rate value of 236 corresponds to an actual data
rate of 2.0 Megabytes/sec.
Note that the DR780 ignores data rate
values greater than 251.
The parameter XFMAXRATE set at system generation limits the maximum
data rate that can be set. This parameter limits the maximum data
rate because very high data rates on certain configurations can cause
a processor timeout. If the user attempts to set the data rate higher
than the rate allowed by XFMAXRATE, the error status SS$ BADPARAM is
returned in the I/O status block.
VAX/VMS defines the following flag bit values:
XF$V CMT SETRTE

If set, XF$B CMT RATE specifies the data
rate. If clear, the data rate established by
a previous $IO STARTDATA QIO is used.
The
IO$ LOADMCODE -function sets the data rate to
the-last value used. If the data rate has
not been previously set, a value of 0 is
used.

XF$V CMT DIPEAB

If set, parity errors on the data portion of
the DDI do not cause device aborts. If
clear, a parity error results in a device
abort.

The eighth longword contains the address of a location to store the
address of the GO bit. This bit must be set whenever the application
program inserts a command packet onto an empty INPTQ.
The GO bit
register is mapped in system memory space and the address is returned
to the user.

11-22

DR32 INTERFACE DRIVER

The IO$ STARTDATA function locks the command and buffer blocks into
memory -and starts the DR32.
Whenever the DR32 interrupts with a
command packet interrupt, the driver queues a packet AST (if an AST
address is specified) and, if IO$M SETEVF is specified, sets the event
flag. The QIO remains active until one of the following events occur:
1.

A Set HALT command packet is processed by the DR32.

The data transfer aborts.

A Cancel I/O ($CANCEL)
channel.

system

service

issued

this

If an abort occurs, the second longword of the I/O status block
contains additional bits that identify the cause of the abort (see
Section 11.5).
The start data transfer function can return twelve error codes in the
I/O
status
block:
SS$ BUFNOTALIGN,
SS$ CTRLERR,
SS$ ABORT,
SS$ CANCEL, SS$ EXQUOTA, SSS INSFMEM, SS$ MCNOTVALID,
SS$ NORMAL,
ss$=IVBUFLEN, ss$_DEVREQERR, ss$_PARITY, and-SS$ PQWERFAIL.
-

11.4.6

High-level Language Interface

VAX/VMS supports a set of program-callable procedures that provide
access to the DR32. The formats of these calls are documented here
for VAX-11 FORTRAN users. VAX-11 MACRO users must set up a standard
VAX/VMS
argument block and issue the standard procedure CALL.
(Optionally, VAX-11 MACRO users can access the DR32 directly by
issuing a IO$ STARTDATA QIO, building command packets, and inserting
them onto INPTQ:) Users of other high-level languages can also specify
the proper subroutine or procedure invocation.
VAX/VMS provides six high-level language procedures for the DR32.
They are contained in the default system library, STARLET.OLB. Table
11-4 lists these procedures. Procedure arguments are either input or
output arguments, that is, arguments supplied by the user or arguments
that will contain information stored by the procedure.
Except for
those that are indicated as output arguments, all arguments in the
following call descriptions are input arguments.
By default, all
procedure arguments are integer variables unless otherwise indicated.
VAX/VMS high-level language support
following:

routines

for

the

DR32

the

•

Issue QIOs

•

Allocate and manage the command memory

•

Build command packets, insert them onto INPTQ, and set the
bit

•

Remove command packets from TERMQ and return
they contain to the controlling process

•

Use ACTION routines for program - device synchronization

11-23

the

information

DR32 INTERFACE DRIVER
Table 11-4
VAX-11 Procedures for the DR32
Function

Subroutine
XF$SETUP

Defines command
queues

and

buffer

areas;

initializes

XF$STARTDEV

Issues a QIO that starts the DR32

XF$FREESET

Releases command packets onto FREEQ

XF$PKTBLD

Builds command packets;

XF$GETPKT

Removes a command packet from TERMQ

XF$CLEANUP

Deassigns the device channel and deallocates
command area

releases them onto INPTQ

the

VAX/VMS also provides a FORTRAN parameter file, SYS$LIBRARY:XFDEF.FOR,
that can be included in FORTRAN programs. This file defines many (but
not all) of the XF$ ••• symbolic names described in this chapter. For
example,
SYS$LIBRARY:XFDEF.FOR contains symbolic definitions for
function codes (that is, device control codes), interrupt control
codes, command control codes, and masks for error bits set in the I/O
status block and the DR32 Status Longword.
To include
these
definitions in a FORTRAN program, insert the following statement in
the source code:
INCLUDE 'SYS$LIBRARY:XFDEF.FOR'

11.4.6.1 XF$SETUP - The XF$SETUP subroutine defines memory space for
the command and buffer areas, and initializes INPTQ, TERMQ, and FREEQ.
The call to XF$SETUP must be made prior to any calls to other DR32
support routines.
The format of the XF$SETUP call is as follows:
CALL XF$SETUP(contxt,barray,bufsiz,numbuf,[idevmsg] ,[idevsiz],
[ilogmsg], [ilogsiz), [cmdsiz), [status))
Argument descriptions are as follows:
contxt

A 30-longword user-supplied array that is maintained by
the support routines and is used to contain context and
status information concerning the current data transfer
(see Section 11.4.6.5).
The contxt array provides a
common storage area that all support routines share.
For
increased
performance,
contxt
should
be
longword-aligned.

11-24

DR32 INTERFACE DRIVER

bar ray

Specifies the starting virtual address of an array of
buffers that, in the case of an output operation
contain information for transfer by the DR32, or in the
case of an input operation, will contain information
transferred by the DR32. For example, if barray is
declared INTEGER*2 BARRAY (I,J), I is the size of each
data buffer in words and J is the number of buffers.
The lower bound on both indices is assumed to be 1.
All buffers in the array must be contiguous to each
other and of fixed size.

bufsiz

Specifies the size in bytes of each buffer in the
array.
All buffers are the same size. If the barray
argument is declared as stated above, bufsiz = I*2.
The bufsiz argument length is one longword.

numbuf

Specifies the number of buffers in the array.
If the
barray
argument is declared as in the preceding
paragraph, numbuf = J. The area of memory described by
the barray, bufsiz, and numbuf arguments is used as the
buffer block for DR32 data transfers.
The numbuf
argument length is one longword.

idevmsg

Specifies an array, declared by
the
application
program, that is used to store an unsolicited input
device message from the far end DR-device.
The DR32
stores unsolicited input in the device message field of
a command packet from FREEQ and places that packet onto
TERMQ.
When XF$GETPKT removes such a packet from
TERMQ, it copies the device message field into the
idevmsg array.
The calling program is then notified
that information has been stored in the idevmsg array.
The idevmsg argument is optional; the argument must be
given if any unsolicited input is anticipated.

idevsiz

Specifies the size in bytes of the idevmsg array.
The
maximum size of a device message is 25n bytes. The
idevsiz argument is optional; if idevmsg is specified,
idevsiz must be specified.' The idevsiz argument length
is one word.

ilogmsg

Specifies an array, declared by
the
application
program, that is used to store log information from the
far end DR-device contained in the log area field of
the
command
packet.
Log
information
is
hardware-dependent data that is returned by the far end
DR-device. The XF$SETUP routine stores the address and
size of the ilogmsg array;
the log information is
stored in the ilogmsg array by the XFSGETPKT routine.
The ilogmsg argument is optional; the argument must be
given if any log information is anticipated.

ilogsiz

Specifies the size in bytes of the ilogmsg array.
The
maximum size of a log message is 256 bytes. The
ilogsiz argument is optional. However, if ilogmsg is
specified, ilogsiz must be specified.
The ilogsiz
argument length is one word.

cmdsiz

Specifies the amount of memory space to be allocated
from which command packets are to be built. The user
must consider the following factors when deciding how
much memory to allocate for this purpose:
1.

The number of command packets
application program will be using.
11-25

that

the

DR32 INTERFACE DRIVER
2.

That the device message and log area fields in
command packets are rounded up to quadword
boundaries.

That the size of the command packet itself
rounded up to an 8-byte boundary.

That cmdsiz will
boundary.

rounded

is
page

argument length is
The cmdsiz argument is optional;
one longword.
If defaulted, the allocated space is
equal to:
(numbuf)*(32+idevsiz+ilogsiz)*(3)
which is rounded up to a full page.
Memory space for command packets is obtained by calling
LIB$GET VM.
status

This output argument receives the VAX/VMS
failure code of the XF$SETUP call:

success

SS$ NORMAL
Normal successful completion
SS$-BADPARAM
Invalid input argument
Error returns from LIB$GET VM
The status argument is optional;
one longword.

argument

11.4.6.2 XF$STARTDEV - The XF$STARTDEV subroutine
request that starts the DR32 data transfer.

length

the

QIO

issues

The format of the XF$STARTDEV call is as follows:
CALL XF$STARTDEV(contxt,devnam,[pktast], [astparm], [efn], [modes],
[data rt], [status])
Argument descriptions are as follows:
contxt

Specifies the array that contains context
information (see Section 11.4.f>.l).

devnam

Specifies the device name
(logical name or actual
device name) of the DR32. All letters in the resultant
string must be capitalized and the device name must
terminate with a colon, for example, "XFAO:". The
devnam datatype is character string.

pktast

Specifies the address of an AST routine that is called
each time a command packet that specifies an interrupt
in its interrupt control field is returned by the DR32,
that is, placed onto TERMQ (see Section 11.4.7.2).
This AST routine is also called on completion of the
QIO request.
Normally, the AST routine would call
XF$GETPKT to remove command packets from TERMQ until
TERMQ is empty. The pktast argument is optional.

11-26

and

status

DR32 INTERFACE DRIVER
astparm

Specifies a longword parameter that is included in the
call to the pktast-specified AST routine. The format
used to call the AST routine is:
CALL pktast(astparm)
The astparm argument is optional; argument length is
one longword.
If astparm is not specified, pktast is
called with no parameter.

efn

If the event flag must be determined by the application
program, efn specifies the number of the event flag
that is set when a packet interrupt is delivered.
Otherwise, it is not necessary to include this argument
in a XF$STARTDEV call. If defaulted, efn is 21.
The
efn argument length is one word.
The event flag (either the default or the event flag
specified by this argument)
is set for every packet
interrupt, and also when the QIO completes.

modes

Specifies the mode of operation.
following value:

VAX/VMS

defines

the

2 = parity errors on the data portion of the DD! do not
cause the device to abort.
If defaulted, modes is 0 (a
device to abort)
data rt

parity

error

causes

the

Specifies the data rate. The data rate controls the
speed at which the transfer takes place. The data rate
is considered to be an unsigned integer in the range 0
to 255.
The relationship between the specified data
rate value and the actual data rate is given by the
following formula:
40

Data rate =
(in megabytes/sec)

(256 - value of data
rate byte)

For example, a data rate value of 23n corresponds to an
actual data rate of 2.0 megabytes/sec. Note that the
DR780 ignores data rate values greater than 251.
If datart is defaulted, the previously set data rate is
used. The datart argument length is one byte.
status

This output argument receives the VAX/VMS
failure code of the XF$STARTDEV call:

success

SS$ NORMAL
Normal successful completion
SS$-BADPARAM
Required parameter defaulted
Error returns from $CREATE (which is called
assign a channel to the device) and $QIO

The status argument is optional;
one longword.

11-27

argument

length

DR32 INTERFACE DRIVER
11.4.6.3 XF$FREESET - The XF$FREESET subroutine releases
command
packets onto FREEQ. These packets are then available to the DR780 to
store any unsolicited input from the far end
DR-device.
If
unsolicited input from the far end DR-device is expected, the
XF$FREESET call should be made before the XF$STARTDEV call is issued.
Idevsiz, the argument that specifies the size of the idevmsg array in
the call to XF$SETUP, defines the size of the device message field in
command packets inserted onto FREEQ.
This is because unsolicited
deviae messages are copied from the device message field of the
command packet to the idevmsg array.
Note that the XF$FREESET subroutine may occasionally disable ASTs
a very short period.

for

The format of the XF$FREESET call is as follows:
CALL XF$FREESET(contxt, [numpkt], [intctrl], [action], [actparm],
[status])
Argument descriptions are as follows:
contxt

Specifies the array that contains context
information (see Section 11.4.6.1).

and

status

numpkt

Specifies the number of command packets to be released
onto FREEQ. The numpkt argument is optional; argument
length is one word. If defaulted, numpkt is 1.

intctrl

Specifies the conditions under which an
AST
is
delivered (and the event flag set) when the DR32 places
this command packet (or packets) on TERMQ (see Section
11.4.6.2). VAX/VMS defines the following values:
0 = unconditional AST delivery and event flag set
1 = AST delivery and event flag set only if TERMQ
empty
2 = no AST interrupt or event flag set
The intctrl argument is optional; argument
one word. If defaulted, intctrl is 0.

length

action

Specifies the address of a routine that is called when
any command packet built by this call to XF$FREESET is
removed from TERMQ by XF$GETPKT (see Section 11.4.7.3).
The action argument is optional.

act pa rm

A longword parameter that is passed to the action
routine when the action routine is called (see Section
11.4.7.3). The actparm argument is optional.

11-28

DR32 INTERFACE DRIVER

status

This output argument receives the VAX/VMS
failure code of the XF$FREESET call:
SS$ NORMAL
SS$-BADQUEUEHDR
SS$-INSFMEM
SHR$ NOCMDMEM

success

Normal successful completion
FREEQ interlock timeout
Insufficient memory to
build
command packets
Command memory is not allocated
(usually
because
the
data
transfer
has
stopped
and
XFSCLEANUP has been called, or
because XF$SETUP has not been
called)

11.4.6.4 XF$PKTBLD - The XF$PKTBLD subroutine builds command
and releases them onto INPTQ.

packets

Note that the XF$PKTBLD subroutine may occasionally disable ASTs for a
very short period.
The format of the XF$PKTBLD call is as follows:
CALL XF$PKTBLD(contxt,func, [index], [size], [devmsg], [devsiz],
[logsiz], [modes], [action], [actparm], (status])
Argument descriptions are as follows:
contxt

Specifies the array that contains context
i n for ma t ion ( see Sect ion 11 • 4 • n •1 ) •

func

Specifies the device control code.
Device control
codes describe the function the DR32 is to perform.
The func argument length is one word. VAX/VMS defines
the
following
values
(Table 11-2 describes the
functions in greater detail):
Symbol

X,F$K PKT RD
XF$K-PKT-RDCHN
XF$K-PKT-WRT
XF$K-PKT-WRTCHN
XF$K-PKT-\'ITRTCM
XF$K PKT SETTST
XF$K-PKT-CLRTST
XF$K-PKT-NOP
XF$K-PKT-DIAGRI
XF$K-PKT-DIAGWI
XF$K-PKT-DIAGRD
XF$K-PKT-DIAGWC
XF$K-PKT-SETRND
XF$K-PKT-CLRRND
XF$K-PKT-HALT

and

status

Value

Function

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

11-29

DR32 INTERFACE DRIVER
index

Specifies the index of a data buffer specified by the
barray argument {see Section 11.4.6.l). The specific
index value given means that elements barray (l,index)
through barray (size,index) will be transferred, that
is, one buffer full of data.
The index argument is
optional and only used when the function specifies a
data transfer, that is, a read device, read device
chained,
write
device,
or write device chained
function. The index argument length is one word.

size

Specifies a byte count to be transferred.
This
argument is optional and only used when the function
specifies a data transfer. If defaulted, the number of
bytes to be transferred is assumed to be the size of
the buffer (specified by the bufsiz argument in the
call to XF$SETUP). If the size argument is given, then
the specified number of bytes of data {barray (l,index)
through barray (size,index)) will be transferred. If
size is defaulted and the function specifies a data
transfer,
then
barray
(l,index)
through barray
(bufsiz,index) will be transferred. The size argument
length is one longword.

devmsg

Specifies a variable that contains the device message
to
be sent to the far end DR-device.
Provides
additional control of the far end DR-device see Section
11.4.3.12. The devmsg argument is optional.

devsiz

Specifies the size in bytes of the devmsg variable. If
the modes argument specifies that a device message is
to be sent over the control portion of the DDI, devsiz
specifies the number of bytes of devmsg that will be
sent to the far end DR-device.

logsiz

Specifies the size of the log message expected from the
far end DR-device.
The logsiz argument is optional,
argument length is one word. If defaulted, logsiz is
0.

modes

Provides additional control
of
the
VAX/VMS defines the following values:
Value

transaction.

Meaning

Only the function code is sent over the
control portion of the DOI to the far end
DR-device. Only for read device, read device
chained,
write device, and write device
chained functions.

+16

The function code and the device message are
sent over the control portion of the DDI to
the far end DR-device. Only for read device,
read device chained, write device, and write
device chained functions.

11-30

DR32 INTERFACE DRIVER
+24

The function code, the device message, and
the buff er size are sent over the control
portion of the DDI to the far end DR-device.
Only for read device, read device chained,
write device, and write
device
chained
functions.
If none of the above three
values
is
selected, nothing is transmitted over the
contrbl portion of the DDI to the far end
DR-device.

+32

Length errors are
suppressed.
If
not
selected, a length error results in an abort.

+n4

An AST should be delivered (and an event flag
set) when this command packet is inserted
onto TERMQ, provided TERMQ is empty.

+128

No AST is delivered or
this command packet.

event

flag

set

for

If both +64 and +128 are selected, +128 takes
precedence.
If neither of the above two values
is
selected, ASTs are delivered and the event
flag is set
unconditionally,
that
is,
whenever this command packet is placed onto
TERMQ.
+25n

Insert this command packet at the head of
INPTQ. If not selected, insert the packet at
the tail of INPTQ.

The modes argument default value is O.
action

Specifies the address of a routine that is called when
XF$GETPKT removes this command packet from TERMQ. This
occurs after the DR32 has completed the
command
specified in the packet (see Section 11.4.7.3). The
action argument length is one longword.

act pa rm

A longword parameter that is passed to the action
routine when the action routine is called (see Section
11.4.7.3). The actparm argument is optional.

status

This output argument receives the VAX/VMS
failure code of the XF$PKTBLD call:
SS$ NORMAL
88$-BADPARAM
88$-BADQUEUEHDR
88$-IN8FMEM
8HR$ NOCMDMEM

11-31

success

Normal successful completion
Input parameter error
INPTQ interlock timeout
Insufficient memory to
build
command packets
Command memory not
allocated
(usually
because
the
data
transfer
has
stopped
and
XF$CLEANUP has been called, or
because XF$8ETUP has not been
called)

DR32 INTERFACE DRIVER
11.4.6.5 XF$GETPKT - The
packet from TERMQ.

XF$GETPKT

subroutine

removes

command

Note that the XF$GETPKT subroutine may occasionally disable ASTs for a
very short period.
The format of the XFSGETPKT call is as follows:
CALL XF $GET PKT ( cont x t , [ wa i t fl g ] , [ fun c ] , [ index] , [de v flag ] ,
[logflag], [status])
Argument descriptions are as follows:
contxt

Specifies the array that contains the context and
status information (see Section 11.4.6.1). On return
from XF$GETPKT, the first eight longwords of the contxt
array are filled with the status of the data transfer:

.--------·---·-..- - - - - - - - - - - - - - - - - - - - - - - - - - - - .
:CONTXT

1/0 status block

4
~--------------- .. · - · - - - - - -

- - - - - - - - - -----t

control information

---------··· ----·---·-------------------------!
byte count

- - - - - - - - - - - - - - -------- ---------------·----"·------------ , _____ -----------1
virtual address of buffer

residual memory byte count

residual DOI byte count

DR32 status longword (DSL)

~-------------

The first two longwords are the I/O status block.
The
next six longwords are copied directly from bytes 8
through 31 of the command packet.
This information is returned by the DR32 as status in
each command packet.
With the exception of the I/O
status block, the information is copied by XF$GETPKT
into the contxt array whenever XF$GETPKT removes a
command packet from TERMQ.
The I/O status block is stored only after the data
transfer has halted and it contains the final status of
the transfer. Section 11.5 describes the I/O status
block.
See Section 11.4.2 for a description of
fields.

11-32

the

remaining

DR32 INTERFACE DRIVER
waitflg

Specifies the consequences of an attempt by XF$GETPKT
to remove a command packet from an empty TERMQ. If
waitflg is 0 (default), XF$GETPKT waits for the event
flag to be set and then removes a packet from TERMQ.
If waitflg is 1, XF$GETPKT returns immediately with a
failure status. Normally, waitflg is set to 1 (.TRUE.)
for AST synchronization and set to 0 (.FALSE.)
for
event flag synchronization (see Section 11.4.7). The
waitflg argument is optional.

f unc

This output argument receives the device control code
specified
in
this
command
packet (see Section
11.4.6.4). The func argument is optional;
argument
length is one word.

index

If this command packet specified a data transfer, this
output argument receives the buffer index specified
when this command packet was ·built by XF$PKTBLD
(see
Section 11.4.6.4).
The index argument is optional;
argument length is one word.

devf lag

If set to .TRUE.
(255), this output argument indicates
that a device message was stored in the idevmsg array,
which is described in the XF$SETUP call
(see Section
11.4.6.1). The devflag argument is optional; argument
length is one byte.

logf lag

If set to .TRUE.
(255), this output argument indicates
that a log message was stored in the ilogmsg array,
which is described in the XF$SETUP call
(see Section
11.4.6.1). The logflag argument is optional; argument
length is one byte.

status

This output argument
XF$GETPKT call:
SS$ NORMAL
SS$-BADQUEUEHDR
SHRS_QEMPTY

SHR$ HALTED

SHR$ NOCMDMEM

receives

the

status

the

Normal successful completion
TERMQ interlock timeout
The TERMQ was empty but the
transfer is still in progress.
Only returned if waitflg
is
.TRUE.
TERMQ was empty, the transfer is
complete, and the I/O status
block contains the final status.
XF$CLEANUP
has
been
called
automatically. Subsequent calls
to
XF$GETPKT
return
SHR$ NOCMDMEM.
Command memory not allocated.
Usually indicates either:
was

not

XF$SETUP
called.

XF$CLEANUP was called.

11.4.6.6 XF$CLEANUP - The XF$CLEANUP subroutine deassigns the channel
and deallocates the command area allocated by XF$SETUP. If XF$GETPKT
detects a TERMQ empty condition and the transfer has halted, it will
automatically call XF$CLEANUP.
However, if the transfer either
terminates in a SS$ .CTRLERR
or
SS$_BADQUEHDR
error,
or
is

11-33

DR32 INTERFACE DRIVER
intentionally terminated, XF$GETPKT may not detect these conditions
and XF$CLEANUP should be called explicitly.
The format of the XF$CLEANUP call is as follows:
CALL XF$CLEANUP(contxt, [status])
Argument descriptions are as follows:
contxt

Specifies the array that contains context
information (see Section 11.4.6.1).

status

This output argument
XF$CLEANUP call:

receives

the

and

status

status
of

the

SS$ NORMAL
Normal successful completion
SHRS NOCMDMEM
Command memory not allocated
Error returns from LIBSFREE VM and SDASSIGN

11.4.7

User Program - DR32 Synchronization

Synchronization of high-level language application programs
DR32 can be achieved in three ways:
•

Event flags

•

AST routines

•

Action routines

with

the

11.4.7.1 Event Flags - Event flag synchronization is attained by
callin'g the XFSGETPKT routine (see Section 11.4.6.5) with the waitflg
argument set to 0 (default). The pktast argument in the XF$STARTDEV
routine
(see Section 11.4.6.2)
is normally defaulted.
If the
XF$GETPKT routine is called and the termination queue is empty, the
routine waits until the DR32 places a command packet on the queue and
sets the event flag. The packet is then removed from the queue and
returned to the caller.

11.4.7.2 AST Routines - If a call to the XF$STARTDEV routine includes
the pktast argument, the specified AST routine is called each time an
AST is delivered.
AST
delivery
can
be
controlled
on
a
packet-by-packet basis through use of the intctrl argument in the
XF$FREESET routine and by specifying appropriate values in the modes
argument
of
the XF$PKTBLD routine
(see Sections 11.4.~.3 and
11.4.6.4). For a particular command packet, ASTs can be delivered:
1.

Unconditionally when the packet is placed onto TERMQ.

Only if TERMQ is empty when the packet is placed on it.

Not at all. That is, there is no
placed on TERMQ.

AST

when

the

packet

There is no guarantee that an AST will be delivered for every command
packet, even when the astctrl argument indicates unconditional AST
delivery. In particular, if packet interrupts are closely spaced,
several packets may be placed onto TERMQ even though only one AST is

11-34

DR32 INTERFACE DRIVER
delivered. Therefore, the AST routine should continue to call the
XF$GETPKT routine until all command packets are removed from TERMQ.

11.4.7.3 Action Routines - The action argument specified in the
XF$FREESET and XF$PKTBLD routines (see Sections 11.4.n.3 and 11.4.n.4)
can be used for a more automated synchronization of the program with
the DR32. Routines specified by action arguments can be used for both
event flag and AST routine synchronization.
The address of the action routine is included in the command packet.
This routine is automatically called by the XF$GETPKT routine when it
removes that packet from TERMQ. This allows the user to define, at
the time it is built, how the command packet will be handled once it
is removed from TERMQ. In addition to specifying different action
routines for different types of command packets, the user can also
specify an action routine parameter (actparm) to further identify the
command packet and/or the action to be taken on completion of the
command. Figure 11-7 shows the use of action-specified routines for
program synchronization.
An important difference between AST routine and action routine use is
the number of times the respective routines are specified. Command
packet AST routines are specified only once, in a XF$STARTDEV call; a
single
AST routine is implied.
Action routines, however, are
specified in each command packet.
This allows a different action
routine to be designed for each type of command packet.
APPLICATION
PROGRAM

XF$GETPKT

CALL
XF$GETPKT

REMOVE PACKET
FROM TERMQ
CALL ACTION

ACTION
PACKETSPECIFIC
PROCEDURE

ACTION Routines with Event Flag Synchronization

APPLICATION
PROGRAM
AST ROUTINE
XF$GETPKT

REMOVE PACKET
FROM TERMQ
CALL ACTION

CALL
XF$GETPKT

PACKETSPECIFIC
PROCEDURE

ACTION Routines with AST Routine Synchronization

Figure 11-7

ACTION

ACTION Routine Synchronization

11-35

DR32 INTERFACE DRIVER
Routines specified by the action argument are supplied
The format of the calling interface is as follows:

the

user.

CALL action-routine (contxt,actparm,devflag,logflag,func,
index,status)
With the exception of actparm, all arguments are the same as those
described for the XF$GETPKT routine. In effect, the action routine
will receive the same information XF$GETPKT optionally returns to its
calling program, along with the actparm argument that was specified
when the packet was built. If these variables are to be passed as
inputs to the action routine, they must be supplied as output
variables in the call to the XF$GETPKT routine.

11.5

I/O STATUS BLOCK

The I/O status block for the load microcode and start data transfer
QIO functions is shown in Figure 11-8. The I/O status block used in
the first two longwords of the contxt array for high-level language
calls also employs this format.
27 26 24 23

16 15

5
status
L....-_ _
bits_ _

status

-:--r_

16 status bits

DOI status

..___:__i _________

Figure 11-8 I/O Functions IOSB Content
VAX/VMS status values are returned in the first longword. Table 11-5
lists
these
values.
If either SS$ CTRLERR, SS$ DEVREQERR, or
SS$ PARITY is returned in the status word, the second longword
contains additional returns, that is, device-dependent data. Table
11-6 lists these returns.
The I/O status block for a QIO function is returned after the function
completes.
Status is not stored on the completion of every command
packet because any number of packets can pass between the application
program and the DR32 during the execution of a single QIO.
Table 11-5
DR32 Status Returns
Status

Meaning

SS$ ABORT

Request aborted. A request in progress was
aborted by the $CANCEL system service.
(Only
for start data transfer functions.)

SS$ BADPARAM

Bad parameter. An attempt was made to set the
data rate higher than the rate allowed by the
SYSGEN parameter XFMAXRATE.
(Only for start
data transfer functions.)
(continued on next page)

ll-3n

DR32 INTERFACE DRIVER
Table 11-5 (Cont.)
DR32 Status Returns
Status

Meaning

------------1~---·~- ----~ ~--------------------!

SS$_BADQUEHDR

Bad queue header.
timeout occurred.

SS$ BUFNOTALIGN

Alignment error. The command block address in
the
Data Transfer Command Table was not
quadword aligned.
(Only for
start
data
transfer functions.)

SS$ CANCEL

Request cancelled by the
$CANCEL
service before it started.
(Only
start data transfer functions.)

SS$ CTRLERR

Controller
error.
A
fatal
hardware
malfunction
occurred that stops all DR32
activity.
(Only for start data
transfer
functions.)
The second longword of the IOSB
contains additional information pertaining to
this error;
the following bit values are
associated with SS$ CTRLERR:

An INPTQ or TERMQ interlock

system
for the

XF$V !OS INVPTE
XF$V-IOS-SBI ERR
XF$V-IOS-RDSERR
SS$ DEVACTIVE

Device is active.
The microcode cannot be
loaded
because
there is an active data
transfer request.
(Only
for
the
load
microcode function.)

SS$_DEVREQERR

DR32 user request error. A programming error
or an error associated with the far end
DR-device is indicated. The second longword
of the I/O status block contains additional
information pertaining to the error;
the
following
bit values are associated with
SS$_DEVREQERR:
XF$V !OS DDIDIS
XF$V-IOS-RNGERR
XF$V-IOS-UNQERR
XF$V-I OS-INVPKT
XF$V-IOS FREQMT
XF$V-I OS-INVDD I
XF$V-IOS-LENERR
XF$V-IOS-DDIERR

SS$_EXQUOTA

AST quota exceeded.
A command packet AST
cannot be queued because the process AST quota
was exceeded.
(Only for start data transfer
functions.)

SS$ INSFMEM

Insufficient dynamic memory to initiate a
start data transfer request, build a command
packet, or queue a command packet AST.
(continued on next page)

11-37

DR32 INTERFACE DRIVER
Table 11-5 (Cont.)
DR32 Status Returns

----.-----··-----------------------------.
Status

Meaning

SS$ IVBUFLEN

Incorrect length. Either the command block
size or the buffer block size is 0 or equal to
or greater than 2**29, or the command table
length is not XF$K CMT LENGTH.

SS$ MCNOTVALID

Microcode has not yet been successfully loaded
or has become invalid.
(Only for start data
transfer functions.)

SS$ NORMAL

QIO request or support routine call completed
successfully. Either the microcode was loaded
successfully or
the
data
transfer
was
completed successfully.

SS$ PARITY

Parity error. Either the microcode was not
loaded successfully or the DR32 controller
a
hardware
detected a parity error and
malfunction is indicated. The second longword
of the I/O status block contains additional
information pertaining to this malfunction;
the following bit values are associated with
SS$ PARITY:
XF$V !OS WCSPE
XF$V-IOS-CIPE
XF$V-IOS-DIPE
XF$V-IOS-PARERR

SS$ POWERFAIL

A power failure occurred while a data transfer
request was active or the DR32 is powered
down.

Table 11-n
Device-Dependent IOSB Returns for I/O Functions
~-·-~-"-'"'------·····

Meaning

Symbolic Name
16 Status Bits
----~-'""'~-,.---·---·

XF$V PKT SUCCESS

The command was performed successfully

XF$V !OS CMDSTD

Command specified
started.

XF$V !OS INVPTE

Invalid page table entry.

XF$V !OS FREQ PK

This command packet came from FREEQ.

XF$V !OS DD ID IS

The far end DR-device is disabled.

XF$V !OS SLFTST

The DR32 is in self-test mode.

the

command

packet

... _ _ _ _ _ _ _ _ _ _.,..i._ _______ ,,.........._, _ _ _ _ _ _ _ _

(continued on next page)

11-38

DR32 INTERFACE DRIVER

Table 11-n (Cont.)
Device-Dependent IOSB Returns for I/O Functions
Symbolic Name

Meaning

XF$V IOS RNG ERR

Range error. The user-provided address is
outside the command block range or the buffer
block range.

XF$V_IOS_UNQERR

A queue element was not aligned on a quadword
boundary.

XF$V IOS INVPKT

A packet was not a valid DR32 command packet.

XF$V_IOS_FREQMT

A message was received from
DR-device and FREEQ was empty.

XF$V IOS RNDENB

Random access mode is enabled.

XF$V IOS INVDDI

A protocol error occurred on the DDI.

- XF$V IOS LENERR
- -

the

far

The far end DR-device terminated the data
transfer before the required number of bytes
were sent, or a message was received from the
far end DR-device and the device message
field in the command packet at the head of
FREEQ was not large enough to hold it.

XF$V IOS DRVABT

The I/O driver aborted the DR32 function.

XF$V PKT PARERR

A parity error occurred on
control portion of the DDI.

end

the

data

DDI Status
XF$V IOS DDISTS

The 1-byte status register O for the far end
DR-device.
XF$V IOS NEXREG, XF$V IOS LOG,
and XF$V IOS DDIERR are returns from -this
register:-

XF$V IOS NEXREG

An attempt was made to access a nonexistent
register on the far end DR-device.

XF$V IOS LOG

The far end DR-device registers are stored in
the log area.

XF$V IOS DDIERR

An error occurred on the far end DR-device.

5 Status Bits
XF$V_IOS_BUSERR

An error on the processor's internal CPU memory
bus occurred.

XF$V IOS RDSERR

A noncorrectable memory
Data Substitute).

XF$V IOS WCSPE

Writeable Control Store parity error.

XF$V IOS CIPE

Control Interconnect parity error.
A parity
error occurred on the control portion of the
DDI.

XF$V IOS DIPE

Data Interconnect parity error. A parity error
occurred on the data portion of the DDI.

11-39

error

occurred

(Read

DR32 INTERFACE DRIVER
PROGRAMMING HINTS

11.6

This
section
considerations
chapter.

11.6.1

contains
information
on
important
programming
relevant to users of the DR32 driver described in this

Command Packet Pre-fetch

The DR32 has the capability of pre-fetching command packets from
INPTQ.
While executing the command specified in one packet, the DR32
can pre-fetch the next packet, decode it, and be ready to execute the
specified command at the first opportunity.
When the command is
executed depends on which command is specified. For example, if two
read device or write device command packets are on INPTQ, the DR32
fetches the first packet, decodes the command, verifies that the
transfer is legal, and starts the data transfer. While the transfer
is taking place, the DR32 pre-fetches the next read device or write
device command packet, decodes it, and verifies the transfer legality.
The second transfer begins as soon as the first transfer is completed.
On the other hand, if the two command packets on INPTQ are read device
(or write device) and write device control message, in that order, the
DR32 pre-fetches the second packet and immediately executes the
command,
because control messages can be overlapped with data
transfers. The DR32 then pre-fetches the next command packet. In an
extreme case, the DR32 can send several control messages over the
control portion of the DD! while a single data transfer takes place on
the data portion of the DDI.
The pre-fetch capability and the overlapping of control and data
transfers can cause unexpected results when programming the DR32. For
instance, if the application program calls for a data transfer to the
far end DR-device followed by notification of the far end DR-device
that data is present, the program cannot simply insert a write device
command packet and then a write control message command packet onto
INPTQ -- the control message may very likely arrive before the data
transfer completes.
A better way to synchronize the data transfer with notification of
data arrival is to request an interrupt in the interrupt control field
of the data transfer command packet. Then, when the data transfer
command packet is removed from TERMQ, the application program can
insert a write control message command packet onto INPTQ to notify the
far end DR-device that the data transfer has completed.
Another consequence of command packet pre-fetching occurs when, for
example, two write device command packets are inserted onto INPTQ.
While the first data transfer takes place, the second command packet
is pre-fetched and decoded.
If an unusual event occurs and the
application program must send an immediate control message to the far
end DR-device, the application program may insert a write device
control message packet onto INPTQ. However, this packet is not sent
immediately because the second write device command packet has already
been pre-fetched; the control message is sent after the second data
transfer starts.
If the application program requires the ability to send a control
message with minimum delay, use one of the following techniques:
•

Insert only one data transfer function onto INPTQ at a time.
If this is done, a second transfer function will not be
pre-fetched and a control message can be sent at any time.

11-40

DR32 INTERFACE DRIVER
•

Use smaller buffers or a faster data rate to reduce
necessary to complete a given command packet.

•

Issue a $CANCEL system
IO$_STARTDATA QIO.

11.6.2

service

call

followed

the
by

time

another

Action Routines

Action routines provide a useful DR32 programming technique. They can
be used in application programs written in either assembly language or
a high-level language. When a command packet is built, the address of
a routine to be executed when the packet is removed from TERMQ is
appended to the end of the packet.
Then, rather than having to
determine what action to perform for a particular packet when it is
removed from TERMQ, the specified action routine is called.

11.6.3

Error Checking

Bits 0 through 23 in the second longword of the I/O status block
correspond to the same bits in the DR32 status longword (DSL).
Although the I/O status block is written only after the QIO function
completes, the DSL is stored in every command packet. However,
because there is no command packet in which to store a DSL for certain
error conditions, for example, FREEQ empty, some errors are reported
only in the I/O status block. To check for an error under these
conditions, the user should examine the DSL in each packet for success
or failure only. Then, if a failure occurs, the specific error can be
determined from the I/O status block. The I/O status block should
also be checked to verify that the QIO has not completed prior to a
wait for the insertion of additional command packets onto TERMQ. In
this way, the application program can detect asynchronous errors for
which there is no command packet available.

11.6.4

Queue Retry Macro

When an interlocked queue instruction is included in the application
program, the code should perform a retry if the queue is locked.
However, the code should not execute an indefinite number of retries.
Consequently, all retry loops should contain a maximum retry count.
The macro programming example provided in Section 11.7 contains a
convenient queue retry macro.

11.6.5

Diagnostic Functions

The diagnostic functions listed in Table 11-2 can be used to test the
DR32 without the presence of a far end DR-device. For the DR780, the
user should perform the following test sequence:
1.

Insert a set self-test command packet onto INPTQ.

Insert a diagnostic write internal command packet that
specifies a 128-byte buffer onto INPTQ. This packet copies
128 bytes from memory into the DR780 internal data silo.

11-41

DR32 INTERFACE DRIVER

Insert a diagnostic read DDI command packet onto INPTQ. This
packet transmits the 128 bytes of data from the silo over the
DDI and returns it to the silo.

Insert a diagnostic read internal command packet
that
specifies another 128-byte buffer in memory onto INPTQ. This
packet copies 128 bytes of data from the silo into memory.

Compare the two memory buffers
the DR780, the diagnostic read
first four bytes in the silo
memory.
Therefore, compare
two buffers.

Insert a clear self-test command packet onto INPTQ.

11.6.6

for equality.
Note that on
internal function destroys the
before storing the data in
only the last 124 bytes of the

The NOP Command Packet

It is often useful to insert a NOP command packet onto INPTQ to test
the state of the DDI disable bit (XF$M PKT DDIDIS in the DSL). By
checking this bit before initiating a data- transfer, an application
program can determine if the far end DR-device is ready to accept
data.

11.6.7

Interrupt Control Field

As described ih Section 11.4.3.6, the interrupt control
field
determines the conditions under which an interrupt is generated:
unconditionally, if TERMQ was empty, or never.
There are several
general applications of this field:
1.

If a program performs five data transfers and requires
notification
of
completion
only after all five have
completed, the first four command packets should specify no
interrupt and the fifth command packet should specify an
unconditional interrupt.

If a program performs a continuous series of data transfers,
for example, each command packet can specify interrupt only
if TERMQ was empty. Then, every time an event flag or AST
notifies the program that a command packet was inserted onto
TERMQ, the program removes and processes all packets on TERMQ
until it is empty.

3. Command packets that specify no interrupt should never be
mixed with command packets that specify interrupt if TERMQ
was empty.
If this were done, a command packet that
specifies no interrupt could be inserted onto TERMQ followed
by a command packet that specifies interrupt if TERMQ was
empty.
Then the latter packet would not interrupt and the
program would never be notified that command packets were
inserted onto TERMQ.

11-42

DR32 INTERFACE DRIVER
11.7

PROGRAMMING EXAMPLES

The program examples in the following two sections use DR32 high-level
language procedures and DR32 Queue I/O functions.

11.7.1

DR32 High-level Langauge Program (Program A)

This program is an example of how the DR32 high-level
language
procedures perform a data
transfer from a far end DR-device.
The
program reads a specified number of data buffers from an undefined far
end DR-device, which is assumed to be a data source, into the VAX-11
memory.
The number of buffers is controlled by the MAXBUF parameter.
The program contains examples of the read data chained function code
and DR32 application program synchronization using AST routines and
action routines.

c
c

*******************************************************************

PROGRAM A

*******************************************************************

INCLUDE 'XFDEF.FOR'
PARAMETER
BUFSIZ
PARAMETER
NUMBUF

1024

PARAMETER

ILOGSIZ

PARAMETER

EFN

INTEGER* 2
INTEGER*2

BUFARRAY(BUFSIZ,NUMBUF)
INDEX

INTEGER*2

COUNT

INTEGER* 2

DATART

INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

CONTXT(30)
!CONTEXT ARRAY USED BY SUPPORT
ILOGMSG(ILOGSIZ)!LOG MESSAGES FROM DEVICE
!STORED HERE
STATUS
!RETURNS FROM SUBROUTINES
DEVMSG
!FAR END DR-DEVICE CODE

EXTERNAL
EXTERNAL

ASTRTN
AST$PROCBUF

EXTERNAL

AST$HALT

;DEFINE XF CONSTANTS
SIZE OF EACH BUFFER
NUMBER OF BUFFERS IN
RING
SIZE OF INPUT LOG
ARRAY
EVENT FLAG SYNCHRONIZING MAIN LEVEL WITH
AST ROUTINE

!THE RING OF BUFFERS
!REFERS TO BUFFER
! IN BUFARRAY
!COUNTS NUMBER OF
!BUFFERS FILLED
!DR32 CLOCK RATE

AST ROUTINE
ACTION ROUTINE TO HANDLE
COMPLETION OF READ DATA
COMMAND PACKET
ACTION ROUTINE TO HANDLE
COMPLETION OF A HALT
COMMAND PACKET

COMMON /MAIN AST/
CONTXT, INDEX
COMMON /MAIN-ACTION/
BUFARRAY, ILOGMSG, COUNT
EXTERNAL
SS$ NORMAL
!SUCCESS STATUS RETURN

c
c

******************************************************************

THE CALL TO THE SETUP ROUTINE

11-43

DR32 INTERFACE DRIVER

******************************************************************
CALL XF$SETUP (CONTXT,BUFARRAY,BUFSIZ*2,NUMBUF,,,ILOGMSG,
1
ILOGSIZ*4,,STATUS)
IF (STATUS .NE .• %LOC(SS$_NORMAL)) CALL LIB$STOP(%VAL(STATUS))

c
C
C

PRE-LOAD THE INPUT QUEUE BEFORE STARTING THE DR32 IN ORDER TO AVOID
A DELAY IN THE DATA TRANSFER

c
c
c
C

******************************************************************
BUILD COMMAND PACKETS

******************************************************************

C
C
C
C

BUILD THE COMMAND PACKET THAT WILL INSTRUCT THE FAR END DR-DEVICE
TO START SAMPLING. ARBITRARILY ASSUME THAT THE FAR END DR-DEVICE
WILL RECOGNIZE THIS DEVICE MESSAGE.
INSERT THIS PACKET ON THE
INPUT QUEUE (INPTQ).

DEVMSG = 25

!SIGNAL FAR END DR-DEVICE
! "GO"

CALL XF$PKTBLD (
1
CONTXT,
1
XFSK PKT_WRTCM,
1

DEVMSG,

1
1

XF$K PKT UNCOND

1
1

+ XF$K PKT CBDM
+ XF$K-PKT-INSTL

1
1

!THE CONTEXT ARRAY
'WRITE CONTROL MESSAGE
FUNCTION
NO INDEX OR SIZE
SIGNAL "GO"
SIZE OF DEVMSG IN BYTES
SPACE FOR INPUT LOG
MESSAGE
MODES: UNCONDITIONAL
INTERRUPT
SEND FUNC AND DEVMSG
INSERT PACKET AT INPTQ
TAIL
NO ACTION ROUTINE OR ACTPARM

ILOGSIZ*4

STATUS)
IF (STATUS .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP(%VAL(STATUS))

c
C
C

IN A LOOP, BUILD THE COMMAND PACKETS THAT WILL PERFORM THE CHAINED
READ TO INITIALLY FILL THE BUFFERS
DO 10
1
1

INDEX= 1, NUMBUF
CALL XF$PKTBLD(
CONTXT,
XF$K PKT RDCHN,
INDEX, -

,,,

1
1

ILOGSIZ*4,
XF$K PKT UNCOND

1
1

+ XF$K PKT CB
+ XF$K=PKT=INSTL,

AST$PROCBUF,

!FOR ALL BUFFERS DO
THE CONTEXT ARRAY
READ DATA CHAINED
IDENTIFIES BUFFER
NO SIZE, DEVMSG, OR DEVSIZ
SPACE FOR INPUT LOG MESSAGE
MODES: UNCONDITIONAL
INTERRUPT
SEND FUNCTION CODE
INSERT PACKET AT INPTQ
TAIL
ACTION ROUTINE
NO ACTPARM

11-44

DR32 INTERFACE DRIVER

1
STATUS)
IF (STATUS .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP(%VAL(STATUS))
CONTINUE

c
C

THE INPUT QUEUE IS LOADED

c
c

*******************************************************************

START THE DR32

*******************************************************************

DATART = 0
COUNT = 0
CALL SYS$CLREF (%VAL(EFN))

!DATA TRANSFER RATE
!NUMBER OF BUFFERS THAT HAVE
!BEEN FILLED
!CLEAR EVENT FLAG BEFORE START

CALL XF$STARTDEV (CONTXT,'XFAO:' ,ASTRTN,,,,DATART,STATUS)
IF (STATUS .NE. %LOC(SSS_NORMAL)) CALL LIB$STOP(%VAL(STATUS))

c
C
C

FROM THIS POINT, ROUTINES AT THE AST LEVEL ASSUME CONTROL.
FOR THEM TO SIGNAL COMPLETION OF THE SAMPLING SWEEP.

WAIT

c
CALL SYS$WAITFR (%VAL(EFN))
STOP
END

c
c

*******************************************************************

AST ROUTINES

c
c

*******************************************************************
SUBROUTINE

ASTRTN (ASTPARM)

INCLUDE 'XFDEF.FOR/NOLIST'
INTEGER*2
ASTPARM

!UNUSED PARAMETER

INTEGER*4
INTEGER*4

CONTXT(30)
STATUS

!CONTEXT ARRAY
!FOR CALL TO XFSGETPKT

LOGICAL*l
LOGICAL*l

WAITFLG
LOG FLAG

!INPUT TO XFSGETPKT
!INPUT TO XF$GETPKT

COMMON

/MAIN_AST/

EXTERNAL

CONTXT, INDEX

SS$ NORMAL

c
C
C

CALL XF$GETPKT IN A LOOP UNTIL TERMQ IS EMPTY.
XFSGETPKT WILL CALL
THE APPROPRIATE ACTION ROUTINE FOR EACH COMMAND PACKET.
WAITFLG
LOG FLAG

!DO NOT WAIT FOR EVENT FLAG
!REQUEST NOTIFICATION IF LOG
!MESSAGE IS IN PACKET

.TRUE.
.TRUE.

CALL XF$GETPKT (CONTXT,WAITFLG,,INDEX,,LOGFLAG,STATUS)
IF (STATUS .EQ. %LOC(SS$_NORMAL))
!PACKET FROM TERMQ

11-45

DR32 INTERFACE DRIVER
1
GOTO 10
IF (STATUS .EQ. SHR$_QEMPTY)
!TERMQ EMPTY - TRANSFER
1
GOTO 20
!STILL IN PROGRESS
IF (STATUS .EQ. SHR$ HALTED .OR. STATUS .EQ. SHR$ NOCMDMEM)
1
GOTO 20
!TRANSFER COMPLETE. NO MORE
!COMMAND PACKETS. ASTS MAY
!STILL BE DELIVERED
CALL LIB$STOP (%VAL(STATUS))
20

!ERROR IN XFSGETPKT

RETURN
END

c
c

*******************************************************************

ACTION ROUTINE

*******************************************************************

SUBROUTINE
1

AST$PROCBUF (CONTXT,ACTPARM,DEVFLAG,LOGFLAG,
FUNC,INDEX,STATUS)

c
C
C
C
C
C
C
C
C

THIS IS THE ACTION ROUTINE CALLED BY XF$GETPKT WHEN IT REMOVES A
COMMAND PACKET FROM TERMQ. THIS PACKET HAS JUST COMPLETED A READ
DATA OPERATION FROM THE BUFFER SPECIFIED BY INDEX. THE BUFFER IS
PROCESSED, AND IF MORE DATA IS REQUIRED (I.E., BUFCOUNT .LE.
MAXCOUNT), ANOTHER PACKET IS BUILT. THE BUFFER IN THIS PACKET IS
THEN REFILLED AND THE PACKET IS INSERTED ONTO INPTQ.
IF BUFCOUNT .GT. MAXCOUNT, THE SAMPLING SWEEP IS FINISHED AND A
HALT PACKET IS INSERTED ONTO INPTQ.
INCLUDE
PARAMETER
PARAMETER

'XFDEF.FOR/NOLIST'
MAXCOUNT = 10
!NUMBER OF BUFFERS IN SWEEP
ILOGSIZ = 4
!SIZE OF INPUT LOG MESSAGE

PARAMETER

BUFSIZ

= 1024

PARAMETER

NUMBUF

INTEGER*2
BUFARRAY
INTEGER*2
INTEGER*2
FILLED
INTEGER* 2

INDEX

!REFERS TO A BUFFER IN

FUNC
BUFCOUNT

!FUNCTION CODE FROM PACKET
!COUNTS NUMBER OF BUFFERS

INTEGER*4
INTEGER*4

ACTPARM
STATUS

INTEGER*4
INTEGER*4
INTEGER*4

STAT
!STATUS OF CALL TO XF$PKTBLD
CONTXT(30)
!CONTEXT ARRAY USED BY SUPPORT
ILOGMSG(ILOGSIZ)!STORES LOG MESSAGES FROM

LOGICAL*l
LOGICAL*l

DEV FLAG
LOG FLAG

ARRAY

!SIZE OF EACH BUFFER (IN

WORDS)
!NUMBER OF BUFFERS

BUFARRAY(BUFSIZ,NUMBUF)

!THE ARRAY OF BUFFERS

!ACTION PARAMETER (NOT USED)
!STATUS OF XF$GETPKT (NOT

USED)

DEVICE

COMMON
EXTERNAL
EXTERNAL

/MAIN_ACTION/

!NOT USED IN THIS EXAMPLE
!SIGNALS LOG MESSAGE PRESENT
BUFARRAY,ILOGMSG,BUFCOUNT

SS$ NORMAL
ASTSHALT

11-46

DR32 INTERFACE DRIVER

c
C

PROCESS THE BUFFER

c
DO 10

= 1, BUFSIZ

c
c

*******************************************************************

C
C

AT THIS POINT INSERT THE CODE TO PROCESS ELEMENT {!,INDEX) OF
BUFARRAY

c
c

*******************************************************************

CONTINUE

*******************************************************************

AT THIS POINT INSERT THE CODE TO LOOK AT THE LOG MESSAGE

c
c

*******************************************************************

c
C

IS THIS THE LAST BUFFER IN THE SWEEP?

c
BUFCOUNT

BUFCOUNT + 1
IY (BUFCOUNT .LT. MAXCOUNT) THEN
CALL FAKE$PKTBLD (
1
CONTXT,
1
XF$K PKT RDCHN,
INDEX, 1

,,,

1
1
1

ILOGSIZ*4,
XF$K PKT UNCOND

1
1

+ XF$K PKT CB
+ XF$K=PKT=INSTL,

, ,

!BUILD A PACKET TO
REFILL THE BUFFER
NEED INTERVENING ROUTINE
THE CONTEXT ARRAY
READ DATA CHAINED
BUFFER INDEX
NO SIZE, DEVMSG, OR DEVSIZ
SPACE FOR LOG MESSAGE
MODES: UNCONDITIONAL
INTERRUPT
SEND CONTROL BYTE
INSERT AT TAIL
ACTION GIVEN IN FAKESPKTBLD

1
STAT)
IF (STAT .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP (%VAL(STAT))
ELSE IF (BUFCOUNT .EQ. MAXCOUNT)
CALL FAKE$PKTBLD (
1
CONTXT,
1
XF$K PKT RD,
INDEX, 1
1
1
1

,,,

ILOGSIZ*4,
XF$K PKT UNCOND

1
1

+ XF$K PKT CB

, ,

+ XF$K=PKT=INSTL,

THEN
!END OF CHAIN
NEED INTERVENING ROUTINE
THE CONTEXT ARRAY
READ DATA FUNCTION
BUFFER INDEX
NO SIZE, DEVMSG, OR DEVSIZ
SPACE FOR LOG MESSAGE
MODES: UNCONDITIONAL
INTERRUPT
SEND CONTROL BYTE
INSET AT TAIL
ACTION GIVEN IN FAKE$PKTBLD

1
STAT)
IF (STAT .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP (%VAL(STAT))
ELSE
1
1
1

!BUILD A HALT PACKET
CALL XF$PKTBLD
CONTXT,
XF$K_PKT_HALT,

!THE CONTEXT ARRAY
!ALL DONE
!DEFAULT VALUES

,,,,

11-47

DR32 INTERFACE DRIVER
!SPACE FOR INPUT LOG MESSAGE
! ACTION ROUTINE

ILOGSIZ*l,
AST$HALT,

l
l

l
I
!NO ACTPARM
l
STAT)
IF (STAT .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP (%VAL(STAT))
END IF
RETURN
END

*******************************************************************

PASS ADDRESS OF ACTION ROUTINE TO COMMAND PACKET

c
c

*******************************************************************
SUBROUTINE

FAKE$PKTBLD(A,B,C,D,E,F,G,H,I,J,K)

c
C
C
C

AST$PROCBUF CALLS THIS SUBROUTINE IN ORDER TO PASS THE ADDRESS OF
AST$PROCBUF TO XF$PKTBLD.
(AST$PROCBUF CANNOT REFER TO ITSELF
WITHIN THE SCOPE OF AST$PROCBUF)
EXTERNAL

AST$PROCBUF

CALL XF$PKTBLD (A,B,C,D,E,F,G,H,AST$PROCBUF,J,K)
RETURN
END

c
c

******************************************************************

HALT ACTION ROUTINE

******************************************************************

SUBROUTINE

AST$HALT (CONTXT,ACTPARM,DEVFLAG,LOGFLAG,
FUNC,INDEX,STATUS)

c
C
C
C
C

THIS IS THE ACTION ROUTINE CALLED BY XF$GETPKT WHEN IT REMOVES A
HALT PACKET FROM TERMQ. THIS ROUTINE PRINTS STATUS INFORMATION,
CALLS XF$CLEANUP TO PERFORM FINAL HOUSEKEEPING FUNCTIONS, AND SETS
THE EVENT FLAG THAT SIGNALS THE TRANSFER IS COMPLETE.

PARAMETER

EFN

INTEGER*2
INTEGER*2

FUNC
INDEX

!NOT USED
!NOT USED

INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

ACTPARM
STATUS
STAT
CONTXT(30)

!NOT USED
!NOT USED
!RETURN FROM XF$CLEANUP
!CONTEXT ARRAY USED BY SUPPORT

LOGICAL*l
LOGICAL*l

DEV FLAG
LOG FLAG

!NOT USED
!SIGNALS LOG MESSAGE

11-48

DR32 INTERFACE DRIVER
EXTERNAL

SS$ NORMAL

!SUCCESS STATUS RETURN

c
C

PRINT FINAL STATUS

*, 'FINAL STATUS IN I/O STATUS BLOCK'
*, CONTXT(l), CONTXT(2)

PRINT
PRINT

c
C

CLEAN UP
CALL XF$CLEANUP (CONTXT,STAT)
IF (STAT .NE. %LOC(SS$_NORMAL)) CALL LIB$STOP (%VAL(STAT))
CALL SYS$SETEF (%VAL(EFN))
RETURN
END

11.7.2

DR32 Queue I/O Functions Program (Program B)

This sample program uses QIO functions to send a device message to the
far
end DR-device and then waits for a message returned in a command
packet on FREEQ. The returned message is copied into another command
packet and that packet writes a data buffer to the far end DR-device.

********************************************************************
PROGRAM B

********************************************************************
.TITLE
.!DENT

DR32 PROGRAMMING EXAMPLE
/01/

DEFINE SYMBOLS
$XFDEF

QRETRY - THIS MACRO EXECUTES AN INTERLOCKED QUEUE INSTRUCTION AND
RETRIES THE INSTRUCTION UP TO 25 TIMES IF THE QUEUE IS
LOCKED.
INPUTS:
OPCODE
OPCODE NAME: INSQHI,INSQTI,REMQHI,REMQTI
OPERANDl = FIRST OPERAND FOR OPCODE
OPERAND2 = SECOND OPERAND FOR OPCODE
SUCCESS = LABEL TO BRANCH TO IF OPERATION SUCCEEDS
ERROR = LABEL TO BRANCH TO IF OPERATION FAILS
OUTPUTS:
RO

DESTROYED

11-49

DR32 INTERFACE DRIVER
C-BIT

CLEAR IF OPERATION SUCCEEDED
SET IF OPERATION FAILED - QUEUE LOCKED
(MUST BE CHECKED BEFORE V-BIT OR Z-BIT)

REMQTI OR REMQHI:
V-BIT

= CLEAR IF AN ENTRY REMOVED FROM QUEUE; SET
IF NO ENTRY REMOVED FROM QUEUE.

INSQTI OR INSQHI:
Z-BIT

= CLEAR IF ENTRY IS NOT FIRST IN QUEUE; SET
IF ENTRY IS FIRST IN QUEUE •

• MACRO

QRETRY

OPCODE,OPERAND1,0PERAND2,SUCCESS,ERROR,?LOOP,
?OK

CLRL

OPCODE
.IF
BCC
.IFF
BCC
.ENDC
AOBLSS
.IF
BRW
.ENDC

OPERAND1,0PERAND2
NB
SUCCESS
SUCCESS

.ENDM

QRETRY

LOOP:

OK
#25,RO,LOOP
NB
ERROR
ERROR

OK:
ALLOCATE STORAGE FOR DATA STRUCTURES
.PSECT

DATA,QUAD

CMDBLK:
INPTQ:
TERMQ:
FREEQ:

COMMAND BLOCK
.BLKQ
.BLKQ
.BLKQ

1
1
1

INPUT QUEUE
TERMINATION QUEUE
FREE QUEUE

MSGPKT:
.BLKQ
.BYTE
.BYTE
.BYTE

1
12
0
XF$K PKT WRTCM

.BYTE

XF$K PKT NOINT@-

.BLKL
.BLKL
.BLKL

THIS PACKET SENDS A 12 BYTE
DEVICE MESSAGE
QUEUE LINKS
LENGTH OF DEVICE MESSAGE
LENGTH OF LOG AREA
COMMAND = WRITE CONTROL
MESSAGE
PACKET CONTROL
NO
INTERRUPT

XF$V PKT INTCTL
1

BYTE COUNT
BUFFER ADDRESS
RESIDUAL MEMORY AND DDI BYTE
COUNTS
DR32 STATUS LONGWORD
DEVICE MESSAGE
EXTEND DEVICE MESSAGE TO
QUADWORD LENGTH

1
2

.BLKL
.LONG
.LONG

1
11111,22222,33333

.ALIGN

QUAD

WRTPKT:

THIS PACKET DOES A WRITE
DEVICE

11-50

DR32 INTERFACE DRIVER
.BLKQ
.BYTE
.BYTE
.BYTE
.BYTE

1
4
0

XF$K PKT WRT
<XF$K PKT CBDMBC@-

XF$V PKT CISEL>!-

WDVMSG:

.LONG
.LONG
.BLKL

<XF$K PKT NOINT@XF$V PKT INTCTL>
1000WRTBFR
2

.BLKL
• BLKQ

1
1

.ALIGN

QUAD

.BLKQ
.BYTE
,BLKL

QUEUE LINKS
LENGTH OF DEVICE MESSAGE
LENGTH OF LOG AREA
COMMAND = WRITE
PACKET CONTROL = SEND
COMMAND BYTE,
DEVICE MESSAGE, AND BYTE
COUNT
AND NO INTERRUPT
BYTE COUNT
BUFFER ADDRESS
RESIDUAL MEMORY AND DDI BYTE
COUNTS
DR32 STATUS LONGWORD
SPACE FOR DEVICE MESSAGE

HLTPKT:
O,O,XF$K PKT HALT,O
5
-

THIS PACKET HALTS THE DR32
QUEUE LINKS
COMMAND = HALT
UNUSED FIELDS IN THIS PACKET

.ALIGN QUAD
PACKET FOR FREE QUEUE
QUEUE LINKS
LENGTH OF DEVICE MESSAGE
FIELD
UNUSED FIELDS IN THIS PACKET
DR32 STATUS LONGWORD
SPACE FOR DEVICE MESSAGE

FREPKT:
.BLKQ
.BYTE

.BLKL
.BLKL
.BLKQ

4
1
1

4,0,0,0

CMDBLKSIZ=.-CMDBLK
BUFFER BLOCK

BFRBLK:

WRTBFR:

• BLKB

1000

BFRBLKSIZ=.-BFRBLK
CMDTBL:

• LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.BYTE
.LONG

CMDBLKSIZ
CMDBLK
BFRBLKSIZ
BFRBLK
PKTAST
0

236,XF$M CMT SETRTE,O,O
GOBITADR-

COMMAND BLOCK SIZE
COMMAND BLOCK ADDRESS
BUFFER BLOCK SIZE
BUFFER BLOCK ADDRESS
PACKET AST ADDRESS
PACKET AST PARAMETER
DATA RATE (2.0 MBYTES/SEC)
ADDRESS TO STORE THE GO
BIT ADDRESS

GOBITADR:
.BLKL

XFIOSB:

I/O STATUS BLOCK

XFNAMEDSC:
.LONG
.LONG

XFNAMESIZ
XFNAME

NAME DESCRIPTOR

XFCHAN:

CHANNEL NUMBER

.BLKL

• BLKW

11-51

DR32 INTERFACE DRIVER
XFNAME: .ASCII /XFAO/
XFNAMESIZE=.-XFNAME

********************************************************************
PROGRAM STARTING PO'INT

********************************************************************
.PSECT

CODE,NOWRT

.ENTRY

DREXAMPLE,M<R2,R3>

$ASSIGN S DEVNAM = XFNAMEDSC,CHAN = XFCHAN
BLBS
R0,10$
BRW
ERROR
10$:

MOVAB
CLRQ
CLRQ
CLRQ

CMDBLK,R2
{R2)+
{R2)+
{R2)

ASSIGN A CHANNEL TO DR32
SUCCESSFUL ASSIGN

INITIALIZE INPTQ
INITIALIZE TERMQ
INITIALIZE FREEQ

INSERT COMMAND PACKET ONTO FREEQ FOR RETURN MESSAGE
QR ET RY
INSQTI

ERROR=BADQUEUE,FREPKT,FREEQ

START DEVICE
$QIO_S

FUNC

#IQ$_ STARTDATA, -

BLBC

CHAN = XFCHAN,IOSB = XFIOSB,EFN = #1,Pl = CMDTBL,P2 = #XF$K CMT LENGTH
RO,ERROR -

SEND MESSAGE TO FAR END DR-DEVICE
QRETRY ERROR=BADQUEUE,INSQTI MSGPKT,INPTQ
MOVL
#1,@GOBITADR
$WAITFR S #1

SET GO BIT
WAIT UNTIL QIO COMPLETES

CHECK FOR SUCCESSFUL COMPLETION
MOVZWL
BEQL

XFIOSB,RO
BADQUEUE

BLBC
RET

RO,ERROR

I/O NOT DONE YET - BAD QUEUE
ERROR IN AST ROUTINE
ERROR
SUCCESSFUL COMPLETION

11-52

DR32 INTERFACE DRIVER
BADQUEUE:
MOVZWL

#SS$_BADQUEUEHDR,RO

AN ERROR HAS OCCURRED. NORMALLY, THE USER MIGHT PERFORM MORE
EXTENSIVE ERROR CHECKING AT THIS POINT.
IN PARTICULAR, IF THE ERROR
IS SS$ CTRLERR, SS$ DEVREQERR, OR SS$ PARITY, THE SECOND LONGWORD
OF THE-I/O STATUS BLOCK CAN PROVIDE ADDITIONAL INFORMATION.
IN THIS
EXAMPLE, THE PROGRAM EXITS WITH THE ERROR STATUS IN RO.

ERROR:

RET

COMMAND PACKET AST ROUTINE
PKTAST: .WORD
NXTPKT: QRETRY
REMQHI
BVC
RET
10$:
BLBC
BBC

0
ERROR=70$,TERMQ,Rl
10$

GET NEXT PACKET FROM QUEUE

XF$L PKT DSL(Rl) ,50$
#XF$V PKT FREQPK,XF$L_PKT_DSL(Rl) ,50$

COMMAND PACKET OBTAINED FROM FREEQ.
WRITE PACKET.

50$:

MOVL
QRETRY
INS QT I
QRETRY
INSQTI
MOVL
RET

PACKET OBTAINED FROM QUEUE
QUEUE IS EMPTY
RETURN IF PACKET ERROR
RETURN IF PACKET NOT FROM
FREEQ
COPY DEVICE MESSAGE AND QUEUE

XF$B PKT DEVMSG(Rl) ,WDVMSG
ERROR=70$,WRTPKT, INPTQ
ERROR=70$,HLTPKT, INPTQ
#1,@GOBITADR
SET GO BIT

BAD QUEUE ERROR IN AST ROUTINE - WAKE UP MAIN LEVEL.
OR MAY NOT HAVE COMPLETED.
7 0$:

$SETEF S
RET
.END

QIO MAY

WAKE UP MAIN LEVEL

DREXAMPLE

11-53

CHAPTER 12
DUPll INTERFACE DRIVER

This chapter describes the use of the DUPll Device Interface driver.
The driver is category C software, which is not supported. The DUPll
is the lowest-level user interface to the VAX/VMS 2780/3780 Protocol
Emulator.
(The user can also access the 2780/3780 through the command
language interface and the record-oriented interface. See the VAX/VMS
2780/3780 Protocol Emulator User's Guide.)

12.1

SUPPORTED DEVICE

The DUPll is a single line, program-controlled communications device
that
interfaces
a
VAX-11 processor to a serial, synchronous
communications line. Data transmission occurs at a maximum speed of
9600
baud.
Although the DUPll functions in either full- or
half-duplex mode, the DUPll driver operates logically only
in
half-duplex mode; only one I/O request is processed at any given time
but many may be queued.
The DUPll driver transfers output data f rorn the VAX/VMS system to the
DUPll.
The DUPll then shifts the data onto the communications line.
Input data from the communications line modern is shifted into the
DUPll where it is made available to the DUPll driver on an interrupt
basis.

12.1.1

Driver Operating Modes

The device driver functions in two
operating
modes:
binary
synchronous communications (BSC) mode and binary mode. BSC mode
operations are described in Appendix C of the VAX/VMS 2780/3780
Protocol Emulator User's Guide. The preface of the same manual also
provides a list of related documents.
In BSC mode, the driver observes standard point-to-point BSC protocol
in send and receive operations. In binary mode, the driver does not
observe any protocol; the only operation performed on the data is the
insertion or deletion of PAD and SYN characters. An operation is
completed when the buffer count reaches zero or the I/O is cancelled.
Function modifiers, which are included in all read and write requests
to the driver, define the operating mode for each I/O operation.
If the only reason for not using the record-oriented interface is the
blocksize restriction (the application is compatible with all other
2780/3780 communications protocols), the DUPll driver should be used
primarily in BSC mode rather than binary mode. Binary mode is used
only if the user requires direct control of some aspect of the

12-1

DUPll INTERFACE DRIVER
communications protocol handled by the driver when in BSC mode. All
line protocol messages, for example, bids and sending EOTs, must be
transmitted in binary mode.

12.1.1.1 SSC Mode - If the IO$M PTPBSC function modifier is included
in a read or write QIO request~ data is read or written in BSC mode.
The DUPll driver performs the following operations:
1.

Inserts in the output data, and removes from the input data,
BSC data-link control characters, for example, STX and !TB.

Checks input message blocks for transmission errors.
Adds
cyclic redundancy check
(CRC) characters to output message
blocks to support error checking by the communications
processor in the remote system.

Manages line protocols, for example, ACK, NAK, and ENQ
responses, that determine whether a message block must be
retransmitted because of transmission errors.

Inserts in the output data, and removes from the input
DLE information in transparent mode.

data,

The DUPll driver does not modify the input or output data in any way.
All necessary processing, for example, data translation and space
compression or expansion, must be included in the user program.
The
user program builds the message block to be transmitted into a single
buffer. This buffer must start with a 2-byte count that includes all
data up to the point where a CRC will be placed, and end with a 2-byte
count field equal to -1. The driver inserts an ITB character in front
of internal CRC characters.
Figures 12-1 through 12-5 illustrate how the DUPll driver reformats
user-formatted output messag~ blocks into standard 2780/3780 message
blocks. The driver deblocks input messages in the reverse order of
that shown in these figures.
All COUNT and CRC fields in these examples are two bytes long.
Each
record count results in the generation of a CRC character. An !TB
character precedes all internal CRC characters. An ETB precedes the
last CRC in a block unless the IO$M LASTBLOCK function modifier is
specified. In that case, an ETX preced~s the CRC. If in transparency
mode
(specified by IO$ SETMODE), all data-link control characters are
preceded by a DLE character and all DLE characters in the data buffers
are changed to DLE DLE. Also, the control character sequence of SYN,
SYN, DLE, STX is inserted between records within the message block.
Message blocks transmitted by the DUPll driver include a prefix of SYN
characters (as specified by the set mode QIO) and a suffix of a PAD
character (hexadecimal FF).
Figure 12-1 shows the format of user-built message buffers that
simulate 3780 processing.
The user must pass the buffers to the
device driver by issuing QIO requests that include the IO$M PTPBSC
function modifier.
2-byte
count field

~-c_o_u_N_r_1~-RECORD1

l __

1R_s_~ ,- R::~rJ-1

'._Rs_ _ ·-R-E_c_o_R_o2___

Figure 12-1

3780 Message Block Example

12-2

DUPll INTERFACE DRIVER
The DUPll driver transmits the message block after modifying the
format, as shown in Figure 12-2. The driver does not modify the data
records in the two buffers; they are identical.

STX

RECOR01

IRS

Figure 12-2

RECOR02

IRS

RECOR03

ETB

CRC

3780 Message Block Example (Modified)

To simulate 2780 processing in nontransparent mode, the user builds
message buffers in the format shown in Figure 12-3. The user must
include the IO$M PTPBSC function modifier in the QIO requests that
pass the buffers-to the DUPll driver.
2-byte
count field
~

COUNT1

RECOR01

Figure 12-3

COUNT 2

RECOR02

COUNT3

RECOR01

-1

Nontransparent 2780 Message Block Example

The DUPll driver transmits the message
format, as shown in Figure 12-4.

STX

RECOR03

ITB

CRC

Figure 12-4

RECOR02

block

CRC

ITB

after

RECOR03

modifying

ETB

the

CRC

Nontransparent 2780 Message Block
Example (Modified)

To simulate 2780 processing in transparent mode, the user must specify
the transparency modifier in a set mode QIO request, build message
buffers in the format shown in Figure 12-3, and include
the
IO$M PTPBSC function modifier in the write QIO requests that pass the
buffers to the DUPll driver. The driver transmits the message block
after modifying the format, as shown in Figure 12-5. The driver adds
a duplicate DLE character to any DLE character encountered in the data
records.

OLE

STX

RECOR01

I I I I I
SYN

SYN

OLE

STX

OLE

ITB

RECOR03

Figure 12-5

CRC

SYN ·SYN

OLE

STX

RECOR02

I I I I
OLE

ETB

CRC

Transparent 2780 Message Block
Example (Modified)

12-3

OLE

ITB · CRC

DUPll INTERFACE DRIVER
12.1.1.2 Binary Mode - If the IO$M SRRUNOUT function modifier is
included in a read or write request, aata is read or written in binary
mode. In binary mode, the DUPll driver performs no processing
operations on the user-supplied message block buffer. Except for the
insertion in output message blocks, and deletion from input message
blocks, of leading SYN and trailing PAD characters, data passes
through the DUPll driver as unprocessed, binary information. The user
program directly controls all data transmitted or received by the
driver. QIO requests in the user program provide all necessary
communications to the remote system. The user program must perform
the following functions:
1.

Explicitly issue all protocol messages, for
NAK, and ENQ responses, to the DUPll driver.

Perform all validity checking calculations and comparisons.

Handle the insertion and removal of any message-framing
inter-record control characters in the message blocks.

Repeat write QIO requests until the operation
or the program's error threshold is reached.

12.2

example,

ACK,

and

successful

DEVICE INFORMATION

Users can obtain information on DUPll characteristics by using the
$GETCHN
and
$GETDEV system services (see Section 1.10).
The
DUPll-specific information is returned in the first three longwords of
a user-specified buffer, shown in Figure 12-6 (Figure 1-9 shows the
entire buffer).
16 15

a'1

device characteristics

device buffer size

(not used)
.•.

SYN

time

"_.......

line characteristics

______

character

Figure 12-6

DUPll Information

The first longword contains device-independent information.
second and third longwords contain device-dependent data.

The

Table 12-1 lists the device-independent
the first longword.

12-4

characteristics

returned

DUPll INTERFACE DRIVER

Table 12-1
Device-Independent Characteristics
Dynamic Bitsl
(Conditionally Set)

Meaning

XJ$M CHA FDX

Full-duplex line

XJ$M CHA XPR

Transparency mode

XJ$M CHA DSR

Data set ready

Static Bits2
(always Set)
DEV$M AVL

Device available

DEV$M IDV

Input device

DEV$M ODV

Output device

1. Defined by the $XJDEF macro.
2~

Defined by the $DEVDEF macro.

The second longword contains the device buffer size (default is 520
bytes). The third longword contains the line characteristics, the SYN
character, and the time, in seconds, to wait for clear to send (CTS).
The SYN character is that character selected to precede all message
blocks transmitted by the DUPll driver.
The line characteristics
returned in the third longword are:
•

XJ$M CHA DSC -- Sense state of data terminal
signal lTne. Meaningful only to IO$ SENSEMODE.

ready

(DTR)

•

XJ$M CHA FDX -- full duplex mode. Do not drop request to send
(RTS) after each segment is transmitted.

•

XJ$M CHA XPR -- transparent mode. Used only when
is specified with a write QIO function.

IO$M PTPBSC

The device buffer size and the third longword contents are established
by IO$_SETMODE (see Section 12.3.3).

12.3

DUPll FUNCTION CODES

The DUPll can perform logical and physical I/O
I/O functions are read, write, set mode, and
lists these functions and their function
paragraphs describe these functions in greater

12-5

operations. The basic
sense mode. Table 12-2
codes.
The following
detail.

DUPll INTERFACE DRIVER

Table 12-2
DUPll I/O Functions
-----.--·· ····-- .

Function Code and
Arguments

Type 1

Function

Function
Modifiers
-

IO$ READLBLK Pl,P2

IO$M SRRUNOUT
IO$M- PTPBSC

Read logical block

IO$ READPBLK Pl,P2

IO$M SRRUNOUT
IO$M- PTPBSC

Read physical
block

IO$ WRITELBLK Pl,P2

IOSM SRRUNOUT
IOSM- PTPBSC
IO$M-LASTBLOCK 2
-

Write logical
block

IO$ WRITEPBLK Pl,P2

IO$M SRRUNOUT
IOSM-PTPBSC
IO$M-LASTBLOCK 2

Write physical
block

IO$ SETMODE Pl

IOSM STARTUP
IO$M-NODSRWAIT 3
IO$M SHUTDOWN

Set line state or
line parameters

IO$ SENSEMODE

Sense line state;
return status

1. L = logical, P = physical
2. Use only with IO$M PTPBSC
3. Use only with IO$M STARTUP

12.3.l

Read

Read functions provide for the transfer of data from the DUPll into
the user process's virtual memory address space. VAX/VMS provides two
function codes:
•

IO$ READLBLK

read logical block

•

IO$ READPBLK

read physical block

The read function codes take two device/function-dependent arguments:
•

Pl = the starting virtual address of the
receive data

•

P2 = the size of the data buffer in bytes

buffer

that

(see

Section

The read QIO functions can take two function modifiers:
•

IO$M SRRUNOUT -- read
12.1:1.2).

data

•

IO$M PTPBSC -- read data in BSC mode (see Section 12.1.1.1).

12-n

binary

format

DUPll INTERFACE DRIVER
12.3.2

Write

Write functions provide for the transfer of data to the DUPll from the
user process's virtual memory address space. VAX/VMS provides two
function codes:
•

IO$ WRITELBLK

write logical block

IO$ WRITEPBLK

write physical block

The write function codes take two device/function-dependent arguments:
•

Pl = the starting virtual address of the
send data to the DUPll

•

buffer

that

(see

Section

= the size of the data buffer in bytes

The write QIO functions can take three function modifiers:
•

IO$M SRRUNOUT -- write data
12 • 1
2) •

•

IO$M PTPBSC

-:-i.

binary

format

write data in BSC mode (see Section 12.1.1.1).

IO$M LASTBLOCK -- terminate
• character.
This function

the data block with
modifier can be used

an
ETX
only in

conjunction with IO$M PTPBSC.

12.3.3

Set Mode

The set mode function is used to change the state of the communication
line or the parameters that control the line. VAX/VMS provides one
function code:
IO$ SETMODE
This function
argument:

code

takes

the

following

Pl = points to a quadword buffer
communication line parameters

device/function-dependent

block

that

contains

the

new

Figure 12-7 shows the format of the Pl buffer.

16 15

24 23

not used

block size

time

SYN
character

Figure 12-7

line characteristics

Set Mode Pl Buffer

In the first longword, blocksize is the largest buffer expected. This
parameter is included in the buffer block only when an IO$ READLBLK
request includes the IO$M PTPBSC function modifier.

12-7

DUPll INTERFACE DRIVER
The first word of the second longword
characteristics:

specifies

the

following

line

•

XJ$M CHA DSC -- sense state of data terminal
signal lTne. Meaningful only to IO$ SENSEMODE.

ready

(DTR)

•

XJSM CHA FDX -- full duplex mode. Do not drop request to send
(RTS) after each segment is transmitted.

•

XJ$M CHA XPR -- transparent mode.
Used only when
is specitied with a write QIO function.

IO$M PTPBSC

The third byte of the second longword is the SYN character that
precedes all message blocks transmitted by the DUPll driver. The
fourth byte specifies the time, in seconds, to wait for clear to send
(CTS).
This parameter is included in the buffer block only when a
read or write request specifies the IOSM_SRRUNOUT function modifier.
The Set Mode function can take three function modifiers:
•

IO$M STARTUP -- enable the communication line
(assert
terminal ready (DTR) and wait for data set ready (DSR).

•

IO$M NODSRWAIT -- complete this function without regard to the
state of DSR. Used only in conjunction with the IO$M STARTUP
function modifier.

•

IO$M SHUTDOWN -- disable the communication line (disable DTR)

12.3.4

data

Sense Mode

The sense mode function senses the current state of the communication
line and returns the line characteristics and status in the I/O status
block (see Figure 12-9). VAX/VMS provides one function code:
IO$ SENSEMODE

I/O STATUS BLOCK

12.4

Figure 12-8 shows the I/O status block far all DUPll QIO functions
except sense mode.
Figure 12-9 shows the I/O status block for the
sense mode function.
Table 12-3 lists the status returns far all
functions.
0

16 15

status

transfer size

device-dependent data

Figure 12-8

IOSB Content

12-8

DUPll INTERFACE DRIVER

24 23

16 15

not used

time

status

SYN
character

Figure 12-9

line characteristics

IOSB Content - Sense Mode

Table 12-3
DUPll Status Returns
Status

Meaning

SS$ ABORT

Request ·aborted. A request in progress was aborted
by the $CANCEL system service.

SS$ ACCVIO

Buffer access violation. An attempt was made to
read from or write to a location in memory that is
protected against the current mode.

SS$_EXQUOTA

Buffered I/O quota exceeded. A request cannot be
queued because the buffered I/O quota was exceeded.

SS$ INSFMEM

Insufficient dynamic
transfer request.

data

SS$ NORMAL

QIO transfer request completed successfully;
specified data was transferred.

the

memory

initiate

In Figure 12-8, the second word of the first longword contains the
size of the transfer in bytes. For transmit (write) operations, the
transfer size is the value specified in the P2 argument.
For read
(receive) operations, transfer size is the amount of data received as
the result of the read request. Table 12-4 lists the device-dependent
data returned in the second longword.
Table 12-4
Device-Dependent Status Returns
Value

Meaning

XJ$M BADCHAIN

A RECORD LIST was incorrectly found in a BSC
(I 0$M _PTPBSC) write request.
This is a fatal
error condition.

XJ$M_CONACK

A BSC (IO$M PTPBSC) write request was completed
with a conversational ACK character. The data
block is considered acknowledged. However, the
data received with the ACK character is lost.
(continued on next page)

12-9

DUPll INTERFACE DRIVER
Table 12-4 (Cont.)
Device-Dependent Status Returns

------

.------·----- ---...------·-····--·-·-----Value

---·-·-·

Meaning

XJ$M DATACK

Retry threshold exceeded.
condition.

XJ$M DISCON

BSC disconnect sequence received, that is,
EOT. This is a fatal error condition.

XJ$M EOT

EOT received.

XJ$M EXTEND

A BSC
(IO$M PTPBSC)
read request
completed
successfully.- The read data included a block
that ended with an EXT character.

XJ$M ILLMOD

Illegal QIO function modifier detected.
a fatal error condition.

XJ$M NODSR

Request aborted because of DSR loss.
fatal error condition.

XJ$M PIPE MARK

A BSC (IO$M_PTPBSC) transfer aborted because of
a previous failure.
This is a fatal error
condition.

XJ$M RVI

A BSC (IO$M PTPBSC) write request completed with
a received RVI.

XJ$M TRABINTMO

A
timeout
occurred
during
a
binary
(IO$M SRRUNOUT) data transfer. This is a fatal
error-condition.

XJ$M XPR

A BSC (IO$M PTPBSC) read request
with
a
transparent
block.
information
was
transmitted
transparency mode.

This is a fatal error
OLE,

This is a fatal error condition.

This is

was satisfied
The received
(written)
in

·---·----·--·· -··--------------'

In Figure 12-9, the first longword contains the current status of the
communication line.
Table 12-3 lists the status return values and
their meaning.
The first word of the second longword
following line characteristics:

returns

one

XJ$M CHA DSC

•

XJ$M CHA FDX
full duplex mode.
segment tranmitted.)

•

XJ$M CHA XPR -- transparent mode. Used only when
is s~eciiied with a write QIO function.

the

state of DTR line
(Do not drop RTS after each
IOSM PTPBSC

The third byte of the second longword is the SYN character selected to
precede all message blocks transmitted by the DUPll driver. The
fourth byte specifies the time, in seconds, to wait for clear to send
(CTS).
This parameter is included in the buffer block only when the
IO$M SRRUNOUT function modifier is specified in a read or write
request.

12-10

APPENDIX A
I/O FUNCTION CODES

This appendix lists the function codes and function modifiers defined
in the $IODEF macro.
The arguments for these functions are also
listed.

TERMINAL DRIVER

A.l

Function

Arguments

Modifier

IO$ READVBLK
IO$-READLBLK
10$-READPBLK
10$-READPROMPT
IO$-TTYREADALL
10$-TTYREADPALL

Pl
P2
P3
P4

- buffer address
- buffer size
- timeout
- read terminator
block address
PS - prompt string
buffer address 1
P6 - prompt string
buffer size 1

10$M NOECHO
10$M-CVTLOW 3
IO$M-NOFILTR 3
IO$M-TIMED
IO$M-PURGE
IO$M-DSABLMBX
IO$M-TRMNOECHO
IO$M-REFRESH

10$ WRITEVBLK
10$-WRITELBLK
!0$-WRITEPBLK

Pl
P2
P3
P4

10$M CANCTRLO
IO$M-ENABLMBX
10$M-NOFORMAT
10$M-REFRESH

10$ SETMODE
l0$=SETCHA.R

Pl - characteristics
buffer address
P3 - speed specifier
P4 - fill specifier
PS - parity flags

IO$ SETMODE!I0$M HANGUP
IO$-SETCHAR!IO$M-HANGUP

(none)

IO$ SETMODE!IO$M CTRLCAST
IO$-SETMODE!IO$M-CTRLYAST
IO$-SETCHAR!IO$M-CTRLCAST
IO$-SETCHAR!IO$M-CTRLYAST

Pl - AST service routine address
P2 - AST parameter
P3 - access mode to deliver AST

10$ SENSEMODE
!0$-SENSECHAR

Pl - Characteristics
buff er address

- buff er address
- buffer size
- (ignored)
- carriage control
specifier 2

IO$M TYPEAHDCNT

1. Pnly for IO$ READPROMPT and IO$ TTYREADPALL
2. Only for IO$_WRITELBLK and IO$_WRITEVBLK
3. Only for IO$_READLBLK,IO$_READVBLK, and IO$ READPROMPT

A-1

r/o FUNCTION CODES
A.2

DISK DRIVERS

Functions
IO$ READVBLK
IO$-READLBLK
IO$-READPBLK
IO$-WRITEVBLK
IO$-WRITELBLK
IO$-W'RITEPBLK

Arguments

Modifiers

Rl - buff er address
P2 - byte count
P3 - disk address

IO$M DATACHECK
IO$M-INHRETRY
IO$M-INHSEEK 1

IO$ WRITECHECK Pl - buff er address
P2 - byte count
P3 - disk address
IO$ SETMODE
IO$-SETCHAR

Pl - characteristic buffer
address

IO$ SENSECHAR
IO$-SENSEMODE
IO$-PACKACK
IO$-MOUNT

{none)

IO$ SEARCH

Pl -

IO$ SEEK

Pl - seek to specified cylinder

read/write head position

IO$ CREATE
Pl
IO$-ACCESS
P2
IO$-DEACCESS
IO$-MODIFY
P3
IO$-DELETE
IO$-ACPCONTROL P4

- FIB descriptor address
- file name string
address
- result string length
address
- result string descriptor
address
PS - attribute list address

IO$M CREATE 2
IO$M-ACCESS 2
IO$M-DELETE 3
IO$M-DMOUNT 4

1. Only for IO$ READPBLK and IO$ WRITEPBLK
2. Only for IO$ CREATE and IO$ ACCESS
3. Only for IO$ CREATE and IO$ DELETE
4. Only for IO$ ACPCONTROL

A.3

MAGNETIC TAPE DRIVERS

Functions
IO$ READVBLK
IO$-READLBLK
IO$-READPBLK
IO$-WRITEVBLK
IO$-WRITELBLK
!0$-WRITEPBLK

Modifiers

Arguments

IO$M DATACHECK 1
IO$M-INHRETRY
IO$M-REVERSE 2
IO$M-INHEXTGAP 3

Pl - buffer address
P2 - byte count

1. Not for TSll

2. Only for read functions
3. Only for write functions

A-2

I/O FUNCTION CODES
Modifiers

Functions

Arguments

IO$ SETMODE
IO$-SETCHAR

Pl - characteristics buffer
address

IO$ CREATE
Pl - FIB descriptor address
IO$-ACCESS
P2 - file name string
IO$-DEACCESS
address
IO$-MODIFY
P3 - result string length
IO$-ACPCONTROL
address
P4 - result string descriptor
address
PS - attribute list address

IO$M CREATE' 1
IO$M-ACCESS 1
IO$M-DMOUNT 2

IO$ SKIPFILE

IO$M INHRETRY

Pl - skip n tape marks

I 0$ M INHRETRY

IO$ SKIPRECORD Pl - skip n records
IO$ MOUNT

(none)

IO$ REWIND
IO$-REWINDOFF

(none)

IO$M INHRETRY
IO$M-NOWAIT

IO$ WRITEOF

(none)

IO$M INHEXTGAP
IO$M-INHRETRY

IO$ SENSEMODE

(none)

IO$M INHRETRY

1. Only for IO$ CREATE and IO$ ACCESS
2. Only for IO$ ACPCONTROL

A.4

LINE PRINTER DRIVER

Functions

Arguments

Modifiers

IO$ WRITEVBLK
IO$-WRITELBLK
IO$-WRITEPBLK

Pl
P2
P3
P4

IO$ SETMODE
IO$-SETCHAR

Pl - characteristics buffer
address

- buffer address
- buffer size
- (ignored)
- carriage control
specifier 1

(none)

lonly for IO$ WRITEVBLK and IO$ WRITELBLK

A.5

CARD READER DRIVER

Functions

Arguments

Modifiers

IO$ READLBLK
!0$-READVBLK
IO$-READPBLK

Pl - buffer address
P2 - byte count

IQ$M BINARY
IO$M-PACKED

IO$ SETMODE
IO$-SETCHAR

Pl - characteristics
buffer address

(none)

IO$ SENSEMODE

(none)

A-3

I/O FUNCTION CODES

MAILBOX DRIVER

A.6

Functions

Arguments

Modifiers

buffer address
buffer size

IO$M NOW

IO$ READVBLK
IO$-READLBLK
IO$-READPBLK
IO$-WRITEVBLK
IO$-WRITELBLK
IO$-WRITEPBLK

Pl P2 -

IO$ WRITEOF

(none)

IO$ SETMODE!IO$M READATTN
IO$-SETMODE!IO$M-WRTATTN

Pl - AST address
P2 - AST parameter
P3 - Access mode

A.7

DMCll DRIVER
Functions

Arguments

IO$ READLBLK
IO$-READPBLK
!0$-READVBLK
!0$-WRITELBLK
IO$-WRITEPBLK
!0$-WRITEVBLK

Pl - buffer address
P2 - message size

IO$ SETMODE
IO$-SETCHAR

Pl - characteristics
buffer address

IO$ SETMODE!IO$M ATTNAST
IO$-SETCHAR!IO$M-ATTNAST

Pl - AST service
routine address
P2 - (ignored)
P3 - AST access mode

IO$ SETMODE!IO$M SHUTDOWN
IO$-SETCHAR!IO$M-SHUTDOWN

Pl - characteristics
block address

IO$ SETMODE!IO$M STARTUP
IO$-SETCHAR!IO$M-STARTUP

Pl - characteristics
block address
P2 - (ignored)
P3 - receive message
blocks

1. Only for read functions
2. Only for IO$ WRITELBLK and IO$ WRITEPBLK

A-4

Modifiers
IO$M DSABLMBX 1
IOSM-Nowl
IO$M-ENABLMBX 2

I/O FUNCTION CODES
A.8

ACP INTERFACE DRIVER

Functions

Arguments

Modifiers

FIB descriptor address
file name string
address
P3 - result string length
address
P4 - result string descriptor
address
PS - attribute list address

IO$M CREATE!
IO$M-ACCESS 1
IO$M-DELETE 2
IO$M-DMOUNT 3

IO$ CREATE
!0$-ACCESS
IO$-DEACCESS
!0$-MODIFY
IO$-DELETE
IO$=ACPCONTROL

Pl P2 -

IO$ MOUNT

(none)

1. Only for IO$ CREATE and IO$ ACCESS
2. Only for IO$ CREATE and IO$ DELETE
3. Only for IO$ ACPCONTROL

A.9

LPAll-K DRIVER

Arguments

Modifier

IO$ LOADCODE

Pl - starting address of
microcode to be loaded
P2 - load byte count
P3 - starting microprogram
address to receive
microcode

(none)

IO$ STARTMPROC

(none)

IO$ INITIAL! ZE

Pl -

address of Initialize
Command 'f.able
P2 - initialize command
buff er length

(none)

SETCLOCK .

P2 - mode of operation
P3 - clock control and
status
P4 - real-time clock preset
value (2's complement)

(none)

IO$ STARTDATA

Pl - Data Transfer Command
Table address
P2 - Data Transfer Command
Table length
P3 - normal completion AST
address
P4 - overrun completion AST
address

IO$M SETEVF

QIO Functions

A-5

1/0 FUNCTION CODES
High Level Language
Subroutines
LPA$ADSWP
LPA$DASWP
LPA$DISWP
LPA$DOSWP
LPA$LAMSKS
LPA$SETADC
LPA$S.ETIBF
LPA$STPSWP
LPA$CLOCKA
LPA$CLOCKB
LPA$XRATE
LPA$IBFSTS
LPA$IGTBUF
LPA$INXTBF
LPA$IWTBUF
LPA$RLSBUF
LPA$RMVBUF
LPA$CVADF
LPA$FLT16
LPA$LOADMC

A.10

Functions
Start A/D converter sweep
Start D/A converter sweep
Start digital input sweep
Start digital output sweep
Specify LPAll-K controller and digital mask words
Specify channel select parameters
Specify buffer parameters
Stop sweep
Set Clock A rate
Set Closk B rate
Compute clock rate and present value
Return buff er status
Return next available buffer
Alter buffer order
Return next buffer or wait
Release buff er to LPAll-K
Remove buffer from device queue
Convert A/D input to floating point
Convert unsigned integer to floating point
Load microcode and initialize LPA-llK

DR32 DRIVER

QIO Functions

Arguments

IO$ LOADMCODE

Pl - Starting address
of microcode to
be loaded
P2 - load byte count

IO$ STARTDATA

Pl - starting address
of Data Transfer
Command Table
P2 - length of the
Data Transfer
Command Table

High Level Language
Subroutines

Function

XF$SETUP

Defines command and buffer areas;
initializes queues

XF$STARTDEV

Issues a QIO that starts the DR32

XF$FREESET

Releases command packets onto FREEQ

XF$PKTBLD

Builds command packets; releases
them onto INPTQ

A-n

Modifier

IO$M SETEVF

I/O FUNCTION CODES
XF$GETPKT

Removes a command packet from TERMQ

XF$CLEANUP

Deassigns the device channel and deallocates
the command area

A.11

DUPll DRIVER

Functions
IO$
IO$
IO$
IO$

READLBLK
READVBLK
WRITELBLK
WRITEVBLK

Arguments

Modifiers

Pl - buff er address
P2 - byte count

IO$M SRRUNOUT
IO$M PTPBSC
IO$M LASTBLOCK 1

IO$ SETMODE

Pl -

IO$M STARTUP
IO$M NODSRWAIT 2
IO$M SHUTDOWN

IO$ SENSEMODE

(none)

line parameters block

1. Only for write functions with IOSM PTPBSC
2. Use only with IO$M STARTUP

A-7

INDEX

A
Access, 1-3, 1-5, 1-14
file, 9-22, 9-23, A-2, A-5
ACP control function, 9-26, 9-27
ACP QIO functions, 9-19 to 9-31
arguments, 9-20 to 9-28
attributes, 9-15 to 9-17
modifiers for, 9-19 to 9-28
status returns, 9-32
Action routines, DR32, 11-35,
11-41
Allocate Device {$ALLOC} system
service, 1-14
Allocation of blocks, FIB, 9-7
ALTMODE, 2-5, 2-8
Analog-to-digital converter, 10-1
Ancillary Control Process (ACP},
1-5, 9-1
functions, 9-2
interface, 9-1
Arguments,
ACP device/function-dependent,
9-20, 9-21
AST address (astadr}, 1-18
AST parameter (astprm}, 1-18
bu ff er , 1-1 9
channel number, 1-15 to 1-17,
1-19, 1-24
device/function-dependent, 1-15,
1-16, 1-18, 2-14
device/function-independent,
1-15, 1-16
$INPUT, 1-19
$OUTPUT, 1-19
$QIO, 1-15 to 1-17
$QIOW, 1-16, 1-17
event flag number, 1-17, 1-19
function, 1-15 to 1-17, 1-18,
A-1
function-dependent, disks, 3-9
to 3-13
I/O status block (iosb}, 1-18,
1-19
keyword, 1-16
length, 1-19
position dependent, 1-15
$GETCHN, 1-24, 1-25
$GETDEV, 1-24 1-25
CALL instruction, 1-23
Assigning channels, 1-13
Assign I/O Channel ($ASSIGN}
system service, 1-13, 1-16,
1-17, 7-2, 8-2
AST,
address, 1-17
parameter arguments, 1-17, 1-18
quota, 1-4, 7-5
routine, 1-23

Asynchronous system trap, 1-22,
1-23
Attention AST,
enable, DMCll, 8-7, 8-8
read, mailbox, 7-7 to 7-9
write, mailbox, 7-7 to 7-9
Attribute Control Block,
explanation of, 9-14
fields, 9-15
f o r ma t , 9 -1 5
record attributes area, 9-17,
9-18
statistics block, 9-19
Attributes Statistics Block, ACP
QIO, 9-19

B
Beginning-of-tape {BOT}, 4-11
Binary mode, DUPll, 12-1, 12-4
Bits,
device/function-dependent, 1-13
device/function-independent,
1-13
Block-addressable devices, 1-7,
1-10
BSC mode, DUPll, 12-1, 12-2
Buffered I/O byte count quota,
1-4
Buffered I/O quota, 1-4, 7-5
Buffer overrun, 10-10, 10-11

c
CALL, 1-23
Card punch combinations, 6-2
Card reader,
device characteristics, 6-3 to
6-5
driver, 6-1
end-of-file, 6-2
error recovery, 6-2, 6-3
I/O functions, 6-5, 6-6
I/O status block, 6-8
read,
function, 6-2, 6-6
mode , 6 -1 , 6- 2
sense mode, 6-7, 6-8
set characteristics, 6-7, 6-8
set mode, 6-1, 6-2, 6-7, 6-8
status returns, 6-9
translation mode, 6-2
Carriage control,
line printer, 5-5 to 5-7
terminal, 2-18
Chaining, command and data, DR32,
11-3

Index-1

INDEX
Channel, 1-13, 1-14
assignments, 1-13
number argument, 1-15 to 1-17
Character
bit mask terminator, terminal,
2-16, 2-17
Character formatting, line printer,
5-2
Characteristics, (see Device characteristics)
Check,
close, 9-3
file identifier number, 9-34
file identifier sequence, 9-34
read, 9-4
write, 9-4
Command packets, DR32, 11-8
Completion status, 1-20, 1-22,
1-23
Console terminal, 2-1
Control characters, terminal,
2-2, 2-5 to 2-8
CTRL/C, 2-6, 2-23
CTRL/C AST, enable, 2-6, 2-23,
2-24
CTRL/G, 2-2
CTRL/I, 2-6
CTRL/J, 2-6
CTRL/K, 2-fi
CTRL/L, 2-6
CTRL/O, 2-6, 2-14
CTRL/Q, 2-2, 2-7, 2-12
CTRL/R, 2-7, 2-15
CTRL/S, 2-2, 2-6, 2-13
CTRL/U, 2-7, 2-14
CTRL/X, 2-7, 2-14
CTRL/Y, 2-7, 2-8, 2-23
CTRL/Y AST, enable, 2-7, 2-23,
2-24
CTRL/Z, 2-8
Create file, 9-21, 9-22
Create Mailbox and Assign Channel
($CREMBX) system service, 1-4,
1-17, 7-2
Cyclic Redundancy Check (CRC), 8-1

D
Data check,
disk, 3-3, 3-9, 3-10
magnetic tape, 4-3, 4-9, 4-10
Data overrun, 10-10
Data Set Ready (DSR) modem line,
DMCll, 8-5
Data Transfer Command Table, 10-10,
10-11, 11-21
Data Transfer Start Command, 10-10
Data Transfer Stop Command, 10-12,
10-13

DDI

(DR32 Device Interconnect),
11-1
Deaccess locked file, 9-33
Deaccess file, 9-19, 9-24, A-5
Deassign I/O Channel ($DASSGN)
system service, 2-24, 7-3
Dedicated mode, LPAll-K, 10-1
DELETE, 2-5, 2-8
Delete file, 9-25, 9-26, A-5
Delete Mailbox ($DELMBX) system
service, 7-3
Device allocation, 1-14
Device characteristics,
card reader, 6-3 to 6-5
disk, 3-5 to 3-7
DMCll, 8-3 to 8-6
DR32, 11-3
DUPll, 12-4
line printer, 5-3, 5-4
LPAll-K, 10-4 to 10-8
magnetic tape, 4-4, 4-5
mailbox, 7-4
terminal, 2-10 to 2-13
Device/function-dependent,
arguments, 1-18, 1-19
bits, 1-13
Device/function-independent,
arguments, 1-16, 1-17
bits, 1-13
Device information, 1-24, 1-25
Device queue (DVQ), LPAll-K, 10-14
Devices, 1-1, · 1-2
Dial-up, 2-9 2-13
DIGITAL Data Communications Message
Protocol (DDCMP), 8-1, 8-4
Digital-to-analog converter, 10-1
Direct I/O quota, 1-4, 8-3
Direct Memory Access (OMA), 8-1
Directory File, 9-5
Disk,
device characteristics, 3-5 to
3-7
devices, 3-1
device types, 3-7
drivers, 3-1
capabilities of, 3-2, 3-3
error recovery, 3-4 .
I/O function, 3-7 to 3-11, A-2
arguments, 3-9 to 3-11
interleaving, 3-4, 3-5
I/O status block, 3-14, 3-15
lock/unlock bits, 9-31
logical to physical translation,
3-4, 3-5
overlapped seeks, 3-3, 3-4
quota file, FIB, 9-7, 9-8, 9-27,
9-28 .
read function, 3-7 to 3-12
sense mode, 3-14
set characteristic, 3-13, 3-14

Index-2

INDEX
Disk, (Cont.)
set mode, 3-13
skew, 3-5
status,
block, 3-14, 3-15
returns, 3-15, 3-16
write function, 3-8, 3-12
DMCll,
device characteristics, 8-3 to
8-6
device types, 8-4
enable attention AST, 8-7, 8-8
error summary bits, 8-6
features of, 8-2
I/O functions, 8-6, 8-7, A-4
I/O status block, 8-10
mailbox usage, 8-2, 8-3
message size, 8-4
quotas, 8-3
read function, 8-6
set characteristics, 8-7
set mode, 8-7, 8-8
shut down unit, 8-9
start unit, 8-9
status returns, 8-10
synchronous communications line
interface driver, 8-1, 8-9
unit characteristics, 8-5
write function, 8-7
$CRDEF, 6-3, 6-7
$DCDEF, 2-11, 2-22, 2-25, 3-7,
4-5, 4-15, 5-4, 6-4
$DEVDEF, 3-6, 4-4, 5-3, 6-4,
7-4, 8-3, 10-5
$LADEF, 10-5, 10-6
$LPDEF, 5-4
$MSGDEF, 2-5, 8-2
$MTDEF, 4-5, 4-13
$SSDEF, 10-33
$TTDEF, 2-22, 2-25
$XMDEF, 8-4, 8-5
DSL (DR32 Status Longword), 11-17,
11-41
DR-device, DR32, 11-1, 11-3, 11-5,
11-7
DR32,
action routines, 11-35, 11-41
AST routines, 11-22, 11-34
buffer block, 11-5
command and data chaining, 11-3
command block, 11-5
command packets, 11-5, 11-6,
11-7, 11-8
AST routine, 11-22, 11-34
Pre-fetch, 11-40
contol (command) messages, 11-7
data transfers, 11-3, 11-5, 11-21
Data Transfer Command Table,
11-21
data rate, 11-22, 11-27

DR 3 2 , (Cont. )
device characteristics, 11-3
device control codes, 11-10
device-dependent IOSB returns,
11-38
diagnostic tests, 11-41
DR-device (definition), 11-1
DR32 Device Interconnect (DDI),
11-1
DR32 Status Longword (DSL),
11-17, 11-41
error checking, 11-41
event flags, 11-21, 11-34
far-end DR-device, 11-1, 11-3,
11-5, 11-7
free queue (FREEQ), 11-5, 11-6
GO bit, 11-7, 11-22
high-level language interface,
11-5, 11-23
synchronization, 11-34
input queue (INPTQ), 11-5, 11-fi
INSQTI instruction, 11-6
interrupts, 11-3, 11-15, 11-22,
11-42
I/O functions, 11-20
I/O status block, 11-36, 11-41
load microcode function (IO$
LOADMCODE), 11-20
microcode loader (XFLOADER),
11-19
programming hints, 11-40
programming interface, 11-5, 11-23
queue headers, 11-6
queue processing, 11-6
queue retry, 11-7, 11-41
random access, 11-3
REMQHI instruction, 11-6
start data transfer function
(IO$ STARTDATA), 11-5,
11-2I
status returns, 11-36, 11-41
termination queue (TERMQ),
11-5, 11-6
XF$CLEANUP, 11-33
XF$FREESET, 11-28
XF$GETPKT, 11-32
XF$PKTBLD, 11-29
XF$SETUP, 11-24
XF$STARTDEV, 11-26
DUPll I
binary mode, 12-1, 12-4
BSC mode, 12-1, 12-2
device characteristics, 12-4
full/half-duplex mode, 12-1
I/O functions, 12-5
I/O status block, 12-8
message blocks, 12-2, 12-3
message buffers, 12-2
nontransparent mode, 12-3
protocol, BSC, 12-1

Index-3

INDEX
DUPll, (Cont.)
transparent mode, 12-2, 12-3
VAX/VMS 2780/3780 Protocol
Emulator, 12-1
Duplex modes, terminal, 2-9
DZ-11 Asynchronous Serial Line
Multiplexer, 2-1, 2-9
DZ-11 Internal Modem Control, 2-1,
2-9

E
Eight-bit ASCII, 2-12
Enable attention AST,
DMCll I 8-7 I 8-8
mailbox, 7-8
Enable CTRL/C AST, 2-6, 2-23,
2-24
Enable CTRL/Y AST, 2-7, 2-23,
2-24
End-of-file,
card reader, 6-2, 6-9
message, mailbox, 7-7, 7-10
status, 4-10
End-of-tape status, 4-9, 4-10
Error Code Correctable (ECC),
disk, 3-3
Error recovery,
card reader, 6-2, 6-3
disk, 3-4
line printer, 5-2
magnetic tape, 4-3
Error,
severity level, 1-20
summary bits, DMCll, 8-6
ESCAPE, 2-5, 2-8
Escape sequences, 2-2, 2-3, 2-12
Event flag, 1-15, 1-22
number argument, 1-16, 1-17,
1-19

F
File Inf or mat ion Block (FIB) ,
3-9, 9-1 to 9-10
argument usage in QIO functions,
9-10 to 9-14
contents of, 9-3 to 9-10
field values, 9-3 to 9-14
format, 9-2
file name string, 9-20
Fill specifier, terminal, 2-22
Foreign volume, 1-10
FORM FEED (FF), 2-6
Form feeds, 2-18, 5-5
Full-duplex mode,
DUPll, 12-1
te rmi na ls, 2-9

Function
arguments, 1-15 to 1-17, A-1
code, 1-1, 1-12, A-1
modifier, 1-12, 1-13, 1-18, A-1
requests, 1-14
Function-dependent arguments, disk,
3-9 to 3-13
Function codes,
IO$ ACCESS, 3-8, 4-6, 9-12
IO$-ACPCONTROL, 3-8, 4-8, 9-14
IO$-CREATE, 1-12, 3-8, 4-6,
-9-10
IO$ DEACCESS, 3-8, 4-6, 9-12
IO$-DELETE, 3-8, 9-13
IO$-INITIALIZE, 10-6, 10-8
IO$-LOADMCODE, 10-6, 10-7,
-10-33, 11-20
IO$ MODIFY, 3-8, 4-6, 9-12
IO$-MOUNT, 3-8, 4-8, 9-14
IO$-PACKACK, 3-9, 3-14
IO$-READLBLK, 1-12, 2-14,
-2-15, 3-8, 3-10, 3-11, 4-7,
6-5, 6-6, 7-5, 8-6
IO$ READPBLK, 1-12, 2-14, 3-8,
-3-10, 3-11, 4-7, 6-5, 6-6,
7-5, 8-6
IO$ READPROMPT, 2-7, 2-14,
-2-15
IO$ READVBLK, 1-12, 2-14, 2-15,
-3-8, 3-10, 3-11, 4-7, 6-5,
6-6, 7-5, 8-6
IO$ REWIND, 4-7
IO$-REWINDOFF, 4-7
IO$-SEARCH, 3-9, 3-11
IO$-SEEK, 3-9, 3-11
IO$-SENSECHAR, 2-24, 3-9
IO$-SENSEMODE, 2-24, 3-9, 3-14,
-4-8, 4-12, 5-8, 6-5
IO$ SETCHAR, 2-7, 2-13, 2-22,
-3-9, 3-11, 4-8, 4-14, 5-8,
6-5 f o-8 I 8-7
IO$ SETCLOCK, 10-7
IO$-SETMODE, 2-7, 2-13, 2-22,
-3-9, 3-11, 4-8, 4-13, 5-8,
6-5, 6-7, 7-7, 8-6
IO$ SKIPFILE, 4-7, 4-11
IO$-SKIPRECORD, 4-7
IO$-STARTDATA, 10-10, 11-5,
-11-21
IO$ STARTMPROC, 10-8
IO$-TTYREADALL, 2-14
IO$-TTYREADPALL, 2-14
IO$-WRITECHECK, 3-9, 3-10
IO$-WRITELBLK, 1-12, 3-8, 3-10
-3-12, 4-7, 5-4, 7-6, 8-7
IO$ WRITEOF, 4-7, 4-12, 7-7
IO$-WRITEPBLK, 1-12, 3-9, 3-10
-3-12, 4-7, 5-4, 7-n, 8-7
IO$ WRITEVBLK, 1-12, 3-8, 3-10,
-3-12, 4-7, 5-4, 7-6, 8-7

Index-4

INDEX
Function modifiers,
IO$M ACCESS, 1-13
IO$M-ATTNAST, 8-8
IO$M-BINARY, 6-1, 6-5, 6-6
IO$M-CANCTRLO, 2-6, 2-18
IO$M-CTRLCAST, 2-23
IO$M-CTRLYAST, 2-7, 2-23
IO$M-CVTLOW, 2-2, 2-15
IO$M-DATACHECK, 1-13, 3-3, 3-12,
4-3, 4-7
IO$M DMOUNT, 4-8, 9-27
IO$M-DSABLMBX, 2-12, 2-15
IO$M-ENABLMBX, 2-12, 2-18, 8-7
IO$M-HANGUP, 2-23
IO$M-INHERLOG, 1-7
IO$M-INHEXTGAP, 4-4, 4-7
IO$M-INHRETRY, 1-13, 3-4, 3-12,
4-3, 4-7
IO$M INHSEEK, 3-3
IO$M-NOECHO, 1-12, 2-2, 2-15
IO$M-NOFILTR, 2-16
IO$M-NOFORMAT, 2-12, 2-18
IO$M-NOW, 7-5, 8-6
IO$M-NOWAIT, 4-7, 4-12
IO$M-PACKED, 6-1, 6-5, 6-6
IO$M-PURGE, 2-15, 2-16
IO$M-READATTN, 7-7
IO$M-REFRESH, 2-16, 2-18
IO$M-REVERSE, 4-7
IO$M-SETEVF, 10-10, 11-21
IO$M-SHUTDOWN, 8-9
IO$M-STARTUP, 8-9
IO$M-TIMED, 2-16
IO$M-TRMNOECHO, 2-16
IO$M-TYPEAHDCNT, 2-25
IO$M-WRTATTN, 7-7
free queue (FREEQ), DR32, 11-5,
11-6

Holdscreen mode, 2-12
Host/terminal synchronization,
2-12

I
Information,
device, 1-24, 1-25
device-dependent, 1-25
Initialize Command Table, 10-9
Input/Output operations, 1-1
Input queue(INPTQ) ,DR32, 11-5,
11-6
Interleaving, disk, 3-4, 3-5
In-use queue (IUQ),LPAll-K, 10-14
I/O completion, 1-21
I/O function,
arguments, 1-15 to 1-17, A-1
code, 1-1, 1-12, A-1
modifier, 1-12, 1-13, 1-18, A-1
requests, 1-14
I/O Functions,
card reader, 6-5, 6-6, A-3
disk, 3-7 to 3-11, A-2
DMCll, 8-6, 8-7, A-4
DR32, 11-20
DUPll, 12-5
line printer, 5-4 to 5-8, A-3
LPAll-K, 10-7 to 10-12, A-5
magnetic tape, 4-5 to 4-9, A-2
mailbox, 7-5 to 7-9, A-4
terminal, 2-13, 2-25, 2-26, A-1
I/O operations, 1-6
logical, 1-7
physical, 1-7
virtual, 1-7, 1-10
I/O quota,
buffered, 1-4, 7-5
byte count, 1-4
direct, 1-4, 8-3
I/O requests, 1-1, 1-13, 1-15,

1-lfi
Get Channel Information ($GETCHN)
system service, 1-24, 2-10,
IOSB, 1-22
3-5, 4-4, 5-3, 6-3, 7-4, 8-3, I/O status block, 1-17, 1-21, 1-22
10-4
argument, 1-18
Get Device Information ($GETDEV)
I/O status,
system service, 1-24, 2-10, 3-5,
ACP QIO interface, 9-31 to 9-35
4-4, 5-3, 6-3, 7-4, 8-3, 10-4
card reader, 6-8, 6-9
GO bit, DR32, 11-7, 11-22
disk devices, 3-14 to 3-16
DMCll, 8-10
DR32, 11-36
DUPll, 12-8
line printer, 5-9
Half-duplex mode,
LPAll-K, 10-32 to 10-35
DUPll, 12-1
magnetic tape devices, 4-15
terminals, 2-9
mailbox, 7-9
Hang-up,
terminal, 2-25
modifier, 2-23
I/O status returns, 1-20, 1-21
terminal, 2-5, 2-9, 2-13
I/O system services, 1-2, 1-10

Index-5

INDEX

K
Keyword arguments,

1~16

L
Laboratory Peripheral Accelerator,
LPAll-K, 10-1
LINE FEED, 2-5
Line feeds, 2-18
Line printer,
carriage control, 5-5 to 5-7
character formatting, 5-2
device characteristics, 5-3, 5-4
driver, 5-1
error recovery, 5-2
I/O functions, 5-4 to 5-8, A-3,
A-5
I/O status block, 5-9
sense printer mode, 5-8
set characteristics, 5-8
set mode, 5-8
status returns, 5-9
types, 5-1
write function, 5-4, 5-5
Li n e , remote , 2- 5 , 2- 9 , 2-13
Line terminators, 2-2
Logical Block Number (LBN), 9-9
Logical I/O,
operations, 1-7
privilege, 1-5, 1-6
Logical name, 1-14
Logical to physical translation,
RXOl, 3-4
Lowercase, characters, 2-12, 2-17,
5-2, 5-4
LPAll-K,
AST addresses, 10-10, 10-12
buffer overrun, 10-10, 10-11
buffer queue control, 10-14,
10-15
data acquisition devices, 10-4
Data Transfer Command Table,
10-10' 10-11
Data Transfer Start Command,
10-10
Data Transfer Stop Command,
10-12, 10-13
device characteristics, 10-4
to 10-8
device configurations, 10-2
device initialization routines,
10-4, 10-36
driver, 10-1, 10-3
errors, 10-2
high-level language support
routines, 10-3, 10-13
I/O functions, 10-7 to 10-12
I/O status block, 10-32
Initialize Command Table, 10-9

LPAll-K, (Cont.)
initialize function, 10-8
load microcode function, 10-5,
10-7
Maintenance Status Register,
10-33
microcode loading routines,
10-4, 10-36
modes of operation, 10-2
Random Channel List (RCL), 10-12
Ready-out Register, 10-33
Request Descriptor Array (RDA),
10-18
RSX-llM differences, 10-37,
10-38
set clock function, 10-7,
10-9
set event flag modifier, 10-10,
10-12
start data transfer request
function, 10-10, 10-11
start microprocessor function,
10-8
status returns, 10-33 to 10-35
subroutines,
LPA$ADSWP, 10-18
LPA$CLOCKA, 10-24
LPA$CLOCKB, 10-25
LPA$CVADF, 10-31
LPA$DASWP, 10-19
LPA$DISWP, 10-20
LPA$DOSWP, 10-21
LPA$FLP16, 10-31
LPA$FLT16, 10-31
LPA$IBFSTS, 10-27
LPA$IGTBUF, 10-27
LPA$INXTBF, 10-28
LPA$IWTBUF, 10-29
LPA$LAMSKS, 10-22
LPA$LOADER, 10-36
LPA$LOADMC, 10-32
LPA$RLSBUF, 10-30
LPA$RMVBUF, 10-30
LPA$SETADC, 10-22
LPA$SETIBF, 10-23
LPA$STPSWP, 10-24
LPA$XRATE, 10-26
subroutine arguments, 10-14 to
10-18
supporting software, 10-3

M
Magnetic tape,
data check, 4-3, 4-9, 4-10
device characteristics, 4-4,
4-5
device types, 4-1
driver, 4-2

Index-6

INDEX

Magnetic tape, (Cont.)
error recovery, 4-3
file, 9-3
I/O functions, 4-5 to 4-9, A-2,
A-3
I/O status block, 4-15
master adapters, 4-2
read function, 4-9, 4-10
rewind, 4-11, 4-12
sense mode, 4-12
set characteristics, 4-13 to
4-15
set mode, 4-13, 4-14
skip function, 4-11, 4-12
slave formatters, 4-2
Magnetic tape,
status returns, 4-15 to 4-17
write function, 4-10, 4-11
Mailbox,
creation of, 1-14, 7-2
deletion of, 7-3
device characteristics, 7-4
driver, 7-1, A-4
explanation of, 7-1, 7-2
I/O functions, 7-5 to 7-9, A-4
I/O status block, 7-9
message format, 2-5, 7-3, 7-4
protection, 1-5
QIO requests,
read, 7-5, 7-n
write, 7-6, 7-7
read attention AST, 7-7 to 7-9
set attention AST, 7-7 to 7-9
status returns, 7-9, 7-10
terminal, 2-4, 2-5
usage,
DMCll, 8-2, 8-3
LPAllK, 10-32, 10-36
write attention AST, 7-7 to
7-9
write end-of-file message, 7-7,
7-10
Master adapter, magnetic tape,
4-2
Mechanical,
form feed, 2-12, 5-4
tabs, 2-13
Message,
format, mailbox, 2-5, 7-3, 7-4
size, DMCll, 8-4
control, DR32, 11-7
Modem control, 2-1, 2-9
Modify file, 9-24, 9-25, A-5
MOUNT, 1-14
Mount,
privilege, 1-5
virtual I/O function, 9-26
Mounted,
foreign 1-7, 1-10, 3-12
structured, 3-11, 3-12

Multirequest mode, LPAll-K, 10-1,
10-2

N
Name string, 9-5
NULL, 2-16

0
Offset, 1-26
recovery, 3-3
Overlapped seeks, disk, 3-3, 3-4

p
Pack acknowledge, 3-14
Page,
length, 2-11
width, 2-11
Parity flags, terminal, 2-23
PASSALL, 2-5, 2-13, 2-15
Physical,
device name, 1-14
I/O operation, 1-7
I/O privilege, 1-4 to 1-7
Printer, (see Line Printer)
Privilege, 1-3
logical I/O, 1-5, 1-6
mount, 1-5
physical I/O, 1-4 to 1-7
Prompt buffer, terminal, 2-14
Protection, 1-3, 1-5, 1-6
mask, 1-5 to 1-7, 1-10
protocol,
DDCMP, 8-1, 8-4
BSC, DUPll, 12-1

Q
QIO

arguments, 1-15 to 1-17
macro, 1-15 to 1-17
QIOW

arguments, 1-16, 1-17
macro, 1-16, 1-17
Queue I/O (QIO),
interface to ACPs, 9-1
macro, 1-15
operations, 1-6
system service ($QIO), 1-1,
1-13, 1-14
Queue processing, DR32, 11-6
Quota file transfer block, disk,
9-28

Index-7

INDEX

Quotas, 1-3, 3-7, 4-6, 7-5, 8-3,
disk, 9-27 to 9-31

Set attention AST,
DMCll, 8-8
mailbox, 7-7 to 7-9
Set characteristics,
card reader, 6-7, 6-8
R
disk devices, 3-13, 3-14
Random Channel List (RCL), 10-12
DMCll, 8-7
Read,
line printer, 5-8
access, 9-30
magnetic tape devices, 4-13 to
attention AST, 7-7 to 7-9
4-15
binary, card reader, 6-1, 6-6
terminal, 2-15, 2-22
checking, 9-4
Set mode,
function codes, 2-14
card reader, 6-1, 6-2, 6-7, 6-8
mailbox QIO requests, 7-5, 7-6
disk devices, 3-13
packed Hollerith, card reader,
DMCll, 8-7, 8-8
DUPll, 12-6, 12-7
6-1, 6-6
line printer, 5-8
with prompt, 2-14
magnetic tape devices, 4-13, 4-14
with timeout, 2-14
QIO function, 1-6, 1-12
Read Event Flags ($READEF) system
terminal, 2-15, 2-22
service, 1-17
Set Resource Wait Mode ($SETRWM)
Read function,
system service, 1-3, 1-4, 1-21
card reader, 6-2, 6-6
Set terminal command, 2-11
disk devices, 3-7 to 3-12
Severity level error, 1-20
DMCll, 8-6
Shut down unit, DMCll, 8-9
DUPll, 12-6
Skew disk, 3-5
magnetic tape devices, 4-9, 4-10
Skip, magnetic tape,
mailbox, 7-5 to 7-9
file, 4-11
terminal, 2-9, 2-14
record, 4-12
Read QIO function, 1-6
Slave formatter, magnetic tapes, 4-2
Receive buffer free list, DMCll,
Software channels, 1-1
8-3, 8-10
Speed specifier, terminal, 2-22
Receive-message blocks, DMCll,
Spooled device characteristics, 1-24
8-9, 8-10
Start unit, DMCll, 8-9
Record attributes area, ACP QIO,
9-17
Statistics block, ACP QIO Attributes,
9-19
Record Management Services (RMS),
1-1
Status block, I/O, 1-17, 1-21, 1-22,
Record-oriented devices, 1-7, 1-10
argument, 1-18
Relative Volume Number (RVN), 9-5,
Status codes,
9-9
SHR$ HALTED, 11-33
Remote line, 2-5, 2-9, 2-13
SHR$-NOCMDMEM, 11-31, 11-33,
Requests, I/O, 1-1, 1-13, 1-15, 1-16
Tl-34
RESET button, card reader, 6-3
SHR$ QEMPTY, 11-33
Resource wait mode, 1-3, 7-2, 10-3
SS$ ABORT, 1-21, 2-9, 2-26,
RETURN, 2-5
-5-9, 8-10, 10-12, 10-33, 11-36
Rewind offline, 4-12
SS$ ACCONFLICT, 9-30, 9-32
SS$-ACCVIO, 1-20, 1-21, 1-26, 7-10
RSX-llM Version 3.1, differences
SS$-ACPVAFUL, 9-32
with VAX/VMS LPAll-K, 10-37,
SS$-BADATTRIB, 9-32
10-38
SS$-BADCHKSUM, 9-32
SS$-BADESCAPE, 2-3, 2-26
SS$-BADFILEHDR, 9-32
SS$-BADFILENAME, 9-32
Seek capability, 3-2, 3-3
SS$-BADFILEVER, 9-32
Sense mode,
SS$-BADIRECTORY, 9-32
card reader, 6-7, 6-8
SS$-BADPARAM, 9-29, 9-32, ll-3n
disk, 3-14
SS$-BADQFILE, 9-29, 9-33
DUPll, 12-6
SS$-BADQUEHDR, 11-37
tape, 4-12
SS$-BLOCKCNTERR, 9-33
terminal, 2-24
SS$=BUFFEROVF, 1-26

Index-8

INDEX

Status codes, (Cont.)
SS$ BUFNOTALIGN, 10-9, 10-33,
-11-37
SS$ CANCEL, 10-9, 10-33, 11-37
SS$-CONTROLC, 2-6, 2-26
SS$-CONTROLO, 2-6, 2-26
SS$-CONTROLY, 2-6, 2-8, 2-27
SS$-CREATED, 9-33
SS$-CTRLERR, 3-12, 3-15, 4-15,
-10-2, 10-8, 10-28, 10-33,
11-37
SS$ DATACHECK, 3-16, 4-15, 10-8,
-10-34
SS$ DATAOVERUN, 4-17, 6-9, 8-10
SS$-DEVACTIVE, 8-10, 10-8, 10-34,
-11-37
SS$ DEVCMDERR, 10-2, 10-9, 10-28,
-10-34
SS$ DEVFOREIGN, 1-10
SS$-DEVICEFULL, 9-33
SS$-DEVNOTMOUNT, 1-10
SS$-DEVOFFLINE, 8-10
SS$-DEVREQERR, 10-2, 10-28,
-10-34, 11-37
SS$ DIRFULL, 9-33
SS$-DRVERR, 3-12, 3-16, 4-16
SS$-DUPDSKQUOTA, 9-29, 9-33
SS$-DUPFILENAME, 9-33
SS$-ENDOFFILE, 4-16, 6-9, 7-10,
-8-10, 9-33
SS$ ENDOFTAPE, 4-16
SS$-ENDOFVOLUME, 4-16
SS$-EXQUOTA, 1-21, 10-12, 10-34,
-11-37
SS$ FCPREADERR, 9-29, 9-33
SS$-FCPREWINDERR, 9-33
SS$-FCPSPACERR, 9-33
SS$-FCPWRITERR, 9-33
SS$-FILELOCKED, 9-33
SS$-FILENUMCHK, 9-34
SS$-FILESEQCHK, 9-34
SS$-FILESTRUCT, 9-34
SS$-FILNOTEXP, 9-34
SS$-FORMAT, 3-16, 4-16
SS$-HEADERFULL, 9-34
SS$-IDXFILEFULL, 9-34
SS$-ILLCNTRFUNC, 9-34
SS$-ILLEFC, 1-21
SS$-ILLSER, 1-21
SS$-INBUFLEN, 3-16
SS$-INCLENGTH, 10-9
SS$-INSFARG, 1-21
SS$-INSFBUFDP, 10-12, 10-34
SS$-INSFMAPREG, 10-9, 10-12,
-10-34
SS$ INSFMEM, 1-21, 7-10, 10-12,
-10-34, 11-37
SS$ IVADDR, 3-16
SS$-IVBUFLEN, 10-35, 11-38
SS$=IVCHAN, 1-21, 1-26

Status codes, (Cont.)
SS$ IVMODE, 10-9, 10-35
SS$-MBFULL, 7-10
SS$-MBTOOSML, 7-10
SS$-MCNOTVALID, 10-8, 10-12,
-10-35, 11-38
SS$ MEDOFL, 3-12, 3-16, 4-16
SS$-NODISKQUOTA, 9-34
SS$-NOMOREFILES, 9-34
SS$-NONEXDRV, 1-22, 3-12, 3-16,
-4-16
SS$ NOPRIV, 1-7, 1-10, 1-21, 1-26,
-7-10, 9-29, 9-34
SS$ NOQFILE, 9-29, 9-34
SS$-NORMAL, 1-20, 1-21, 1-26,
-2-16, 2-27, 3-12, 3-15, 4-15,
5-9, 6-9, 7-10, 8-10, 11-38
SS$ NOSUCHFILE, 9-34
SS$-NOTAPEOP, 9-34
SS$-NOTLABELMT, 9-34
SS$-OVRDSKQUOTA, 9-30, 9-35
SS$-PARITY, 2-27, 3-16, 4-17,
-10-12, 10-35, 11-38
SS$ PARTESCAPE, 2-3, 2-27
SS$-POWERFAIL, 10-8, 10-12,
-10-35, 11-38
SS$ QFACTIVE, 9-35
SS$-QFNOTACT, 9-29, 9-35
SS$-SUPERSEDE, 9-35
SS$-TAPEPOSLOST, 9-35
SS$-TIMEOUT, 2-16, 2-27, 10-8,
-10-35
SS$ TOOMANYVER, 9-35
SS$-UNASEFC, 1-21
SS$-UNSAFE, 3-17, 4-17
SS$-VOLINV, 3-17, 4-17
SS$-WASECC, 3-17
SS$-WRITLCK, 3-17, 4-17
SS$-WRTLCK, 9-35
Status completion, 1-20, 1-22,
1-23
Status returns,
ACP QIO interface, 9-31 to
9-35
card reader, 6-9
disk devices, 3-15, 3-16
DMCll, 8-10
DUPll, 12-8
I/O, 1-20, 1-21
line printer, 5-9
LPAll-K, 10-33 to 10-35
magnetic tape devices, 4-15 to
4-17
mailbox, 7-9, 7-10
system services, 1-20
terminal, 2-26, 2-27
System services,
$ALLOC, 1-14
$ASSIGN, 1-13, 1-16, 1-17, 7-2,
8-2

Index 9

INDEX

System services, (Cont.)
$CANCEL, 2-24, 2~2~, 10-7,
10-12, 10-33
$CREMBX, 1-14, 1-17, 7-2
$DASSGN, 2-24, 7-3
$DELMBX, 7-3
$GETCHN, 1-24, 2-10, 3-5, 4-4,
5-3, 6-3, 7-4, 8-3, 10-4
$GETDEV, 1-24, 2-10, 3-5, 4-4,
5-3, 6-3, 7-4, 8-3, 10-4
$INPUT, 1-19
$OUTPUT, 1~19
$QIO, 1-1, 1-14 to 1-16
$QIOW, 1-15 to 1-17
$READEF, 1-17
$SETRWM, 1-3, 1-4, 1-21
$WAITFR, 1-15 to 1-17
$WFLAND, 1-1 7
$WFLOR, 1-1 7
System services,
I/O, 1-2, 1-10
status returns, 1-20, 1-21

Terminator set, 2-16
Transfer count, 1-22
Translation, logical to physical,
RXOl, 3-4
Translation mode, card reader, 6-2
Transparent mode, DUPll, 12-2, 12-3
Truncate operations, FIB, 9-3, 9-7
Type-ahead, 2-1, 2-4, 2-13, 2-15,
2-25

u
Unsolicited data, 2-4
Uppercase, characters, 2-12, 2-17,
5-2, 5-4
User queue (USQ}, LPAll-K, 10-14
User Status Word (USW}, 10-10

v
VAX-11 Record Management Services
(RMS) , 1-1
VAX/VMS System Services Reference
Manual, 1-3
Version,
name, 9-20
type, 9-20
Vertical tab, 2-6
Virtual Block Number (VBN), 9-8
Virtual I/O operation, 1-7, 1-10
Volume protection, 1-5
VTlOO User's Guide, 2-4

TAB, 2-6
Tabs, 2-6, 2-13, 2-18
Tape, (see Magnetic tape)
Terminal,
carriage c?ntrol, 2-18
characteristics, 2-2, 2-10
to 2-13'
control characters, 2-2, 2-5
to 2-8
driver, 2-1
enable CTRL/C AST, 2~6, 2-23,
2-24
Wait for Single Event Flag ($WAITFR}
enable CTRL/Y AST, 2-7, 2-23,
system service, 1-15 to 1-17
2-24
Wild card,
function modifiers, 2-15
bits for disk quota file, 9-8
hang-up, 2-5, 2-9
Write,
hang-up function modifier, 2-23
access, FIB, 9-3, 9-8, 9-30
I/O functions, 2-13, A-1
attention AST, mailbox, 7-7 to
I/O status block, 2-25
7-9
mailbox, 2-24, 2-5
checking, 9-4
read function, 2-9, 2-10, 2-14
mailbox QIO requests, 7-5 to 7-7
read terminator set, 2-16,
QIO function, 1-6
sense mode, 2-24
set characteristic, 2-22
Write End-of-File,
magnetic tape, 4-12
set mode, 2-22
special keys, 2-8
message, mailbox, 7-7, 7-10
status returns, 2-26, 2-27
Write function,
write function, 2-9
disk, 3-8, 3-12
2-10, 2-17
DMCll, 8-7
Terminal/host synchronization, 2-12
DUPll, 12-7
line printer, 5-4, 5-5
Termination queue (TERMQ}, DR32,
11-5, 11-11
magnetic tape, 4-10, 4-11
Terminator character bit mask,
mailbox, 7-6 to 7-9
2-16, 2-17
terminal, 2-9 , 2-17

Index-10

INDEX

z
026 code, card reader, 6-2
029 code, card reader, 6-2

Index-11

VAX/VMS
I/O User's Guide
AA-D028B-TE
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 •

c
0

Did you find errors in this manual?
page number.

If so, specify the error and the

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify)~~~~~~~~~~~~~~~~~~~

CitY--------------------~------State _____________ Zip

Code _____________
or
Country

DoNotTear-FoldHereandTape -

II
I

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS TW/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876

No Postage
Necessary
if Mailed in the
United States