OpenVMS I/O Users Reference

Manual
Order Number: AAPV6SETK
June 2002
This manual contains the information necessary to interface directly
with the I/O device drivers supplied as part of the Compaq OpenVMS
Operating System. Several examples of programming techniques are
included. This document does not contain information on I/O operations
using the OpenVMS Record Management Services.

Revision/Update Information:

This manual supersedes the OpenVMS

I/O Users Reference Manual, Version
7.3

Software Version:

OpenVMS Alpha Version 7.3-1

OpenVMS VAX Version 7.3

Compaq Computer Corporation

Houston, Texas

 2002 Compaq Information Technologies Group, L.P.

COMPAQ, the Compaq logo, Alpha, OpenVMS, Tru64, VAX, VMS, and the DIGITAL logo are
trademarks of Compaq Information Technologies Group, L.P., in the U.S. and/or other countries.
Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft
Corporation in the U.S. and/or other countries.
Intel, Intel Inside, and Pentium are trademarks of Intel Corporation in the U.S. and/or other
countries.
Motif, OSF/1, and UNIX are trademarks of The Open Group in the U.S. and/or other countries.
All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government
under vendors standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The
information in this document is provided "as is" without warranty of any kind and is subject
to change without notice. The warranties for Compaq products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed as
constituting an additional warranty.
ZK6136
The Compaq OpenVMS documentation set is available on CD-ROM.

This document was prepared using DECdocument, Version 3.3-1b.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xix

1 ACPQIO Interface
1.1
1.2
1.3
1.3.1
1.3.1.1
1.3.1.2
1.3.1.3
1.3.2
1.3.2.1
1.3.2.2
1.3.3
1.3.3.1
1.3.3.2
1.3.4
1.3.4.1
1.3.4.2
1.3.5
1.3.5.1
1.3.5.2
1.4
1.5
1.6
1.6.1
1.6.1.1
1.6.1.2
1.6.1.3
1.6.1.4
1.6.2
1.6.2.1
1.6.2.2
1.6.3
1.6.3.1
1.6.3.2
1.6.4
1.6.4.1
1.6.4.2
1.6.5
1.6.5.1

ACP Functions and Encoding . . . . . . . .

File Information Block (FIB) . . . . . . . .
ACP Subfunctions . . . . . . . . . . . . . . . .
Directory Lookup . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Directory Entry Protection . . . .
Access . . . . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Extend . . . . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Truncate . . . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Read/Write Attributes . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Attribute Descriptions . . . . . . .
ACP-QIO Record Attributes Area . . . . .
ACPQIO Attributes Statistics Block . .
Major Functions . . . . . . . . . . . . . . . . . .
Create File . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Disk ACP Operation . . . . . . . . .
Directory Entry Creation . . . . .
Magnetic Tape ACP Operation .
Access File . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Deaccess File . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Modify File . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .
Delete File . . . . . . . . . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

12
13
16
17
17
18
19
110
110
111
111
111
113
113
113
113
114
114
119
121
122
124
125
125
126
127
127
127
128
128
129
129
129
129
130
130
130
131

iii

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

131
131
132
134
135
135
135
136
136
137
139

2.1
Supported Disk Devices and Controllers . . . . . . . . . . . . . . . . . .
2.1.1
UDA50 UNIBUS Disk Adapter . . . . . . . . . . . . . . . . . . . . . .
2.1.2
KDA50 Disk Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.3
KDB50 Disk Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.4
HSC40, HSC50, and HSC70 Controllers . . . . . . . . . . . . . . .
2.1.5
SII Integral Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.6
KFQSA Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.7
RQDX3 Disk Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.8
RA70 and RA90 Disk Drives . . . . . . . . . . . . . . . . . . . . . . . .
2.1.9
RA60 Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.10
RA80/RB80/RM80 and RA81 Fixed-Media Disks . . . . . . . . .
2.1.11
RB02 and RL02 Cartridge Disk (VAX Only) . . . . . . . . . . . . .
2.1.12
RC25 Disk (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.13
RD53 and RD54 Disks (VAX Only) . . . . . . . . . . . . . . . . . . . .
2.1.14
RF30 and RF71 Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.15
RK06 and RK07 Cartridge Disks (VAX Only) . . . . . . . . . . .
2.1.16
RM03 and RM05 Pack Disks (VAX Only) . . . . . . . . . . . . . . .
2.1.17
RP05 and RP06 Disk (VAX Only) . . . . . . . . . . . . . . . . . . . . .
2.1.18
RP07 Fixed-Media Disk (VAX Only) . . . . . . . . . . . . . . . . . . .
2.1.19
RRD40 and RRD50 Read-Only Memory (CD-ROM) . . . . . . .
2.1.20
RX01 Console Disk (VAX Only) . . . . . . . . . . . . . . . . . . . . . .
2.1.21
RX02 Disk (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.22
RX23 (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.23
RX33 (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.24
RX50 (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.25
RZ22, RZ23, and RZ55 Disks . . . . . . . . . . . . . . . . . . . . . . . .
2.1.26
TU58 Magnetic Tape (DECtape II) . . . . . . . . . . . . . . . . . . . .
2.2
Driver Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1
Dual-Pathed Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2
Dual Porting MASSBUS Disks . . . . . . . . . . . . . . . . . . . . . .
2.2.2.1
Port Selection and Access Modes . . . . . . . . . . . . . . . . . .
2.2.2.2
Disk Use and Restrictions . . . . . . . . . . . . . . . . . . . . . . .
2.2.2.3
Restriction on Dual-Ported Non-DSA Disks in a Cluster
2.2.3
Dual-Pathed DSA Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.4
Dual-Porting HSC Disks . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.5
Dual-Pathed RF-Series Disks . . . . . . . . . . . . . . . . . . . . . . . .
2.2.6
Data Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.7
Effects of a Failure During an I/O Write Operation . . . . . . .
2.2.8
Overlapped Seeks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

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

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

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

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

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

21
21
22
22
22
23
23
23
23
23
24
24
24
24
25
25
25
25
25
25
26
26
27
27
27
27
27
28
28
29
29
210
210
211
211
211
212
213
213

1.6.6
1.6.6.1
1.6.6.2
1.6.6.3
1.6.7
1.6.8
1.6.8.1
1.6.8.2
1.6.8.3
1.6.8.4
1.7
I/O

Movefile Subfunction . . . . . . . . . . . . . . . .
Calling the Movefile Subfunction . . . .
Input Parameters . . . . . . . . . . . . . . . .
Operation . . . . . . . . . . . . . . . . . . . . . .
Mount . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACP Control . . . . . . . . . . . . . . . . . . . . . . .
Input Parameters . . . . . . . . . . . . . . . .
Magnetic Tape Control Functions . . .
Miscellaneous Disk Control Functions
Disk Quotas . . . . . . . . . . . . . . . . . . . .
Status Block . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

2 Disk Drivers

iv

Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Skip Sectoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logical-to-Physical Translation (RX01 and RX02) . . . . . . . . . . . . . .
DIGITAL Storage Architecture (DSA) Devices . . . . . . . . . . . . . . . . .
Bad Block Replacement and Forced Errors for DSA Disks . . . . .
VAXstation 2000 and MicroVAX 2000 Disk Driver . . . . . . . . . . . . . .
SCSI Disk Class Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audio Extensions to the SCSI Disk Class Driver . . . . . . . . . . . . . . .
$QIO Interface to Audio Functionality of the SCSI Disk Class
Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.14.2
Defining an Audio Control Block (AUCB) . . . . . . . . . . . . . . . . .
2.2.14.3
Error Handling in Applications Using SCSI Audio Functions . .
2.2.14.4
Using CD-ROM to Store Both Data and Audio Information . . . .
2.2.14.5
Programming Audio Applications . . . . . . . . . . . . . . . . . . . . . . . .
2.2.14.6
Application Program Example Using SCSI Audio Capabilities
(VAX only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3
Disk Driver Device Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4
Disk Function Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.1
Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.2
Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.3
Sense Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.4
Set Density . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.5
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.6
Pack Acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.7
Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.8
Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.9
Seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.10
Write Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11
Set Preferred Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11.1
Forcing a Path Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11.2
Using IO$_SETPRFPATH with Disks Dual-Pathed Between
HSCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11.3
Using IO$_SETPRFPATH with Disks Dual-Pathed Between
Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11.4
Using IO$_SETPRFPATH with Disks Accessed Through MSCP
Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.11.5
Using IO$_SETPRFPATH with Phase I Volume Shadowing . . .
2.4.11.6
Using IO$_SETPRFPATH with Phase II Volume Shadowing . . .
2.5
I/O Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6
Disk Driver Programming Example . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.9
2.2.9.1
2.2.10
2.2.11
2.2.11.1
2.2.12
2.2.13
2.2.14
2.2.14.1

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

214
214
215
216
217
218
218
219

.
.
.
.
.

.
.
.
.
.

220
220
223
225
226

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

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

226
226
228
233
234
235
235
235
236
236
236
236
236
237
238

..

238

..

239

.
.
.
.
.

.
.
.
.
.

239
239
239
239
240

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

31
31
31
31
31
32
32
32
32
32
33

3 Magnetic Tape Drivers

3.1
Magnetic Tape Controllers and Drives . . . . . . . . . . . . . . . . .
3.1.1
TM03 Magnetic Tape Controller (VAX Only) . . . . . . . . .
3.1.2
TS11 Magnetic Tape Controller (VAX Only) . . . . . . . . . .
3.1.3
TM78 and TM79 Magnetic Tape Controllers (VAX Only)
3.1.4
TU80 Magnetic Tape Subsystem (VAX Only) . . . . . . . . .
3.1.5
TA81 Magnetic Tape Subsystem . . . . . . . . . . . . . . . . . .
3.1.6
TU81 Magnetic Tape Subsystem (VAX Only) . . . . . . . . .
3.1.7
TU81-Plus Magnetic Tape Subsystem (VAX Only) . . . . .
3.1.8
TA90 Magnetic Tape Subsystem . . . . . . . . . . . . . . . . . .
3.1.9
RV20 Write-Once Optical Drive (VAX Only) . . . . . . . . . .
3.1.10
TK50 Cartridge Tape System (VAX Only) . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

3.1.11
3.1.12
3.1.13
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.2.7
3.3
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.5.1
3.4.6
3.4.7
3.4.8
3.4.9
3.4.10
3.4.11
3.4.12
3.4.13
3.4.14
3.4.15
3.4.16
3.5
3.6

TK70 Cartridge Tape System (VAX Only) . . . . . . . . . . . . . . . . . .

TZ30 Cartridge Tape System . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read and Write Compatibility Between Cartridge Tape Systems .
Driver Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dual-Path HSC Tape Drives . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dynamic Failover and Mount Verification . . . . . . . . . . . . . . . . . .
Tape Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Master Adapters and Slave Formatters . . . . . . . . . . . . . . . . . . . .
Data Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Streaming Tape Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Driver Device Information . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Function Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rewind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Skip File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Skip Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logical End-of-Volume (EOV) Detection . . . . . . . . . . . . . . . . .
Write End-of-File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rewind Offline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sense Tape Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Tape Density Support (Alpha Only) . . . . . . . . . . . . . . . .
Data Security Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pack Acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
I/O Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Driver Programming Examples . . . . . . . . . . . . . . . . .

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

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

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

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

33
33
33
34
35
35
35
36
36
37
37
38
310
314
316
316
317
318
318
319
319
319
319
320
323
324
324
325
325
325
325
326

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

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

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

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

41
41
43
44
44
44
45
45
49
411
411
414
414
415
415
417

4 Mailbox Driver
4.1
4.1.1
4.1.2
4.1.3
4.1.4
4.2
4.3
4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.3.7
4.4
4.5

vi

Mailbox Operations . . . . . . . . . . . . . . . .
Creating Mailboxes . . . . . . . . . . . . .
Deleting Mailboxes . . . . . . . . . . . . . .
Mailbox Message Format . . . . . . . . .
Mailbox Protection . . . . . . . . . . . . . .
Mailbox Driver Device Information . . . .
Mailbox Function Codes . . . . . . . . . . . . .
Read . . . . . . . . . . . . . . . . . . . . . . . . .
Write . . . . . . . . . . . . . . . . . . . . . . . .
Write End-of-File Message . . . . . . . .
Set Attention AST . . . . . . . . . . . . . .
Wait for Writer/Reader . . . . . . . . . . .
Set Protection . . . . . . . . . . . . . . . . .
Get Mailbox Information . . . . . . . . .
I/O Status Block . . . . . . . . . . . . . . . . . . .
Mailbox Driver Programming Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5 Terminal Driver
5.1
5.2
5.2.1
5.2.1.1
5.2.1.2
5.2.1.3
5.2.1.4
5.2.1.5
5.2.1.6
5.2.1.7
5.2.2
5.2.2.1
5.2.2.2
5.2.2.3
5.2.3
5.2.3.1
5.2.3.2
5.2.3.3
5.2.4
5.2.5
5.2.6
5.3
5.3.1
5.4
5.4.1
5.4.1.1
5.4.1.2
5.4.1.3
5.4.1.4
5.4.2
5.4.2.1
5.4.2.2
5.4.3
5.4.3.1
5.4.3.2
5.4.3.3
5.4.3.4
5.4.3.5
5.4.3.6
5.4.4
5.4.4.1
5.4.4.2
5.4.4.3
5.4.4.4
5.4.4.5
5.4.4.6
5.4.4.7
5.4.4.8
5.4.4.9
5.4.5
5.4.5.1
5.4.5.2
5.4.5.3

Supported Terminal Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Terminal Driver Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command-Line Editing and Command Recall . . . . . . . . . . . . .
Control Characters and Special Keys . . . . . . . . . . . . . . . . . . . .
Read Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Escape and Control Sequences . . . . . . . . . . . . . . . . . . . . . . . . .
Type-Ahead Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Line Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Duplex Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting of Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET HOST Facility and Output Buffering . . . . . . . . . . . . . . . .
Dialup Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modem Signal Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hangup on Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preservation of a Process Across Hangups . . . . . . . . . . . . . . . .
Terminal/Mailbox Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Autobaud Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Out-of-Band Control Character Handling . . . . . . . . . . . . . . . . . . .
Terminal Driver Device Information . . . . . . . . . . . . . . . . . . . . . . . . . .
Terminal Characteristics Categories . . . . . . . . . . . . . . . . . . . . . . .
Terminal Function Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Modifier Codes for Read QIO Functions . . . . . . . . . .
Read Function Terminators . . . . . . . . . . . . . . . . . . . . . . . . . . .
Itemlist Read Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read Verify Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Modifier Codes for Write QIO Functions . . . . . . . . . .
Write Function Carriage Control . . . . . . . . . . . . . . . . . . . . . . .
Set Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hangup Function Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enable Ctrl/C AST and Enable Ctrl/Y AST Function Modifiers
Set Modem Function Modifier . . . . . . . . . . . . . . . . . . . . . . . . .
Loopback Function Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enable Out-of-Band AST Function Modifier . . . . . . . . . . . . . . .
Broadcast Function Modifier . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT Port Driver QIO Interface . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT Port Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT Port Driver Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and Configuring LAT Entities . . . . . . . . . . . . . . . . . .
Obtaining Information About LAT Entities . . . . . . . . . . . . . . .
Programming Application Ports . . . . . . . . . . . . . . . . . . . . . . . .
Programming Application Services and Dedicated Ports . . . . .
Programming Forward Ports . . . . . . . . . . . . . . . . . . . . . . . . . .
Queue Change Notification (Alpha Only) . . . . . . . . . . . . . . . . .
Hangup Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sense Mode and Sense Characteristics . . . . . . . . . . . . . . . . . . . . .
Type-ahead Count Function Modifier . . . . . . . . . . . . . . . . . . . .
Read Modem Function Modifier . . . . . . . . . . . . . . . . . . . . . . . .
Broadcast Function Modifier . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

51
52
53
53
54
57
57
59
510
510
510
510
511
511
513
513
517
517
518
519
520
520
526
527
528
529
530
531
537
538
539
539
541
545
545
546
548
549
550
550
551
552
552
560
575
577
577
578
579
579
580
580
582
vii

5.5
5.6

I/O Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Terminal Driver Programming Examples . . . . . . . . . . . . . . . . . . . . . . . . . .

582
586

6 Pseudoterminal Driver
6.1
6.1.1
6.1.2
6.1.3
6.2
6.3
6.4
6.5
6.5.1
6.5.2
6.5.3
6.5.4
6.5.5
6.5.5.1
6.5.5.2
6.5.5.3
6.5.5.4
6.5.5.5
6.5.5.6
6.6
6.6.1

Pseudoterminal Operations . . . . . . . . . . . . . . .
Creating a Pseudoterminal . . . . . . . . . . . .
Canceling a Request . . . . . . . . . . . . . . . . . .
Deleting a Pseudoterminal . . . . . . . . . . . . .
Pseudoterminal Driver Features . . . . . . . . . . .
Pseudoterminal Driver Device Information . . .
I/O Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pseudoterminal Functions . . . . . . . . . . . . . . . .
Reading Data . . . . . . . . . . . . . . . . . . . . . . .
Writing Data . . . . . . . . . . . . . . . . . . . . . . .
Using Write with Echo . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . .
Event Notification . . . . . . . . . . . . . . . . . . .
Input Flow Control . . . . . . . . . . . . . . . .
Output Stop . . . . . . . . . . . . . . . . . . . . .
Output Resume . . . . . . . . . . . . . . . . . .
Characteristics Changed . . . . . . . . . . .
Output Abort . . . . . . . . . . . . . . . . . . . .
Terminal Driver Read Events . . . . . . . .
Pseudoterminal Driver Programming Example
Design Overview . . . . . . . . . . . . . . . . . . . .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

61
61
62
62
63
63
63
64
64
65
65
65
66
66
66
66
66
66
67
67
67

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

71
72
72
72
72
73
74

Overview of SCSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OpenVMS SCSI Class/Port Architecture . . . . . . . . . . . . . . . . . . . .
Overview of the OpenVMS Generic SCSI Class Driver . . . . . . . . .
Accessing the OpenVMS Generic SCSI Class Driver . . . . . . . . . . .
SCSI Port Features Under Application Control . . . . . . . . . . . . . . .
Setting the Data Transfer Mode . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Disconnection and Reselection . . . . . . . . . . . . . . . . .
Disabling Command Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Command Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring a Device Using the Generic Class Driver . . . . . . . . . .
Disabling the Autoconfiguration of a SCSI Device (VAX Only) .
Assigning a Channel to GKDRIVER . . . . . . . . . . . . . . . . . . . . . . .
Issuing a $QIO Request to the Generic Class Driver . . . . . . . . . . .
Generic SCSI Class Driver Device Information . . . . . . . . . . . . . . .
Call a Generic SCSI Class Driver . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

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

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

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

81
82
83
84
86
86
87
87
88
88
89
89
810
813
814

7 Shadow-Set Virtual Unit Driver

7.1
7.2
7.2.1
7.2.2
7.3
7.3.1
7.4

Introduction . . . . . . . . . . . . . . . . . . . . . . .
Configurations . . . . . . . . . . . . . . . . . . . . .
Supported Hardware . . . . . . . . . . . . .
Compatible Disk Drives and Volumes
Driver Functions . . . . . . . . . . . . . . . . . . .
Read and Write Functions . . . . . . . . .
Error Processing . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

8 Using the OpenVMS Generic SCSI Class Driver

8.1
8.2
8.3
8.4
8.5
8.5.1
8.5.2
8.5.3
8.5.4
8.6
8.6.1
8.7
8.8
8.9
8.10

viii

9 Local Area Network (LAN) Device Drivers

9.1
9.2
9.2.1
9.2.2
9.2.3
9.3
9.4
9.4.1
9.4.2
9.5
9.6
9.6.1
9.6.2
9.6.3
9.6.4
9.6.5
9.6.6
9.6.7
9.6.8
9.6.9
9.6.10
9.6.11
9.7
9.7.1
9.7.2
9.7.3
9.7.4
9.7.4.1
9.7.4.2
9.7.4.3
9.7.4.4
9.7.4.5
9.7.5
9.7.6
9.7.7
9.8
9.9
9.10
9.10.1
9.10.2
9.10.3
9.11
9.11.1
9.11.2
9.11.3
9.11.4
9.12
9.12.1
9.13
9.13.1
9.13.2
9.13.3
9.13.4

Local Area Network (LAN) Terminology . . . . . . . . . . . . . . . . . . . . . . . . . .

Supported Communication Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OpenVMS VAX LAN Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OpenVMS Alpha LAN Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Industry Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAN Controller Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fast Ethernet LAN Devices (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . .
Fast Ethernet NICDE500 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fast Ethernet NICDE600 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Gigabit Ethernet LAN Devices (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . .
Gigabit Ethernet NICDEGPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGPA Internal Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Medium Access Control (MAC) Counter Statistics . . . . . . . . . . . . . . . .
Interface Counter Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Host Commands Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interrupt Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DMA Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ring Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal MAC Receive Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal MAC Transmit Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Gigabit Ethernet NICDEGXA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGXA Internal Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Statistics Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Statistics: Receive MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Statistics: Transmit MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Statistics: Receive List Placement State Machine . . . . . . . . . . . . .
Statistics: Send Data Initiator State Machine . . . . . . . . . . . . . . . .
Statistics: Host Coalescing State Machine . . . . . . . . . . . . . . . . . . .
Fork Delay Debug Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Driver Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Device-Specific Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FDDI LAN Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TMS380 Token LAN Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAN ATM Network Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAN Emulation over an ATM Network . . . . . . . . . . . . . . . . . . . . . . . .
LAN Emulation Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Classical IP Over an ATM Network . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supporting and Configuring LAN Emulation over ATM . . . . . . . . . . . . . . .
Specifying the User to Network Interface (UNI) . . . . . . . . . . . . . . . . .
Enabling SONET/SDH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring an Emulated LAN (ELAN) . . . . . . . . . . . . . . . . . . . . . . . .
Ports and LAN Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Driver Initialization and Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ethernet Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format of Ethernet Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ethernet Address Classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting an Ethernet Physical Address . . . . . . . . . . . . . . . . . . . . . . . .
Ethernet Physical and Multicast Address Values . . . . . . . . . . . . . . . . .

91
91
92
92
94
95
96
96
97
97
98
98
98
911
912
915
917
917
918
918
919
921
921
922
922
925
926
926
927
928
929
929
930
930
931
932
932
932
933
934
934
935
935
936
936
936
937
938
939
939
939
940
940
ix

9.13.5
Token Ring Functional Address Mapping . . . . . . . . . . . . . . . . . . . . . . .
9.14
Configuring ISA Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.14.1
OpenVMS LAN Devices Requiring Configuration . . . . . . . . . . . . . . . .
9.14.1.1
DE203 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.14.1.2
DW110 Token Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.15
Configuring the Ethernet Media Type from the Console . . . . . . . . . . . . . .
9.16
Frame Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.1
CSMA/CD Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.2
FDDI Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.3
Token Ring Frames (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.4
ATM ELAN Frames (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.5
802.2/802.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.16.6
Token Ring Source Routing Header (Alpha Only) . . . . . . . . . . . . . . . .
9.17
Format Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18
Features of Packet Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.1
Ethernet Packet Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.1.1
Ethernet Protocol Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.1.2
Ethernet Packet Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.1.3
Protocol Type Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.2
IEEE 802 Packet Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.2.1
Class I Service Packet Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.2.2
User-Supplied Service Header Format . . . . . . . . . . . . . . . . . . . . . .
9.18.2.3
Service Access Point (SAP) Use and Restrictions . . . . . . . . . . . . . .
9.18.3
IEEE 802 Extended Packet Format . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.18.3.1
Protocol Type PID Sharing (Alpha Only) . . . . . . . . . . . . . . . . . . . .
9.19
LAN Device Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20
LAN Function Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.1
Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.2
Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3
Set Mode and Set Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3.1
Set Controller Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3.2
Set Mode Parameters for Packet Formats . . . . . . . . . . . . . . . . . . .
9.20.3.3
Set Mode Parameter Validation . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3.4
Shutdown Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3.5
Enable Attention AST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.3.6
IO$M_SET_MAC Functional Modifier to IO$M_SETMODE . . . . .
9.20.3.7
IO$M_UPDATE_MAP Functional Modifier to IO$_SETMODE . . .
9.20.3.8
IO$M_ROUTE Functional Modifier to IO$_SETMODE . . . . . . . . .
9.20.4
Sense Mode and Sense Characteristics . . . . . . . . . . . . . . . . . . . . . . . .
9.20.4.1
IO$M_SENSE_MAC Functional Modifier to
IO$_SENSEMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.20.4.2
IO$M_SHOW_MAP Functional Modifier to IO$_SENSMODE . . . .
9.20.4.3
IO$M_SHOW_ROUTE Functional Modifier to
IO$_SENSEMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.21
I/O Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.22
Application Programming Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.22.1
Promiscuous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.22.2
Local Area Network Programming Examples . . . . . . . . . . . . . . . . . . .
9.23
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

941
943
943
943
944
944
945
946
948
948
948
949
950
950
953
954
954
954
955
956
956
957
958
958
959
960
961
962
966
968
969
979
980
981
981
982
984
986
987
989
991
991
993
994
994
994
9101

10 Optional Features for Improving I/O Performance

10.1
Fast I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.1
Fast I/O Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.2
Using Buffer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.3
Differences Between Fast I/O Services and $QIO . . . . . . . . . . . . . . . .
10.1.4
Using Fast I/O Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.1
Using Fandles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.2
Modifying Existing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.3
I/O Status Area (IOSA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.4
$IO_SETUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.5
$IO_PERFORM[W] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.6
$IO_CLEANUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.4.7
Fast I/O FDT Routine (ACP_STD$FASTIO_BLOCK) . . . . . . . . . . .
10.1.5
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2
Fast Path (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.1
Fast Path Features and Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.2
Using Fast Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.2.1
Fast Path System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.2.2
Identifying and Setting a Ports Preferred CPU . . . . . . . . . . . . . . .
10.2.3
Fast Path Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.4
Special Considerations for Fast Path on Multi-RAD Systems . . . . . . .

101
102
102
103
104
104
105
105
106
106
106
106
107
107
108
109
109
1010
1012
1013

A I/O Function Codes

A.1
A.2
A.3
A.4
A.5
A.6
A.7
A.8

ACP-QIO Interface Driver . . . . . . . . . . .

Disk Drivers . . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Drivers . . . . . . . . . . . . . .
Mailbox Driver . . . . . . . . . . . . . . . . . . . .
Terminal Driver . . . . . . . . . . . . . . . . . . .
Local Area Network Device Drivers . . . .
Fast I/O Function Codes and Modifiers .
Fast Path Function Codes and Modifiers

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

A1
A2
A3
A5
A6
A8
A8
A9

DEC Multinational Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Terminal Sequences and Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C1
C9

B IO$_DIAGNOSE Function for SCSI Class Drivers

C Tables
C.1
C.2

D Control Connection Routines

PTD$CANCEL . . . . . . . . . . . . . . . . .
PTD$CREATE . . . . . . . . . . . . . . . . .
PTD$DELETE . . . . . . . . . . . . . . . . .
PTD$READ . . . . . . . . . . . . . . . . . . .
PTD$READW . . . . . . . . . . . . . . . . . .
PTD$SET_EVENT_NOTIFICATION
PTD$WRITE . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

D2
D3
D6
D7
D9
D10
D13

xi

Index
Examples
21
31
32
33
34
41
42
43
51
52
53
54
61
81
91
92
93
94

DISK_DRIVER.MAR Disk Driver Programming Example . . . . . . . .

Defining the P1 Parameter in a IO$_SKIPRECORD QIO . . . . . . . .
Device Characteristic Program Example . . . . . . . . . . . . . . . . . . . . .
Set Mode and Sense Mode Program Example . . . . . . . . . . . . . . . . .
MAGNETIC_TAPE.MAR Device Characteristic Program Example .
Mailbox Driver Program Example 1 . . . . . . . . . . . . . . . . . . . . . . . . .
Mailbox Driver Program Example 2 . . . . . . . . . . . . . . . . . . . . . . . . .
Mailbox Driver Program Example 3 . . . . . . . . . . . . . . . . . . . . . . . . .
LAT.C Terminal Driver Programming Example . . . . . . . . . . . . . . . .
FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
READ_VERIFY.MAR Terminal Driver Programming Example . . . .
LIB$XXABLE_CTRL.C Terminal Driver Programming Example . . .
Sample Pseudocode for Pseudoterminal Driver Program . . . . . . . . .
Generic SCSI Class Driver Call Example . . . . . . . . . . . . . . . . . . . . .
Using the isacfg at Console Prompt with the DE203 . . . . . . . . . . .
Using the isacfg at Console Prompt with the DW110 . . . . . . . . . . .
LANETH.MAR Local Area Network Programming Example . . . . . .
LAN802.C Local Area Network Programming Example . . . . . . . . . .

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

240
314
326
327
328
418
420
422
586

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

5100
5109
5113
68
814
944
944
995
998

ACP Device- or Function-Dependent Arguments . . . . . . . . . . . . . . . . .

ACP Device/Function Argument Descriptor Format . . . . . . . . . . . . . . .
Typical Short FIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attribute Control Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACP-QIO Record Attributes Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACPQIO Attributes Statistics Block . . . . . . . . . . . . . . . . . . . . . . . . . .
Quota File Transfer Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsACP-QIO Functions . . . . . . . . . . . . . . . . . . . . . . . . .
Disk Physical Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dual-Ported Disk Drives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audio Control Block (AUCB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Channel Selection and Volume Settings for CD-ROM Ports as
Used by the SET_VOLUME Function . . . . . . . . . . . . . . . . . . . . . . . . .
Starting Physical Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Physical Cylinder Number Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB Contents for the Sense Mode Function . . . . . . . . . . . . . . . . . . . .
IO$_SKIPFILE Argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IO$_SKIPRECORD Argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sense Mode P1 Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Mode Characteristics Buffer for IO$_SETMODE . . . . . . . . . . . . . .

13
13
14
114
121
123
139
139
26
29
221

Figures
11
12
13
14
15
16
17
18
21
22
23
24
25
26
27
28
31
32
33
34

xii

224
232
233
239
240
317
318
320
321

35
36
41
42
43
44
45
46
47
48
49
410
411
51
52
53
54
55
56
57
58
59
510
511
512
513
514
515
516
517
518
61
81
82
83
91
92
93
94
95
96
97
98
99
910

Set Mode Characteristics Buffer for IO$_SETCHAR . . . . . . . . . . .

IOSB Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Mailbox Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$QIO READ STREAM Operation . . . . . . . . . . . . . . . . . . . . . . . . . .
Read Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write Attention AST (Read Unsolicited Data) . . . . . . . . . . . . . . . .
Read Attention AST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protection Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsRead Function . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsWrite Function . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsSet Protection Function . . . . . . . . . . . . . . . . . . . .
IOSB ContentsGet Mailbox Information Function . . . . . . . . . . .
Modem Control: Two-Way Simultaneous Operation . . . . . . . . . . . .
Terminal Mailbox Message Format . . . . . . . . . . . . . . . . . . . . . . . .
Short and Long Forms of Terminator Mask Quadwords . . . . . . . .
Itemlist Read Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P4 Carriage Control Specifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write Function Carriage Control (Prefix and Postfix Coding) . . . .
Set Mode and Set Characteristics Buffers . . . . . . . . . . . . . . . . . . .
Relationship of Out-of-Band Function with Control Characters . . .
Set Mode P1 Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example SETMODE Itemlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sense Mode Characteristics Buffer . . . . . . . . . . . . . . . . . . . . . . . .
Sense Mode Characteristics Buffer (type-ahead) . . . . . . . . . . . . . .
Sense Mode P1 Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsRead Function . . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsItemlist Read Function . . . . . . . . . . . . . . . . . . . .
IOSB ContentsWrite Function . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsSet Mode, Set Characteristics, Sense Mode, and
Sense Characteristics Functions . . . . . . . . . . . . . . . . . . . . . . . . . .
IOSB ContentsLAT Port Driver Function . . . . . . . . . . . . . . . . . .
Buffer Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OpenVMS SCSI Class/Port Interface . . . . . . . . . . . . . . . . . . . . . . .
Generic SCSI Class Driver Flow . . . . . . . . . . . . . . . . . . . . . . . . . .
SCSI_NOAUTO System Parameter . . . . . . . . . . . . . . . . . . . . . . . .
Emulated LAN Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typical Ethernet Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAN Frame Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CSMA/CD Frame with Ethernet Header . . . . . . . . . . . . . . . . . . . .
CSMA/CD Frame with IEEE 802.3 Header . . . . . . . . . . . . . . . . . .
FDDI Frame Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Token Ring Frame Format (Alpha Only) . . . . . . . . . . . . . . . . . . . .
LAN Emulation Data Frame Format with IEEE 802.3/Ethernet
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
802.2 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
802.1 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

322
325
42
47
48
410
412
413
415
416
416
416
416
515
519
531
532
539
542
543
547
548
554
580
580
581
582
583
583

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

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

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

584
584
64
82
85
810
934
938
946
947
947
948
948

...
...
...

949
949
950

xiii

911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
B1
B2
D1

802.1 Header Subfields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Source Routing Field (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . .
Frames with Ethernet Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Frames with 802 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Frames with 802E Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class I Service 802.2 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-Supplied Service 802.2 Header . . . . . . . . . . . . . . . . . . . . . . .
DSAP and SSAP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
802 Extended Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DVI$_DEVDEPEND Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Read Function P5 Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write Function P5 Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P2 Extended Characteristics Buffer . . . . . . . . . . . . . . . . . . . . . . . .
Format of IO$M_UPDATE_MAP Setmode P2 Buffer (Alpha Only)
Format of the IO$M_ROUTE P2 Buffer (Alpha Only) . . . . . . . . . .
Sense Mode P1 Characteristics Buffer . . . . . . . . . . . . . . . . . . . . . .
Sense Mode Attribute Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format of IO$M_SHOW_MAP P2 Buffer . . . . . . . . . . . . . . . . . . . .
Format of IO$M_SHOW_ROUTE P2 Buffer (Alpha Only) . . . . . . .
IOSB Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-Bit Layout . . . . . .
OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-Bit Layout . . . . . .
Device Characteristics Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

950
950
951
952
953
956
957
958
959
960
964
967
969
985
986
988
989
991
992
993
B2
B3
D4

Contents of the FIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FIB Fields (Lookup Control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FIB Fields (Access Control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FIB Fields (Extend Control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FIB Fields (Truncate Control) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attribute Control Block Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACP-QIO Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Characteristics Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACP Record Attributes Values . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents of the Statistics Block . . . . . . . . . . . . . . . . . . . . . . . . . . .
IO$_CREATE and the FIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IO$_ACCESS and the File Information Block . . . . . . . . . . . . . . . .
FIB Fields (Movefile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IO$_ACPCONTROL and the FIB . . . . . . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Operations and the FIB . . . . . . . . . . . . . . . . . . . . .
Disk Quota Functions (Enable/Disable) . . . . . . . . . . . . . . . . . . . . .
Disk Quota Functions (Individual Entries) . . . . . . . . . . . . . . . . . .
SCSI Disk Class Driver Audio Commands . . . . . . . . . . . . . . . . . . .
Contents of AUCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Status Codes Returned to the IOSB and AUCB by the SCSI Disk
Class Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

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

14
17
110
111
113
114
115
118
121
124
125
128
132
135
136
137
138
219
221

...

225

Tables
11
12
13
14
15
16
17
18
19
110
111
112
113
114
115
116
117
21
22
23

xiv

24
25
31
32
33
34
35
36
41
51
52
53
54
55
56
57
58
59
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
71
91
92
93

Disk Device Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Disk I/O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Magnetic Tape Device-Independent Characteristics . . . . . . . . . . . . .
Device-Dependent Information for Tape Devices . . . . . . . . . . . . . . .
Extended Device Characteristics for Tape Devices . . . . . . . . . . . . . .
Magnetic Tape I/O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Mode and Set Characteristics Magnetic Tape Characteristics . .
Extended Device Characteristics for Tape Devices . . . . . . . . . . . . . .
Mailbox Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Terminal Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Terminal Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Control and Data Signals (Full Modem Mode Configuration) . . . . . .
Terminal Device-Independent Characteristics . . . . . . . . . . . . . . . . .
Terminal Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extended Terminal Characteristics . . . . . . . . . . . . . . . . . . . . . . . . .
Read QIO Function Modifiers for the Terminal Driver . . . . . . . . . . .
Item Codes for Itemlist Read Operations for the Terminal Driver . .
Write QIO Function Modifiers for the Terminal Driver . . . . . . . . . .
Write Function Carriage Control (FORTRAN: Byte 0 Not Equal to
0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Write Function Carriage Control (P4 byte 0 = 0) . . . . . . . . . . . . . . .
Broadcast Requester IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_NODE Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_SERVICE Item Codes . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_LINK ItemCodes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_PORT Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_NODE Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . .
Node Service Subblock Item Codes . . . . . . . . . . . . . . . . . . . . . . . . .
Node Counters Item Codes for Port Counters Subblocks (Alpha
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Node Counters Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protocol Error Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_SERVICE Item Codes . . . . . . . . . . . . . . . . . . . . . . . . .
Service Node Subblock Item Codes . . . . . . . . . . . . . . . . . . . . . . . . .
Service Counters Subblock Item Codes . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_LINK Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Link Counters Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Link Counters Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT$C_ENT_PORT Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT SENSMODE Queue Entries (Alpha Only) . . . . . . . . . . . . . . . .
IO$M_LT_CONNECT Request Status . . . . . . . . . . . . . . . . . . . . . . .
Byte IOSB+5 Status Information . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAT Rejection Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions of the Shadow Set Virtual Unit Driver . . . . . . . . . . . . . .
Supported OpenVMS VAX Systems LAN Devices . . . . . . . . . . . . . .
Supported OpenVMS Alpha LAN Devices . . . . . . . . . . . . . . . . . . . .
Fast Ethernet Cabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

227
229
38
39
310
311
322
323
44
51
55
516
521
521
523
529
532
539

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

540
541
550
555
558
559
559
562
564

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

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

564
565
567
568
568
570
570
571
572
573
575
576
583
584
73
92
93
96

xv

94
95
96
97
98
99
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947

xvi

DE500 Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DE600 Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Gigabit Ethernet Cabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGPA Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGPA Status and Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAC Counter Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interface Counter Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Host Commands Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interrupt Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DMA Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ring Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal MAC Receive Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGXA Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEGXABasic Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Status Block Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receive MAC Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transmit MAC Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receive List Placement State Machine . . . . . . . . . . . . . . . . . . . . . . . .
Send Data Initiator State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . .
Host Coalescing State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LANCP Device-Specific Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .
PDQ FDDI NICs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TMS380 Token Ring NICs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Components of LAN Emulation over ATM Network . . . . . . . . . . . . . . .
Address Mappings of Token Ring Drivers . . . . . . . . . . . . . . . . . . . . . .
ISA Configuration Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ethernet Controller Device Characteristics . . . . . . . . . . . . . . . . . . . . .
Ethernet Controller Unit and Line Status . . . . . . . . . . . . . . . . . . . . . .
Error Summary Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAN I/O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Maximum User Data Sizes for CSMA/CD, FDDI, and Token Ring . . . .
Maximum User Data Sizes for LAN Emulation over ATM (Alpha
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Maximum Message Sizes for CSMA/CD, FDDI, and Token Ring . . . . .
Maximum Message Sizes for LAN Emulation over ATM (Alpha
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Mode Parameters for Packet Formats . . . . . . . . . . . . . . . . . . . . . .
Medium Specific Parameters of IO$M_SET_MAC for Ethernet (Alpha
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Medium Specific Parameters of IO$M_SET_MAC for FDDI . . . . . . . . .
Medium Specific Parameters of IO$M_SET_MAC for Token Ring . . . .
Medium Specific Parameters of IO$M_SET_MAC for ATM . . . . . . . . .
Parameters of IO$M_SENSE_MAC . . . . . . . . . . . . . . . . . . . . . . . . . . .
State of the Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rules for Promiscuous Mode Operation . . . . . . . . . . . . . . . . . . . . . . . .

96
97
97
98
98
911
913
916
917
917
918
918
919
921
922
926
926
927
929
929
930
931
932
932
933
942
943
960
961
961
961
965
965
967
967
970
979
982
982
983
984
989
993
994

B1
C1
C2
D1
D2

S2DGB$L_FLAGS Bit Fields . . . . . . . . . . . . . .

DEC Multinational Character Set . . . . . . . . . .
Sequences and Modes . . . . . . . . . . . . . . . . . . .
Control Connection Routines . . . . . . . . . . . . . .
Symbolic Names Defined by $PTDDEF Macro .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

B4
C1
C9
D1
D11

xvii

Preface
Intended Audience
This manual is intended for system programmers who want to take advantage of
the time and space savings that result from direct use of I/O drivers. OpenVMS
users who do not require such detailed knowledge of I/O drivers can use the
device-independent services described in the OpenVMS Record Management
Services Reference Manual.

Document Structure
This manual is organized into the following chapters and appendixes:

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

Chapters 2 through 9 describe the use of file-structured and real-time I/O

device drivers, the drivers for storage devices such as disks and magnetic
tapes, and supported terminal devices:
Chapter 2 discusses the disk drivers.
Chapter 3 discusses the magnetic tape drivers.
Chapter 4 discusses the mailbox driver.
Chapter 5 discusses the terminal driver.
Chapter 6 discusses the pseudoterminal driver.
Chapter 7 discusses the shadow-set virtual unit driver.
Chapter 8 discusses the Generic Small Computer System Interface (SCSI)
class driver.
Chapter 9 discusses the local area network (LAN) device drivers.

Chapter 10 describes optional features to improve OpenVMS Alpha I/O

performance.

Appendix A summarizes the QIO function codes, arguments, and function

modifiers used by the drivers listed previously.

Appendix B describes the enhanced IO$_DIAGNOSE function for SCSI class

drivers.

Appendix C lists the DEC Multinational character set and the ANSI and
DIGITAL private escape sequences for terminals.

Appendix D describes the calling conventions for the pseudoterminal drivers

control connection routines.

xix

Device Driver Support for OpenVMS Alpha 64-Bit Addressing

The OpenVMS Alpha operating system provides support for 64-bit virtual
memory addressing, which makes the 64-bit virtual address space defined by the
Alpha architecture available to the OpenVMS Alpha operating system and to
application programs. In the 64-bit virtual address space, both process-private
and system virtual address space extend beyond 2 GB. By using 64-bit addressing
features, programmers can create images that map and access data beyond the
limits of 32-bit virtual addresses.
Input and output operations can be performed directly to and from the 64-bit
addressable space by means of RMS services, the $QIO system service, and most
of the device drivers supplied with OpenVMS Alpha systems. A device driver
declares support for 64-bit addresses individually by I/O function code. Disk and
tape device drivers support 64-bit addresses for data transfers to and from disk
and tape devices on the virtual, logical, and physical read and write functions.
For example, the OpenVMS SCSI disk class driver, SYS$DKDRIVER, supports
64-bit addresses on the IO$_READVBLK and IO$_WRITEVBLK functions,
but not on the IO$_AUDIO function. The device drivers, function codes, and
$QIO arguments that support 64-bit addressing are indicated in the appropriate
chapters of this manual.
For more information about the OpenVMS Alpha device drivers that support
64-bit addressing, refer to the OpenVMS Programming Concepts Manual. To find
out how to modify a customer-written device driver to support 64-bit addressing,
see the OpenVMS Alpha Guide to Upgrading Privileged-Code Applications.

Related Documents
The following manuals provide additional information that relates to the topics
covered in this book:

OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

OpenVMS Programming Concepts Manual

OpenVMS System Services Reference Manual: AGETUAI

OpenVMS System Services Reference Manual: GETUTCZ

OpenVMS Record Management Services Reference Manual

DECnet for OpenVMS Networking Manual (available on the Documentation

CD-ROM)

OpenVMS VAX Device Support Manual (available on the Documentation

CD-ROM)
Important Note
For updated hardware information, refer to the most recent Software
Product Description for the OpenVMS Operating System for Alpha and
VAX.

For additional information about Compaq OpenVMS products and services, access
the Compaq website at the following location:
http://www.openvms.compaq.com/

xx

Readers Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
Internet

[email protected]

Mail

Compaq Computer Corporation

OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Visit the following World Wide Web address for information about how to order
additional documentation:
http://www.openvms.compaq.com/

Conventions
The following conventions are used in this manual:
Ctrl/x

A sequence such as Ctrl/x indicates that you must hold down

the key labeled Ctrl while you press another key or a pointing
device button.

PF1 x

A sequence such as PF1 x indicates that you must first press

and release the key labeled PF1 and then press and release
another key or a pointing device button.

Return

In examples, a key name enclosed in a box indicates that

you press a key on the keyboard. (In text, a key name is not
enclosed in a box.)
In the HTML version of this document, this convention appears
as brackets, rather than a box.

...

A horizontal ellipsis in examples indicates one of the following

possibilities:

Additional optional arguments in a statement have been

omitted.

The preceding item or items can be repeated one or more

times.

Additional parameters, values, or other information can be

entered.

.
.
.

A vertical ellipsis indicates the omission of items from a code

example or command format; the items are omitted because
they are not important to the topic being discussed.

()

In command format descriptions, parentheses indicate that you

must enclose choices in parentheses if you specify more than
one.

[]

In command format descriptions, brackets indicate optional

choices. You can choose one or more items or no items.
Do not type the brackets on the command line. However,
you must include the brackets in the syntax for OpenVMS
directory specifications and for a substring specification in an
assignment statement.

xxi

In command format descriptions, vertical bars separate choices

within brackets or braces. Within brackets, the choices are
optional; within braces, at least one choice is required. Do not
type the vertical bars on the command line.

{}

In command format descriptions, braces indicate required

choices; you must choose at least one of the items listed. Do
not type the braces on the command line.

bold text

This typeface represents the introduction of a new term. It

also represents the name of an argument, an attribute, or a
reason.

italic text

Italic text indicates important information, complete titles

of manuals, or variables. Variables include information that
varies in system output (Internal error number), in command
lines (/PRODUCER=name), and in command parameters in
text (where dd represents the predefined code for the device
type).

UPPERCASE TEXT

Uppercase text indicates a command, the name of a routine,

the name of a file, or the abbreviation for a system privilege.

Monospace text

Monospace type indicates code examples and interactive screen

displays.
In the C programming language, monospace type in text
identifies the following elements: keywords, the names
of independently compiled external functions and files,
syntax summaries, and references to variables or identifiers
introduced in an example.

xxii

A hyphen at the end of a command format description,

command line, or code line indicates that the command or
statement continues on the following line.

numbers

All numbers in text are assumed to be decimal unless

otherwise noted. Nondecimal radixesbinary, octal, or
hexadecimalare explicitly indicated.

1
ACPQIO Interface
An ancillary control process (ACP) is a process that interfaces between
the user process and the driver, and performs functions that supplement the
drivers functions. Virtual I/O operations involving file-structured devices
(disks and magnetic tapes) often require ACP intervention. In most cases, ACP
intervention is requested by OpenVMS Record Management Services (RMS) and
is transparent to the user process; however, user processes can request ACP
functions directly by issuing a Queue I/O (QIO) request and specifying an ACP
function code.
Executing physical and logical input/output (I/O) operations on a device that is
managed by a file ACP interferes with the operation of the ACP, and can result in
unpredictable consequences such as system failure.
In addition to the ACP, the XQP (extended QIO processor) facility supplements
the QIO drivers functions when performing virtual I/O operations on filestructured devices; however, rather than being a separate process, the XQP
executes as a kernel-mode thread in the process of its caller.
An XQP is provided to support Files-11 ODS-2 and ODS-5 (On-Disk Structure
Level 2 and 5) disks as the base file system, and an ACP is provided for ANSI
standard X3.27 magnetic tapes.
On VAX systems, an ACP is provided for supporting Files-11 ODS-1 (On-Disk
Structure Level 1) disks.
There are also ACPs to support the ISO 9660 CD-ROM disk structure (Files-11
C) and High Sierra CD-ROM disk structure (Files-11 D). Collectively, these ACPs
are called Files-11 C/D.
This chapter describes the QIO interface to ACPs for disk and magnetic tape
devices (file system ACPs). The sample program in Chapter 3 performs QIO
operations to the magnetic tape ACP.
This section also describes a number of structures and field names of the form
xxx$name. A MACRO program can define symbols of this form by invoking the
$xxxDEF macro.
The following macros are available in SYS$LIBRARY:STARLET.MLB:
$IODEF
$FIBDEF
$ATRDEF
$SBKDEF
The following macros are available in SYS$LIBRARY:LIB.MLB:
$FATDEF
$DQFDEF
$FCHDEF

ACPQIO Interface 11

ACPQIO Interface

Programs written in BLISS-32 can use these symbols by referencing them and
including the correct library, SYS$LIBRARY:STARLET.L32 (for the macros listed
under SYS$LIBRARY:STARLET.MLB), and SYS$LIBRARY:LIB.L32 (for the
macros listed under SYS$LIBRARY:LIB.MLB).
References to ANSI refer to the American National Standard Magnetic Tape
Labels and File Structures for Information Interchange, ANSI X3.271978.

1.1 ACP Functions and Encoding

ACP functions can be expressed using seven function codes and four function
modifiers. The function codes are:

IO$_CREATECreates a directory entry or file

IO$_ACCESSSearches a directory for a specified file and accesses the file, if

found

IO$_DEACCESSDeaccesses a file and, if specified, writes the final

attributes in the file header

IO$_MODIFYModifies the file attributes and file allocation

IO$_DELETEDeletes a directory entry and file header

IO$_MOUNTInforms the ACP when a volume is mounted; requires MOUNT

privilege

IO$_ACPCONTROLPerforms miscellaneous control functions

The function modifiers are:

IO$M_ACCESSOpens a file on the users channel

IO$M_CREATECreates a file

IO$M_DELETEDeletes a file or marks it for deletion

IO$M_DMOUNTDismounts a volume

In addition to the function codes and modifiers, ACPs take five device- or
function-dependent arguments, as shown in Figure 11. The first argument, P1,
is the address of the file information block (FIB) descriptor. Section 1.2 describes
the FIB in detail.
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.
Argument P3 is the address of
length. The resultant string is
Argument P4 is the address of
file name string. Both of these

12 ACPQIO Interface

a word to receive the resultant file name string

not padded. The actual length is returned in P3.
a descriptor for a buffer to receive the resultant
arguments are optional.

ACPQIO Interface
1.1 ACP Functions and Encoding
Figure 11 ACP Device- or Function-Dependent Arguments
31

P1:

Address of FIB Descriptor

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)

ZK0636GE

The fifth argument, P5, is an optional argument containing the address of the
attribute control block. Section 1.3.5 describes the attribute control block in
detail.
All areas of memory specified by the descriptors must be capable of being read or
written to.
Figure 12 shows the format for the descriptors. The count field is the length in
bytes of the item described.
Figure 12 ACP Device/Function Argument Descriptor Format
31

16 15
Not Used

0
Count

Address
ZK0637GE

1.2 File Information Block (FIB)

The file information block (FIB) contains much of the information that is
exchanged between the user process and the ACP. The FIB must be writable.
The FIB is passed by a descriptor (see Figure 12). A short FIB can be used in
ACP calls that do not need arguments near the end of the FIB. The ACP treats
the omitted portion of the FIB as if it were 0. Figure 13 shows the format of a
typical short FIB that would be used to open an existing file.

ACPQIO Interface 13

ACPQIO Interface
1.2 File Information Block (FIB)
Figure 13 Typical Short FIB
31

24 23

16 15

FIB$B_WSIZE

87

FIB$L_ACCTL
FIB$W_FID

FIB$W_DID
FIB$L_WCC
0

FIB$W_NMCTL
0
ZK0639GE

Table 11 gives a brief description of the FIB fields. More detailed descriptions
are provided in Sections 1.3 and 1.6.
Table 11 Contents of the FIB
Field

Subfields

Meaning

FIB$L_ACCTL

Contains flag bits that control the access to the

file. Sections 1.3.1.1, 1.3.2.1, 1.6.1.1, 1.6.4.1, and
1.6.5 describe the FIB$L_ACCTL field flag bits.

FIB$L_ACL_STATUS

Status of the requested ACL attribute operation, if

any. The ACL attributes are included in Table 17.
If no ACL attributes are given, SS$_NORMAL is
returned here.

FIB$L_ACLCTX

Maintains position context when processing ACL

attributes from the attribute (P5) list.

FIB$B_ALALIGN

Contains the interpretation mode of the allocation

(FIB$W_ALLOC) field.

FIB$W_ALLOC

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

FIB$W_LOC_FID

Three-word related file ID for RFI placement.

FIB$W_LOC_NUM

Related file number.

FIB$W_LOC_SEQ

Related file sequence number.

FIB$B_LOC_RVN

Related file relative volume number (RVN) or

placement RVN.

FIB$B_LOC_NMX

Related file number extension.

FIB$L_LOC_ADDR

Placement logical block number (LBN), cylinder, or

virtual block number (VBN).
Contains option bits that control the placement
of allocated blocks. Section 1.3.3.1 describes the
FIB$B_ALOPTS field flag bits.
(continued on next page)

14 ACPQIO Interface

ACPQIO Interface
1.2 File Information Block (FIB)
Table 11 (Cont.) Contents of the FIB
Field

Subfields

Meaning

FIB$L_ALT_ACCESS

A 32-bit mask that represents an access mask to

check against file protection; for example, opens a
file for read access and checks whether it can be
deleted. The mask has the same configuration as
the standard protection mask.

FIB$W_CNTRLFUNC

In an IO$_ACPCONTROL function, this field

contains the code that specifies which ACP control
function is to be performed (see Section 1.6.8).
This field overlays FIB$W_EXCTL.

FIB$L_CNTRLVAL

Contains a control function value used in an IO$_

ACPCONTROL function (see Section 1.6.8). The
interpretation of the value depends on the control
function specified in FIB$W_CNTRLFUNC. This
field overlays FIB$L_EXSZ.

FIB$W_DID

Contains the file identifier of the directory file.

For Files-11 On-Disk Structure Level 1 and Level
2, the following subfields are defined:
FIB$W_DID_NUM

File number.

FIB$W_DID_SEQ

File sequence number.

FIB$W_DID_RVN

Relative volume number (only for magnetic tape

devices).

FIB$B_DID_RVN

Relative volume number (only for disk devices).

FIB$B_DID_NMX

File number extension (only for disk devices).

FIB$W_EXCTL

Contains flag bits that specify extend control for

disk devices. Sections 1.3.3.1 and 1.3.4.1 describe
the FIB$W_EXCTL field flag bits.

FIB$L_EXSZ

Specifies the number of blocks to be allocated in

an extend operation on a disk file.

FIB$L_EXVBN

Specifies the starting disk file virtual block

number at which a file is to be truncated.

FIB$W_FID

Specifies the file identification. You supply the file

identifier when it is known; the ACP returns the
file identifier when it becomes known; for example,
as a result of a create or directory lookup. A 0
file identifier can be specified when an operation
is performed on a file that is already open on
a particular channel. The ACP returns the file
identifier of the open file.
For Files-11 On-Disk Structure Level 1 and Level
2, the following subfields are defined:
FIB$W_FID_NUM

File number.

FIB$W_FID_SEQ

File sequence number.

FIB$W_FID_RVN

Relative volume number (only for magnetic tape

devices).

FIB$B_FID_RVN

Relative volume number (only for disk devices).

FIB$B_FID_NMX

File number extension (only for disk devices).

(continued on next page)

ACPQIO Interface 15

ACPQIO Interface
1.2 File Information Block (FIB)
Table 11 (Cont.) Contents of the FIB
Field

Subfields

Meaning

FIB$B_NAME_
FORMAT_IN

Contains the format of the input file specification.

Section 1.3.1.1 describes the FIB$B_NAME_
FORMAT_IN field flag bits.

FIB$B_NAME_
FORMAT_OUT

Contains the format of the output file specification.

Section 1.3.1.1 describes the FIB$B_NAME_
FORMAT_OUT field flag bits.

FIB$W_NMCTL

Contains flag bits that control the processing of

a name string in a directory operation. Sections
1.3.1.1 and 1.6.1.1 describe the FIB$W_NMCTL
field flag bits.

FIB$L_STATUS

Access status. Applies to all major functions. The

following bits are supported:
FIB$V_ALT_REQ

Set to indicate whether the alternate access bit is

required for the current operation. If not set, the
alternate access bit is optional.

FIB$V_ALT_GRANTED

If FIB$V_ALT_REQ = 0, the FIB bit returned from

the file system is set if the alternate access check
succeeded.

FIB$W_VERLIMIT

Contains the version limit of the directory entry.

FIB$L_WCC

Maintains position context when processing

wildcard directory operations.

FIB$B_WSIZE

Controls the size of the file window used to map

a disk file. If a window size of 255 is specified,
the file is completely mapped by using segmented
windows.

1.3 ACP Subfunctions

The operations that the ACP performs can be organized into two categories:
major ACP functions and subfunctions. Each ACP operation performs one
major function. That function is specified by an I/O function code, such as IO$_
ACCESS, IO$_CREATE, or IO$_MODIFY. While executing the major function,
one or more subfunctions can be performed. A subfunction is an operation such
as looking up, accessing, or extending a file. Most subfunctions can be executed
by more than one of the major functions. Sections 1.3.1 through 1.3.5 describe
the following subfunctions in detail:

Directory Lookup

Access

Extend

Truncate

Read/Write Attributes

Section 1.6, which contains the descriptions of the major functions, lists the
subfunctions available to each major function.

16 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
1.3.1 Directory Lookup
The directory lookup subfunction is used to search for a file in a disk directory or
on a magnetic tape. This subfunction can be invoked using the major functions
IO$_ACCESS, IO$_MODIFY, IO$_DELETE, and IO$_ACPCONTROL. A directory
lookup occurs if the directory file ID field in the FIB (FIB$W_DID) is a nonzero
number.
1.3.1.1 Input Parameters
Table 12 lists the FIB fields that control the processing of a lookup subfunction.

Table 12 FIB Fields (Lookup Control)

Field

Subfields

FIB$W_NMCTL

Meaning
Name string control. The following name control bits
are applicable to a lookup operation:

FIB$V_ALLNAM

Set to match all name field values.

FIB$V_ALLTYP

Set to match all field type values.

FIB$V_ALLVER

Set to match all version field values.

FIB$V_CASE_
SENSITIVE

When set, performs case-sensitive lookup; when clear,

performs case-blind lookup.

FIB$V_FINDFID

Set to search a directory for the file ID in FIB$W_

FID.

FIB$V_NAMES_8BIT

Caller can accept (8-bit) ODS-2 or ISO Latin-1

formats.

FIB$V_NAMES_16BIT

Caller can accept (16-bit) Unicode (UCS-2) formats.

FIB$V_WILD

Set if name string contains wildcards. Setting this

bit causes wildcard context to be returned in FIB$L_
WCC.

FIB$W_FID

File identification. The file ID of the file found is

returned in this field.

FIB$W_DID

Contains the file identifier of the directory file. This

field must be a nonzero number.

FIB$L_WCC

Maintains position context when processing wildcard

directory operations.

FIB$L_ACCTL

The following access control flag is applicable to a

lookup subfunction:
FIB$V_REWIND

FIB$B_NAME_
FORMAT_IN

Set to rewind magnetic tape before lookup. If not set,

a magnetic tape is searched from its current position.
Contains the format of the input file specification.
The following formats are valid:

FIB$C_ODS2

ODS-2 Format (default)

FIB$C_ISO_LATIN

ISO Latin-1 Format

FIB$C_UCS2

Unicode (UCS-2) Format

FIB$B_NAME_
FORMAT_OUT

Contains the format of the output file specification.

The following formats are valid:
FIB$C_ODS2

ODS-2 Format (default)

(continued on next page)

ACPQIO Interface 17

ACPQIO Interface
1.3 ACP Subfunctions
Table 12 (Cont.) FIB Fields (Lookup Control)
Field

Subfields

Meaning

FIB$C_ISO_LATIN

ISO Latin-1 Format

FIB$C_UCS2

Unicode (UCS-2) Format

QIO arguments P2 through P6 (see Figure 11) are passed as values. The second
argument, P2, specifies the address of the descriptor for the file name string to be
searched for in the directory.
The file name string must have one of the following two formats:
name.type;version
name.type.version
The name and type can be any combination of alphanumeric characters, and
the dollar sign ( $ ), asterisk ( * ), and percent ( % ) characters. The version must
consist of numeric characters optionally preceded by a minus sign ( ) (only for
disk devices) or a single asterisk. The total number of alphanumeric and percent
characters in the name field and in the type field must not exceed 39. Any
number of additional asterisks can be present.
If any of the bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER are
set, then the contents of the corresponding field in the name string are ignored
and the contents are assumed to be an asterisk.
Note that the file name string cannot contain a directory string. The directory
is specified by the FIB$W_DID field (see Table 11). Only RMS can process
directory strings.
Argument P3 is the address of a word to receive the resultant file name string
length. Argument P4 is the address of a descriptor for a buffer to receive the
resultant file name string. The resultant string is not padded. The P3 and P4
arguments are optional.
1.3.1.2 Operation
The system searches either the directory file specified by FIB$W_DID or the
magnetic tape for the file name specified in the P2 file name parameter. The
actual file name found and its length are returned in the P3 and P4 length and
result string buffers. The file ID of the file found is returned in FIB$W_FID and
can be used in subsequent operations as the major function is processed.
Zero and negative version numbers have special significance in a disk lookup
operation. Specifying 0 as a version number causes the latest version of the file
to be found. Specifying 1 locates the second most recent version, 2 the third
most recent, and so forth. Specifying a version of 0 locates the lowest numbered
version of the file. For magnetic tape lookups, a version number of 0 locates the
first occurrence of the file encountered; negative version numbers are not allowed.
Wildcard lookups are performed by specifying the appropriate wildcard characters
in the name string and setting FIB$V_WILD. (The name control bits FIB$V_
ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER can also be used in searching
for wildcard entries, but they are intended primarily for compatibility mode use.)
On the first lookup, FIB$L_WCC should contain zero entries. On each lookup, the
ACP returns a nonzero value in FIB$L_WCC, which must be passed back on the
next lookup call. In addition, you must pass the resultant name string returned
by the previous lookup using the P4 result string buffer, and its length in the P3

18 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
result length word. This string is used together with FIB$L_WCC to continue the
wildcard search at the correct position in the directory.
Perform a lookup by file ID by setting the name control bit FIB$V_FINDFID.
When this bit is set, the system searches the directory for an entry containing the
file ID specified in FIB$W_FID, and the name of the entry found is returned in
the P3 and P4 result parameters. Note that if a directory contains multiple
entries with the same file ID, only the first entry can be located with this
technique.
Lookups by file ID should be done only when the file name is not available,
because lookups by this method are often significantly slower than lookups by file
name.
Because not all programs can handle all of the available name formats, the
FIB$W_NMCTL flags govern the name formats, and are returned as follows:

FIB$V_ NAMES_8BIT clear

FIB$V_ NAMES_16BIT clear
Only ODS-2 format names are returned. Note that this includes specifications
that were originally in ISO Latin-1 format or Unicode (UCS-2) format
but converted to ODS-2 format before being stored on the volume. All
specifications are converted to uppercase before being returned.

FIB$V_ NAMES_8BIT set

FIB$V_ NAMES_16BIT clear
Only those file specifications stored in ODS-2 and ISO Latin-1 formats are
returned. The value in the FIB$B_NAME_FORMAT_OUT field indicates the
format of the particular name being returned. ODS-2 format file specifications
are not converted to uppercase before being returned.

FIB$V_ NAMES_8BIT clear

FIB$V_ NAMES_16BIT set
All file specifications are returned in Unicode (UCS-2) format.

FIB$V_ NAMES_8BIT set

FIB$V_ NAMES_16BIT set
File specifications are returned in the format stored on the volume. This is
the simplest format compatible with the file name syntax and the characters
it contains. For example, a specification originally in Unicode format that
only contains characters that are part of the ISO Latin-1 character set are
returned in ISO Latin-1 format.

1.3.1.3 Directory Entry Protection

A directory entry is protected with the same protection code as the file itself. For
example, if a directory file is protected against delete access, then the file name
has the same protection. Consequently, a nonprivileged user cannot rename a file
because renaming a file is essentially the same as deleting the file name. This
protection is applied regardless of the protection on the directory file.
Nonprivileged users can neither write directly into a .DIR;1 directory file nor turn
off the directory bit in a directory file header.

ACPQIO Interface 19

ACPQIO Interface
1.3 ACP Subfunctions
1.3.2 Access
The access subfunction is used to open a file so that virtual read or write
operations can be performed. This subfunction can be invoked using the major
functions IO$_CREATE and IO$_ACCESS (see Sections 1.6.1 and 1.6.2). An
access subfunction is performed if the IO$M_ACCESS modifier is specified in the
I/O function code.
1.3.2.1 Input Parameters
Table 13 lists the FIB fields that control the processing of an access subfunction.

Table 13 FIB Fields (Access Control)

Field

Subfields

FIB$L_ACCTL

Meaning
Specifies field values that control access to the file.
The following access control bits are applicable to the
access subfunction:

FIB$V_WRITE

Set for write access; clear for read-only access.

FIB$V_NOREAD

Set to deny read access to others. (You must have

write privilege to the file to use this option.)

FIB$V_NOWRITE

Set to deny write access to others.

FIB$V_NOTRUNC

Set to prevent the file from being truncated; clear to

allow truncation.

FIB$V_DLOCK

Set to enable deaccess lock (close check). Used only

for disk devices.
Used to flag a file as inconsistent if the program
currently modifying the file terminates abnormally. If
the program deaccesses the file without performing a
write attributes operation, the file is marked as locked
and cannot be accessed until it is unlocked.

FIB$V_UPDATE

Set to position at the start of a magnetic tape file

when opening a file for write; clear to position at
end-of-file.

FIB$V_READCK

Set to enable read checking of the file. Virtual reads

to the file are performed using a data check operation.

FIB$V_WRITECK

Set to enable write checking of the file. Virtual writes

to the file are performed using a data check operation.

FIB$V_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 requests issued from
SUPERVISOR, EXEC, or KERNEL mode.

FIB$V_NOLOCK

Set to override exclusive access to the file, allowing

you to access the file when another user has the
file open with FIB$V_NOREAD specified. You must
have SYSPRV privilege to use this option. FIB$V_
NOREAD and FIB$V_NOWRITE must be clear for
this option to work.

FIB$V_NORECORD

Set to inhibit recording of the files modification and

expiration dates. If not set, the files expiration date
can be modified, depending on the file retention
parameters of the volume.
(continued on next page)

110 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
Table 13 (Cont.) FIB Fields (Access Control)
Field

Subfields

Meaning

FIB$V_SEQONLY

Set to inform the file system that the file is to be

processed sequentially only.

FIB$B_WSIZE

Controls the size of the file window used to map a

disk file. The ACP uses the volume default if FIB$B_
WSIZE is 0. 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. Note that
the window is charged to the users BYTELIM quota.

FIB$W_FID

Specifies the file identification of the file to be

accessed.

1.3.2.2 Operation
The file is opened according to the access control specified (see Table 13).

1.3.3 Extend
The extend subfunction is used to allocate space to a disk file. This subfunction
can be invoked using the major I/O functions IO$_CREATE and IO$_MODIFY
(see Sections 1.6.1 and 1.6.4). The extend subfunction is performed if the bit
FIB$V_EXTEND is set in the extend control word FIB$W_EXCTL.
1.3.3.1 Input Parameters
Table 14 lists the FIB fields that control the processing of an extend subfunction.

Table 14 FIB Fields (Extend Control)

Field

Subfields

FIB$W_EXCTL

Meaning
Extend control flags. The following flags are
applicable to the extend subfunction:

FIB$V_EXTEND

Set to enable extension.

FIB$V_NOHDREXT

Set to inhibit generation of extension file headers.

FIB$V_ALCON

Allocates contiguous space. The extend operation fails

if the necessary contiguous space is not available.

FIB$V_ALCONB

Allocates the maximum amount of contiguous space.

If both FIB$V_ALCON and FIB$V_ALCONB are set,
a single contiguous area, whose size is the largest
available but not greater than the size requested, is
allocated.

FIB$L_EXSZ

FIB$V_FILCON

Marks the file as contiguous. This bit can only be set

if the file does not have space already allocated to it.

FIB$V_ALDEF

Allocates the extend size (FIB$L_EXSZ) or the system

default, whichever is greater.
Specifies the number of blocks to allocate to the file.
(continued on next page)

ACPQIO Interface 111

ACPQIO Interface
1.3 ACP Subfunctions
Table 14 (Cont.) FIB Fields (Extend Control)
Field

Subfields

Meaning
The number of blocks actually allocated for this
operation is returned in this longword. More blocks
than requested can be allocated to meet cluster
boundaries.

FIB$L_EXVBN

Returns the starting virtual block number of the

blocks allocated. FIB$L_EXVBN must initially
contain 0 blocks.

FIB$B_ALOPTS

Contains option bits that control the placement of

allocated blocks. The following bits are defined:
FIB$V_EXACT

Set to require exact placement; clear to specify

approximate placement. If this bit is set and
the specified blocks are not available, the extend
operation fails.

FIB$V_ONCYL

Set to locate allocated space within a cylinder. This

option functions correctly only when FIB$V_ALCON
or FIB$V_ALCONB is specified.

FIB$B_ALALIGN

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 byte relative volume number

(RVN) in FIB$B_LOC_RVN and a cylinder number in
FIB$L_LOC_ADDR.

FIB$C_LBN

Location is specified as a byte RVN in FIB$B_LOC_

RVN, followed by a longword logical block number
(LBN) in FIB$L_LOC_ADDR.

FIB$C_VBN

Location is specified as a longword virtual block

number (VBN) of the file being extended in FIB$L_
LOC_ADDR. A 0 VBN or one that fails to map
indicates the end of the file.

FIB$C_RFI

Location is specified as a three-word file ID in

FIB$W_LOC_FID, followed by a longword VBN of
that file in FIB$L_LOC_ADDR. A 0 file ID indicates
the file being extended. A 0 VBN or one that fails to
map indicates the end of that file.

FIB$W_ALLOC

112 ACPQIO Interface

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_LOC_FID

Three-word related file ID for RFI placement.

FIB$W_LOC_NUM

Related file number.

FIB$W_LOC_SEQ

Related file sequence number.

FIB$B_LOC_RVN

Related file RVN or placement RVN.

FIB$B_LOC_NMX

Related file number extension.

FIB$L_LOC_ADDR

Placement LBN, cylinder, or VBN.

ACPQIO Interface
1.3 ACP Subfunctions
1.3.3.2 Operation
The specified number of blocks are allocated and appended to the file. The virtual
block number assigned to the first block allocated is returned in FIB$L_EXVBN.
The actual number of blocks allocated is returned in FIB$L_EXSZ.
The actual number of blocks allocated is also returned in the second longword of
the users I/O status block. If a contiguous allocation (FIB$V_ALCON) fails, the
size of the largest contiguous space available on the disk is returned in the second
longword of the users I/O status block.

1.3.4 Truncate
The truncate subfunction is used to remove space from a disk file. This
subfunction can be invoked by the major I/O functions IO$_DEACCESS and IO$_
MODIFY (see Sections 1.6.3 and 1.6.4). The truncate subfunction is performed if
the bit FIB$V_TRUNC is set in the extend control word FIB$W_EXCTL.
1.3.4.1 Input Parameters
Table 15 lists the FIB fields that control the processing of a truncate
subfunction.
Table 15 FIB Fields (Truncate Control)
Field

Subfields

FIB$W_EXCTL

Meaning
Extend control flags. The following flags are
applicable to the truncate subfunction:

FIB$V_TRUNC

Must be set to enable truncation.

FIB$V_MARKBAD

Set to append the truncated blocks to the bad block

file, instead of returning them to the free storage
pool. Only one cluster can be deallocated. This is
most easily accomplished by specifying the last VBN
of the file in FIB$L_EXVBN. SYSPRV privilege or
ownership of the volume is required to deallocate
blocks to the bad block file.

FIB$L_EXSZ

Returns the actual number of blocks deallocated.

FIB$L_EXSZ must initially contain a value of 0.

FIB$L_EXVBN

Specifies the first virtual block number to be removed

from the file. The actual starting virtual block
number of the truncate operation is returned in
this field.

1.3.4.2 Operation
Blocks are deallocated from the file, starting with the virtual block specified in
FIB$L_EXVBN and continuing through the end of the file. The actual number
of blocks deallocated is returned in FIB$L_EXSZ. The virtual block number of
the first block actually deallocated is returned in FIB$L_EXVBN. Because of
cluster round-up, this value might be greater than the value specified. If FIB$V_
MARKBAD is specified, the truncation VBN is rounded down instead of up, and
the value returned in FIB$L_EXVBN might be less than that specified.
The number of blocks by which FIB$L_EXVBN was rounded up is returned in the
second longword of the I/O status block.
The truncate subfunction normally requires exclusive access to the file at run
time. This means, for example, that a file cannot be truncated while multiple
writers have access to it.

ACPQIO Interface 113

ACPQIO Interface
1.3 ACP Subfunctions
An exception occurs when a truncate subfunction is requested for a write-accessed
file that allows other readers. Although the truncate subfunction returns success
status in this instance, the actual file truncation (the return of the truncated
blocks to free storage) is deferred until the last reader deaccesses the file. If a
new writer accesses the file after the truncate subfunction is requested, but before
the last deaccess, the deferred truncation is ignored.
Once the truncate operation has started, the file is locked from other writers for
the duration of the truncate operation. Attempts to access the file for shared
write access during this time will result in an SS$_ACCONFLICT error.

1.3.5 Read/Write Attributes

The read and write attributes subfunctions are used for operations such as
reading and writing file protection and creating and revising dates. A read or
write attributes operation is invoked by specifying an attribute list with the
QIO parameter P5. A read attributes operation can be invoked by the major I/O
function IO$_ACCESS (see Section 1.6.2); a write attributes operation can be
invoked by the major I/O functions IO$_CREATE, IO$_DEACCESS, and IO$_
MODIFY (see Sections 1.6.1, 1.6.3, and 1.6.4).
1.3.5.1 Input Parameters
The read or write attributes subfunction is controlled by the attribute list
specified by P5. The list consists of a variable number of two longword control
blocks, terminated by a 0 longword, as shown in Figure 14. The maximum
number of attribute control blocks in one list is 30. Table 16 describes the
attribute control block fields.
Figure 14 Attribute Control Block Format
31

16 15
ATR$W_TYPE

0
ATR$W_SIZE

ATR$L_ADDR

(Additional Control Blocks)

0
ZK0640GE

Table 16 Attribute Control Block Fields

Field

Meaning

ATR$W_SIZE

Specifies the number of bytes of the attribute to be written, or the size

of the buffer into which the attribute is to be read. Legal values for
writing attributes are from 0 to the maximum size of the particular
attribute (see Table 17), and legal values for the reading attributes
are from 0 to the maximum unsigned 16-bit integer.
(continued on next page)

114 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
Table 16 (Cont.) Attribute Control Block Fields
Field

Meaning

ATR$W_TYPE

Identifies the individual attribute to be read or written.

ATR$L_ADDR

Contains the buffer address of the memory space to or from which the
attribute is to be transferred. The attribute buffer must be writable.

Table 17 lists the valid attributes for ACP-QIO functions. The maximum size
(in bytes) is determined by the required attribute configuration. For example,
the Radix-50 file name (ATR$S_FILNAM) uses only 6 bytes, but it 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).
Table 17 ACP-QIO Attributes
Maximum Size
(bytes)

Attribute Name6

Meaning

ATR$C_ACCDATE12

Corresponds to POSIX st_atime and reflects the

last time a file was accessed.

ATR$C_ACCESS_MODE

Access mode for following attribute descriptors.

File access level.

Returns the size, in bytes, of the objects ACL.

2 4 5 10

ATR$C_ACLEVEL

ATR$C_ACLLENGTH

10 11

ATR$C_ADDACLENT

7 10

ATR$C_ALCONTROL
ATR$C_ASCDATES

2 Protected
3 Not

255

Adds an ACE to the beginning of the ACL when the

ACE context value is 0; to the end of the ACL when
the ACE context value is 1; or at a location pointed
to by a prior ACL$C_FNDACETYP or ACL$C_
FNDACLENT.

14

Compatibility mode allocation data.

35

Revision count (2 binary bytes), revision date,

creation date, and expiration date, in ASCII.
Format: DDMMMYY (revision date), HHMMSS
(time), DDMMMYY (creation date), HHMMSS
(time), DDMMMYY (expiration date). (The format
contains no embedded spaces or commas.)

(can be written to only by system or owner).

supported on write operations to MTAACP; defaults are returned on read operations.

4 Locked
5 For

2 3

11

(cannot be written to while the file is locked).

Files-11 C/D, returns 0.

6 Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code and one with an ATR$S_
prefix for the size, which is not included in the list.
7 Exclusive

access required. This operation does not complete successfully if other readers or writers are allowed.

10 Not

supported for Files-11 On-Disk Structure Level 1 or magnetic tapes.

11 The

status from this attribute operation is returned in FIB$L_ACL_STATUS.

12 Not

supported by all ACPs. Maintained on ODS-5 volumes when access dates are enabled using the DCL INITIALIZE
or SET VOLUME commands. Not maintained on ODS-2 volumes.

(continued on next page)

ACPQIO Interface 115

ACPQIO Interface
1.3 ACP Subfunctions
Table 17 (Cont.) ACP-QIO Attributes
Maximum Size
(bytes)

Attribute Name6
ATR$C_ASCNAME

252 (ODS-5)
86 (ODS-2)

Meaning
File name, type, and version, in ASCII, including
punctuation. Format: name.type;version.
Magnetic tape: contains 17-character file identifier
(ANSI a); no version number. Overrides all other
file name and file type specifications if supplied on
input operations. If specified on an access operation
and you want only a value to be returned, specify
(in ATR$W_SIZE) a buffer of greater than 17 bytes.
See Section 1.3.5.2 for additional information.

12

Corresponds to POSIX st_ctime and reflects the

last time a file attribute was modified.

10

File back link pointer.

4 5 8 10

64-bit backup date and time.

Magnetic tape block size.

Offset length for ANSI magnetic tape header label

buffer.

64-bit creation date and time.

ATR$C_ATTDATE

ATR$C_BACKLINK
ATR$C_BAKDATE

ATR$C_BLOCKSIZE
ATR$C_BUFFER_OFFSET

ATR$C_CREDATE2
ATR$C_DELACLENT

ATR$C_DELETE_ALL
ATR$C_DELETEACL

7 10

11

255

Deletes an access control entry pointed to by the

buffer address or, if the buffer address is 0, the
ACE pointed to by a prior ACL$C_FNDACETYP or
ACL$C_FNDACLENT.

7 10 11

255

Delete the entire ACL, including protected entries.

255

Deletes the entire ACL with the exception of

protected ACEs.

7 10 11

10

Directory update sequence count.

ATR$C_ENDLBLAST

End of magnetic tape label processing; provides AST

control block.

ATR$C_EXPDAT2

Expiration date in ASCII. Format: DDMMMYY.

64-bit expiration date and time.

ATR$C_DIRSEQ

ATR$C_EXPDATE

ATR$C_FILE_SPEC

10

4098 (ODS-5)
512 (ODS-2)

Convert FID to file specification. See Section 1.3.5.2

for additional information.

ATR$C_FILNAM

10

6-byte Radix-50 file name plus ATR$C_FILTYP and

ATR$C_FILVER. See Section 1.3.5.2 for additional
information.

ATR$C_FILTYP

2-byte Radix-50 file type plus ATR$C_FILVER. See

Section 1.3.5.2 for additional information.

2 Protected
3 Not

4 Locked
5 For

(can be written to only by system or owner).

supported on write operations to MTAACP; defaults are returned on read operations.

(cannot be written to while the file is locked).

Files-11 C/D, returns 0.

6 Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code and one with an ATR$S_
prefix for the size, which is not included in the list.
7 Exclusive
8 Can

access required. This operation does not complete successfully if other readers or writers are allowed.

be written only by the system, owner, or someone holding READALL privilege.

10 Not

supported for Files-11 On-Disk Structure Level 1 or magnetic tapes.

11 The

status from this attribute operation is returned in FIB$L_ACL_STATUS.

12 Not

supported by all ACPs. Maintained on ODS-5 volumes when access dates are enabled using the DCL INITIALIZE
or SET VOLUME commands. Not maintained on ODS-2 volumes.

(continued on next page)

116 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
Table 17 (Cont.) ACP-QIO Attributes
Maximum Size
(bytes)

Attribute Name6
ATR$C_FILVER

Meaning
2-byte binary version number. See Section 1.3.5.2
for additional information.

ATR$C_FNDACLENT

10 11

255

Locates an ACE pointed to by its buffer address.

ATR$C_FNDACETYP

10 11

255

Locates an ACE of the type pointed to by its buffer

address.

ATR$C_FPRO2

2
10 11

ATR$C_GRANT_ACE

255

ATR$C_HDR1_ACC

ATR$C_HEADER

512
10

ATR$C_HIGHWATER
ATR$C_JOURNAL

10

ATR$C_LINKCOUNT
ATR$C_MATCHING_ACE

ATR$C_MODACLENT

10

7 10 11

ATR$C_MODDATE12
ATR$C_NEXT_ACE

File protection.
Return an ACE that grants or denies access to the
object.
ANSI magnetic tape header label accessibility
character.
Complete file header. This attribute is read only.

High-water mark (user read-only).

Journal control flags.

Count of hardlinks.

255

ACE used to gain access (if any). This attribute can

only be retrieved on the initial file access or create
operation.

255

Replaces the ACE pointed to by a prior ACL$C_

FNDACETYP or ACL$C_FNDACLENT with the
ACE pointed to by its buffer address.

Corresponds to POSIX st_mtime and reflects the

last time data was modified.

10 11

Advance to the next ACE in the ACL.

10

Privileges used to gain access. This attribute can

only be retrieved on the initial file access or create
operation.

ATR$C_PRIVS_USED

ATR$C_READACE

10 11

255

Reads the ACE pointed to by ACL$C_FNDACETYP

or ACL$C_FNDACLENT into the buffer.

ATR$C_READACL

10 11

512

Reads the entire ACL or as much as will fit in

the supplied buffer. Only complete ACEs are
transferred.

32

Record attribute area. Section 1.4 describes the

record attribute area in detail.

ATR$C_RECATTR4
ATR$C_RESERVED
2 4

ATR$C_REVDATE
2 Protected

9 10

380
8

Modifies the reserve area.

64-bit revision date and time.

(can be written to only by system or owner).

4 Locked

(cannot be written to while the file is locked).

6 Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code and one with an ATR$S_
prefix for the size, which is not included in the list.
7 Exclusive
8 Can

access required. This operation does not complete successfully if other readers or writers are allowed.

be written only by the system, owner, or someone holding READALL privilege.

9 The actual length available can decrease if the file is extended in a noncontiguous manner or if an ACL is applied to the
file.
10 Not supported for Files-11 On-Disk Structure Level 1 or magnetic tapes.
11 The

status from this attribute operation is returned in FIB$L_ACL_STATUS.

12 Not

supported by all ACPs. Maintained on ODS-5 volumes when access dates are enabled using the DCL INITIALIZE
or SET VOLUME commands. Not maintained on ODS-2 volumes.

(continued on next page)

ACPQIO Interface 117

ACPQIO Interface
1.3 ACP Subfunctions
Table 17 (Cont.) ACP-QIO Attributes
Maximum Size
(bytes)

Attribute Name6
ATR$C_RPRO

10
10

ATR$C_SEMASK
ATR$C_STATBLK
ATR$C_UCHAR2

2-byte record protection.

File security mask and limit.

32

Statistics block. This attribute is read only.

Section 1.5 describes the statistics block in detail.

4-byte file characteristics. (The file characteristics

bits are listed following this table.)

80

User file label. This attribute is not supported for

disk devices.

ATR$C_USERLABEL

Meaning

ATR$C_UIC2

4-byte file owner UIC.

ATR$C_UIC_RO

4-byte file owner UIC. This attribute is read only.

2 Protected
3 Not

(can be written to only by system or owner).

supported on write operations to MTAACP; defaults are returned on read operations.

6 Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the code and one with an ATR$S_
prefix for the size, which is not included in the list.
10 Not

supported for Files-11 On-Disk Structure Level 1 or magnetic tapes.

Table 18 lists the bits contained in the file characteristics longword, which is
read with the ATR$C_UCHAR attribute.
Table 18 File Characteristics Bits
FCH$M_NOBACKUP

Do not back up file.

FCH$M_READCHECK

Verify all read operations.

FCH$M_WRITCHECK

Verify all write operations.

FCH$M_CONTIGB

Keep file as contiguous as possible.

FCH$M_LOCKED

File is deaccess-locked.

FCH$M_CONTIG

File is contiguous.

FCH$M_BADACL

Files ACL is corrupt.

FCH$M_SPOOL

File is an intermediate spool file.

FCH$M_DIRECTORY

File is a directory.

FCH$M_BADBLOCK

File contains bad blocks.

FCH$M_MARKDEL

File is marked for deletion.

FCH$M_ERASE

Erase file contents before deletion.

FCH$M_ASSOCIATED
FCH$M_EXISTENCE

File has an associated file.

Suppress existence of file.

FCH$M_NOMOVE

Disable movefile operations on this file.

FCH$M_NOSHELVABLE

File is not shelvable.

FCH$M_SHELVED

File is shelved.

1 Files-11

118 ACPQIO Interface

C/D only.

ACPQIO Interface
1.3 ACP Subfunctions
1.3.5.2 Attribute Descriptions
This section contains descriptions of the following attribute codes that are listed
in Table 17:

ATR$C_ASCNAME

ATR$C_FILE_SPEC

ATR$C_FILNAM

ATR$C_FILTYP

ATR$C_FILVER

ATR$C_ASCNAME
The ATR$C_ASCNAME attribute allows the file specification stored in a files
primary file header to be read and written.
Reading the ATR$C_ASCNAME Attribute
For ODS-5 volumes, the file specification is returned in the supplied buffer, and
the name format is returned in the FIB$B_ASCNAME_FORMAT cell.
The format in which the name is returned is controlled by the settings of the
FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags in the same way as the
output file specification parameter. A pseudoname can be returned in place of the
actual file specification if the format is not one of those the calling program can
accept.
Unlike the output file specification parameter, the length of a file specification
contained in the ASCNAME attribute is not passed back explicitly. To determine
the length of the file specification, the calling program must search the attribute
buffer for the first occurrence of the padding character. If neither the FIB$V_
NAMES_8BIT nor the FIB$V_NAMES_16BIT flag is set, the buffer is padded
with space (note that only ODS-2 format names are returned in this case). If one
or more of the flags are set, the attribute buffer is padded with zeros.
Note
The file system does not enforce a minimum length on the attribute
buffer. If the file specification is longer than the attribute buffer, the
value returned is truncated without signaling an error or warning.
In contrast, the file system does enforce a maximum size for the attribute
buffer. Supplying a larger buffer returns a BADPARAM error.

Writing the ATR$C_ASCNAME Attribute

The ASCNAME attribute can only be written for files on ODS-2 or ODS-5 volumes
provided that the FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags are
clear.
The ability to write this attribute is only intended to provide compatibility with
existing applications that do so. New and modified programs should not write
this attribute. Changing its value can prevent a file from being permanently
deleted.
In those cases where it is legal to write the attribute, the contents of the attribute
buffer (up to 252 bytes) are copied to the file name field in the file header. For
ODS-5 headers, the format is set to ODS-2, and the file name length is set to

ACPQIO Interface 119

ACPQIO Interface
1.3 ACP Subfunctions
the offset of the first space character. This can be 252 bytes or the length of the
supplied buffer, whichever is the least.
ATR$C_FILE_SPEC
The FILE_SPEC attribute is a read-only attribute that returns the physical file
specification in the form:
DDnn:[DIR1.DIR2_DIRn]name.type;1
The file name returned is that from the file header, which may be different
from that in the directory. The specification may be incomplete if any errors are
encountered while reading the file headers of any of the directories in the path.
For files on ODS-5 volumes, the path may contain file names that are in any
of the three name formats. This creates a number of problems; for instance,
the presence of periods in a directory name could return an ambiguous path
specification. To avoid this and other problems, the file system makes use of
services provided by RMS to translate the file specification and the components of
the path to their escaped form.
When you access files on an ODS-5 volume from a VAX system in a mixed
architecture OpenVMS system, no escaped forms are returned. For an ODS-2
or ISO Latin-1 file format, the name stored in the file header is returned. For
a UCS-2 file format, a pseudoname is returned, followed by the file identifier in
parentheses. For example:
DKA100:[ABC]\pUNICODE\.??? (10095,5,0)
If the escaped form of the path is longer than can be accommodated by the buffer
for the attribute, one or more directories in the path may be replaced by the DID
of the rightmost of those replaced. This process is identical to that performed by
RMS.
However, if the file specification, even after DID abbreviation, is longer than can
be accommodated by the buffer, the file name is truncated. The file specification
string returned to the user buffer has a 2-byte count prefix. The count contains
the number of bytes for the untruncated file specification. If the count is greater
than the size of the user buffer (minus the two bytes that contain the count), the
user can conclude that the returned file specification has been truncated.
ATR$C_FILNAM, ATR$C_FILTYP, and ATR$C_FILVER
The first two of these attributes allow the file name and file type to be read and
written using Radix-50 encoding. This encoding scheme enables 3 characters to
be packed into a 16-bit word. Only 38 characters in the ODS-2 format set are
valid for Radix-50 names, with the exceptions being dash (-) and underscore (_).
The maximum component lengths of a Radix-50 encoded file specification are:

File name: 15 characters (10 bytes)

File type: 6 characters (4 bytes)

As a result of the additional character and length restrictions, only a subset of

legal ODS-2 file names is expressible in the Radix-50 encoding.
The file system only attempts to read or write the three attributes if the format
of the existing file name in the file header is ODS-2. If this is not the case, a
NORAD50 error will be returned. If the existing file name is in ODS-2 format,
but is incompatible with the Radix-50 encoding or the length limits on Radix-50
file names, a BADFILENAME error will be returned.

120 ACPQIO Interface

ACPQIO Interface
1.3 ACP Subfunctions
The ATR$C_FILVER attribute allows the file version number in the file header
to be read or written as a 2-byte integer. As the process requires the existing file
name to be converted into a Radix-50 file name, the above restriction also applies
to this attribute.

1.4 ACP-QIO Record Attributes Area

Figure 15 shows the format of the record attributes area.
Figure 15 ACP-QIO Record Attributes Area
31

24 23

16 15

FAT$W_RSIZE

8 7

FAT$B_RATTRIB

0
FAT$B_RTYPE*
4

FAT$L_HIBLK
8

FAT$L_EFBLK

12
FAT$B_VFCSIZE

FAT$B_BKTSIZE

FAT$W_FFBYTE
16

FAT$W_DEFEXT

FAT$W_MAXREC
20
FAT$W_GBC
24

(6 Bytes Reserved for Future Use)

FAT$W_VERSIONS

28

Not Used

*FAT$V_RTYPE Bits 03; FAT$V_FILEORG Bits 47

ZK0641GE

Table 19 lists the record attributes values and their meanings.

Table 19 ACP Record Attributes Values
Field Value

Meaning

FAT$B_RTYPE

Record type. Contains FAT$V_RTYPE and

FAT$V_FILEORG.

FAT$V_RTYPE

Record type. The following bit values are defined:

FAT$C_FIXED

Fixed-length record

FAT$C_VARIABLE

Variable-length record

FAT$C_VFC

Variable-length record with fixed

control

FAT$C_UNDEFINED

Undefined record format (stream

binary)

FAT$C_STREAM

RMS stream format

FAT$C_STREAMLF

Stream terminated by LF

FAT$C_STREAMCR

Stream terminated by CR
(continued on next page)

ACPQIO Interface 121

ACPQIO Interface
1.4 ACP-QIO Record Attributes Area
Table 19 (Cont.) ACP Record Attributes Values
Field Value

Meaning

FAT$V_FILEORG

File organization. The following bit values are defined:

FAT$B_RATTRIB

FAT$C_DIRECT

Direct file organization1

FAT$C_INDEXED

Indexed file organization

FAT$C_RELATIVE

Relative file organization

FAT$C_SEQUENTIAL

Sequential file organization

Record attributes. The following bit values are defined:

FAT$M_FORTRANCC

Fortran carriage control

FAT$M_IMPLIEDCC

Implied carriage control

FAT$M_PRINTCC

Print file carriage control

FAT$M_NOSPAN

No spanned records
4

FAT$M_MSBRCW
FAT$W_RSIZE

Record count word (RCW) is MSB

formatted

Record size in bytes.

2

Highest allocated VBN. The ACP maintains this field when the
file is extended or truncated. Attempts to modify this field in a
write attributes operation are ignored.

FAT$L_HIBLK

FAT$L_EFBLK2

FAT$W_HIBLKH

High-order 16 bits

FAT$W_HIBLKL

Low-order 16 bits

End-of-file VBN
FAT$W_EFBLKH

High-order 16 bits

FAT$W_EFBLKL

Low-order 16 bits

FAT$W_FFBYTE3

First free byte in FAT$L_EFBLK.

FAT$B_BKTSIZE

Bucket size in blocks.

FAT$B_VFCSIZE

Size in bytes of fixed-length control for VFC records.

FAT$W_MAXREC

Maximum record size in bytes.

FAT$W_DEFEXT

Default extend quantity.

FAT$W_GBC

Global buffer count.

FAT$W_VERSIONS

Default version limit; valid only if the file is a directory.

1 Defined

but not implemented.

2 Inverted

format field. The high- and low-order 16 bits are transposed for compatibility with PDP-11
software.
3 When the end-of-file position corresponds to a block boundary, by convention
FAT$L_EFBLK contains the end-of-file VBN plus 1, and FAT$W_FFBYTE contains 0.
4 Variable-length

record format (FAT$C_VARIABLE) only.

1.5 ACPQIO Attributes Statistics Block

Figure 16 shows the format of the attributes statistics block. Table 110 lists
the contents of this block.

122 ACPQIO Interface

ACPQIO Interface
1.5 ACPQIO Attributes Statistics Block
Figure 16 ACPQIO Attributes Statistics Block
31

16 15

87

SBK$L_STLBN
SBK$L_FILESIZE
SBK$L_FCB

SBK$B_LCNT

SBK$B_ACNT

(Not Used)
SBK$W_LCNT

SBK$W_ACNT

SBK$W_TCNT

SBK$W_WCNT
SBK$L_READS
SBK$L_WRITES
ZK0642GE

ACPQIO Interface 123

ACPQIO Interface
1.5 ACPQIO Attributes Statistics Block

Table 110 Contents of the Statistics Block

Field

Subfields

SBK$L_STLBN

Contains the starting LBN of the file if the file is

contiguous. If the file is not contiguous, this field
contains a value of 0. The LBN appears as an
inverted longword (the high- and low-order 16 bits are
transposed for PDP-11 compatibility). The following
subfields are defined:
SBK$W_STLBNH

Starting LBN (high-order 16 bits)

SBK$W_STLBNL

Starting LBN (low-order 16 bits)

SBK$L_FILESIZE

SBK$B_ACNT

Meaning

Contains the size of the file in blocks. The file

size appears as an inverted longword (the highand low-order 16 bits are transposed for PDP-11
compatibility). The following subfields are defined:
SBK$W_FILESIZH

File size (high-order 16 bits)

SBK$W_FILESIZL

File size (low-order 16 bits)

Access count (low byte). Field is for PDP-11

compatibility.

SBK$B_LCNT1

Lock count (low byte). Field is for PDP-11

compatibility.

SBK$L_FCB

System pool address of the files file control block.

SBK$W_ACNT

Access count (number of channels with file open

currently).

SBK$W_LCNT1

Lock count (the number of access operations that have

locked the file against writers).

SBK$W_WCNT1

Writer count (the number of channels that currently

have the file open for write).

SBK$W_TCNT1

Truncate lock count (the number of access operations

that have locked the file against truncation).

SBK$L_READS

Number of read operations executed for the file on

this channel.

SBK$L_WRITES

Number of write operations executed for the file on

this channel.

1 Accesses

from processes on the local node in a cluster are counted.

1.6 Major Functions

The following sections describe the operation of the major ACP functions. Each
section describes the required and optional parameters for a particular function,
as well as the sequence in which the function is performed. For clarity, when
a major function invokes a subfunction, the input parameters used by the
subfunction are omitted.

124 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
1.6.1 Create File
Create file is a virtual I/O function that creates a directory entry or a file on a
disk device, or a file on a magnetic tape device.
The following is the function code:

IO$_CREATE

The following are the function modifiers:

IO$M_CREATECreates a file.

IO$M_ACCESSOpens the file on your channel.

IO$M_DELETEMarks the file for deletion (applicable only to disk devices).

1.6.1.1 Input Parameters

The following are the device- or function-dependent arguments for
IO$_CREATE:

P1The address of the file information block (FIB) descriptor.

P2The address of the file name string descriptor (optional).

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

P4The address of a descriptor for a buffer that is to receive the resultant

file name string (optional).

P5The address of a list of attribute descriptors (optional).

Table 111 lists fields in the FIB that are applicable to the IO$_CREATE
operation.
Table 111 IO$_CREATE and the FIB
Field

Subfields

FIB$L_ACCTL

Meaning
Specifies field values that control access to the file. The
following bits are applicable to the IO$_CREATE function:

FIB$V_REWIND

Set to rewind magnetic tape before creating the file. Any data
currently on the tape is overwritten.

FIB$V_CURPOS

Set to create magnetic tape file at the current tape position.

(Note: a magnetic tape file is created at the end of the volume
set if neither FIB$V_REWIND nor FIB$V_CURPOS is set.) If
the tape is not positioned at the end of a file, FIB$V_CURPOS
creates a file at the next file position. Any data currently on
the tape past the current file position is overwritten.

FIB$V_
WRITETHRU

Specifies that the file header is to be written back to the disk.

If not specified and the file is opened, writing of the file header
can be deferred to some later time.

FIB$W_
CNTRLFUNC

Specifies the following value, which allows you to control

actions subsequent to EOT detection on a magnetic tape file.

FIB$W_FID

Contains the file ID of the file created or entered.

FIB$W_DID

Contains the file identifier of the directory file.

(continued on next page)

ACPQIO Interface 125

ACPQIO Interface
1.6 Major Functions
Table 111 (Cont.) IO$_CREATE and the FIB
Field

Subfields

FIB$W_NMCTL

Meaning
Controls the processing of the file name in a directory
operation. The following bits are applicable to the IO$_
CREATE function:

FIB$V_NEWVER

Set to create a file of the same name with the next higher
version number. Only for disk devices.

FIB$V_
SUPERSEDE

Set to supersede an existing file of the same name, type, and

version. Only for disk devices.

FIB$V_LOWVER

Set on return if a lower numbered version of the file exists.

Only for disk devices.

FIB$V_HIGHVER

Set on return if a higher numbered version of the file exists.

Only for disk devices.

FIB$W_VERLIMIT

Specifies the version limit for the directory entry created.

Used only for disk devices and only when the first version of
a new file is created. If 0, the directory default is used. If a
directory operation was performed, FIB$W_VERLIMIT always
contains the actual version limit of the file.

FIB$L_ACL_
STATUS

Status of the requested ACL attribute operation, if any.

The ACL attributes are included in Table 17. If no ACL
attributes are given, SS$_NORMAL is returned here.

1.6.1.2 Disk ACP Operation

If the modifier IO$M_CREATE is specified, a file is created. The file ID of the file
created is returned in FIB$W_FID. If the modifier IO$M_DELETE is specified,
the file is marked for deletion.
If a nonzero directory ID is specified in FIB$W_DID, a directory entry is created.
The file name specified by parameter P2 is entered in the directory, together with
the file ID in FIB$W_FID. (Section 1.3.1.1 describes the format for the file name
string.) Wildcards are not permitted. Negative version numbers are treated as
equivalent to a 0 version number. If a result string buffer and length are specified
by P3 and P4, the actual file name entered, and its length, are returned.
The version number of the file receives the following treatment:

If the version number in the specified file name is 0 or negative, the directory
entry created gets a version number one greater than the highest previously
existing version of that file (or version 1 if the file did not previously exist).

If the version number in the specified file name is a nonzero number and
FIB$V_NEWVER is set, the directory entry created gets a version number
one greater than the highest previously existing version of that file, or the
specified version number, whichever is greater.

If the version number in the specified file name is a nonzero number

and the directory already contains a file of the same name, type,
and version, the previously existing file is set aside for deletion if
FIB$V_SUPERSEDE is specified. If FIB$V_SUPERSEDE is not specified, the
create operation fails with a SS$_DUPFILNAM status.

If, after creating the new directory entry, the number of versions of the
file exceeds the version limit, the lowest numbered version is set aside for
deletion.

126 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions

If the file did not previously exist, the new directory entry is
given a version limit as follows: the version limit is taken from
FIB$W_VERLIMIT if it is a nonzero number; if it is 0, the version
limit is taken from the default version limit of the directory file; if the
default version limit of the directory file is 0, the version limit is set to
32,767 (the highest possible number).

The file name string entered in the directory is returned using the P3
and P4 result string parameters, if present. The file name string is
also written into the header. If no directory operation was requested
(FIB$W_DID is 0), the file name string specified by P2, if any, is written
into the file header.
If an attribute list is specified by P5, a write attributes subfunction is performed
(see Section 1.3.5).
If the modifier IO$M_ACCESS is specified, the file is opened (see
Section 1.3.2).
If the extend enable bit FIB$V_EXTEND is specified in the FIB, an extend
subfunction is performed (see Section 1.3.3).
Finally, if a file was set aside for deletion (IO$M_DELETE is specified), that file
is deleted. If the file is deleted because the FIB$V_SUPERSEDE bit was set, the
alternate success status SS$_SUPERSEDE is returned in the I/O status block. If
the file is deleted because the version limit was exceeded, the alternate success
status SS$_FILEPURGED is returned.
If an error occurs in the operation of an IO$_CREATE function, all actions
performed to that point are reversed (the file is neither created nor changed), and
the error status is returned to the user in the I/O status block.
1.6.1.3 Directory Entry Creation
Creating a new version of a file eliminates default access to the previously highest
version of the file. For example, creating RESUME.TXT;4 masks RESUME.TXT;3
so the DCL command TYPE RESUME.TXT yields the contents of version 4, not
version 3. To protect the contents of the earlier version of a file, the creator of a
file must have write access to the previous version of a file of the same name.
1.6.1.4 Magnetic Tape ACP Operation
No operation is performed unless the IO$M_CREATE modifier is specified.
The magnetic tape is positioned as specified by FIB$V_REWIND and FIB$V_
CURPOS, and the file is created. The name specified by the P2 parameter is
written into the file header label.
If P5 specifies an attribute list, a write attributes subfunction is performed (see
Section 1.3.5).
If the modifier IO$M_ACCESS is specified, the file is opened (see Section 1.3.2).

1.6.2 Access File

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 following is the function code:

IO$_ACCESS

The following are the function modifiers:

IO$M_CREATECreates a file.
ACPQIO Interface 127

ACPQIO Interface
1.6 Major Functions

IO$M_ACCESSOpens the file on your channel.

1.6.2.1 Input Parameters

The following are the device- or function-dependent arguments for
IO$_ACCESS:

P1The address of the file information block (FIB) descriptor.

P2The address of the file name string descriptor (optional).

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

P4The address of a descriptor for a buffer that is to receive the resultant

file name string (optional).

P5The address of a list of attribute descriptors (optional).

Table 112 lists FIB fields that are applicable to the IO$_ACCESS operation.
Table 112 IO$_ACCESS and the File Information Block
Field

Subfields

Meaning

FIB$W_CNTRLFUNC

Specifies the value that allows the user to control

actions subsequent to EOT detection on a magnetic
tape file.

FIB$W_VERLIMIT

Receives the version limit for the file. Applicable

only if FIB$W_DID is a nonzero number (if a
directory lookup is done). Used only for disk devices.

FIB$L_ACL_STATUS

Status of the requested ACL attribute operation, if

any. The ACL attributes are included in Table 17.
If no ACL attributes are given, SS$_NORMAL is
returned here. (For Files-11 C/D, this field is always
set to SS$_NORMAL.)

FIB$L_STATUS

Alternate access status. The following bits are

supported:

FIB$L_ALT_ACCESS

FIB$V_ALT_REQ

Set to indicate whether the alternate access bit is

required for the current operation. If not set, the
alternate access bit is optional.

FIB$V_ALT_GRANTED

If FIB$V_ALT_REQ = 0 and the alternate access

check succeeded, the FIB bit returned from the file
system is set.
A 32-bit mask that represents an access mask
to check against file protection; for example, to
open a file for read and to check whether it can be
deleted. The mask has the same configuration as
the standard protection mask.

1.6.2.2 Operation
If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction is
performed (see Section 1.3.1.) The version limit of the file found is returned in
FIB$W_VERLIMIT.
If the directory search fails with a file not found condition and the
IO$M_CREATE function modifier is specified, the function is reexecuted as a
CREATE. In that case, the argument interpretations for IO$_CREATE, rather
than those for IO$_ACCESS, apply.

128 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
If IO$M_ACCESS is specified, an access subfunction is performed to open the file
(see Section 1.3.2).
If P5 specifies an attribute list, a read attributes subfunction is performed (see
Section 1.3.5).

1.6.3 Deaccess File

Deaccess file is a virtual I/O function that deaccesses a file and, if specified, writes
final attributes in the file header.
The following is the function code:

IO$_DEACCESS

IO$_DEACCESS takes no function modifiers.

1.6.3.1 Input Parameters
The following are the device- or function-dependent arguments for
IO$_DEACCESS:

P1The address of the file information block (FIB) descriptor.

P5The address of a list of attribute descriptors (optional).

The following FIB fields are applicable to the IO$_DEACCESS function:

Field

Meaning

FIB$W_FID

File ID of the file being deaccessed. This field can contain a

value of 0. If it does not, it must match the file identifier of the
accessed file.

FIB$L_ACL_STATUS

Status of the requested ACL attribute operation, if any. The

ACL attributes are included in Table 17. If no ACL attributes
are given, SS$_NORMAL is returned here. (For Files-11 C/D,
this field is always set to SS$_NORMAL.)

1.6.3.2 Operation
For disk files, if P5 specifies an attribute control list and the file was accessed for
a write operation, a write attributes subfunction is performed (see Section 1.3.5).
If the file was opened for write, no attributes were specified, and FIB$V_DLOCK
was set when the file was accessed, the deaccess lock bit is set in the file header,
inhibiting further access to that file.
For disk files, if the truncate enable bit FIB$V_TRUNC is specified in the FIB, a
truncate subfunction is performed (see Section 1.3.4).
Finally, the file is closed. Trailer labels are written for a magnetic tape file that
was opened for write.

1.6.4 Modify File

Modify file is a virtual I/O function that modifies the file attributes or allocation
of a disk file. The IO$_MODIFY function is not applicable to magnetic tape; that
is, the function returns success, but no action is performed.
The following is the function code:

IO$_MODIFY

The following is the function modifier:

IO$M_MOVEFILE

ACPQIO Interface 129

ACPQIO Interface
1.6 Major Functions
1.6.4.1 Input Parameters
The following are the device- or function-dependent arguments for
IO$_MODIFY:

P1The address of the file information block (FIB) descriptor.

P2The address of the file name string descriptor (optional). If specified, the
directory is searched for the name.

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

P4The address of a descriptor for a buffer that is to receive the resultant

file name string (optional).

P5The address of a list of attribute descriptors (optional).

The following FIB fields are applicable to the IO$_MODIFY function:

Field

Subfields

FIB$L_ACCTL

Meaning
Specifies field values that control access to the file.
The following bit is applicable to the IO$_MODIFY
function:

FIB$V_WRITETHRU

Specifies that the file header is to be written back

to the disk. If not specified and the file is currently
open, writing of the file header can be deferred to
some later time.

FIB$W_VERLIMIT

If a nonzero number, specifies the version limit for

the file.

FIB$L_ACL_STATUS

Status of the requested ACL attribute operation, if

any. The ACL attributes are included in Table 17.
If no ACL attributes are given, SS$_NORMAL is
returned here.

1.6.4.2 Operation
If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is
executed (see Section 1.3.1). If a nonzero version limit is specified in
FIB$W_VERLIMIT and the directory entry found is the latest version of that file,
the version limit is set to the value specified.
If P5 specifies an attribute list, a write attributes subfunction is performed (see
Section 1.3.5).
The file can be either extended or truncated. If FIB$V_EXTEND is specified
in the FIB, an extend subfunction is performed (see Section 1.3.3). If FIB$V_
TRUNC is specified in the FIB, a truncate subfunction is performed (see
Section 1.3.4). Extend and truncate operations cannot be performed at the
same time.

1.6.5 Delete File

Delete file is a virtual I/O function that removes a directory entry or file header
from a disk volume.
The following is the function code:

IO$_DELETE

130 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
The following is the function modifier:

IO$M_DELETEDeletes the file (or marks it for deletion).

The following are the device- or function-dependent arguments for

IO$_DELETE:

P1The address of the file information block (FIB) descriptor.

P2The address of the file name string descriptor (optional).

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

P4The address of a descriptor for a buffer that is to receive the resultant

file name string (optional).

The following FIB fields are applicable to the IO$_DELETE function:

Field

Subfields

FIB$L_ACCTL

Meaning
Specifies field values that control access to the file. The
following bit is applicable to the IO$_DELETE function.

FIB$V_NOLOCK (Alpha
only)

Allows the caller to mark a file for delete that is

currently open for write access. When the file is closed,
it is automatically deleted. The file cannot be accessed
by new callers after it has been marked for delete.

FIB$V_WRITETHRU

Specifies that the file header is to be written back to

the disk. If not specified and the file is currently open,
writing of the file header can be deferred to some later
time.

FIB$W_DID

Contains the file identifier of the directory file. This

field must be a nonzero number.

FIB$W_FID

Specifies the file identification to be deleted.

1.6.5.1 Operation
If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is
performed (see Section 1.3.1). The file name located is removed from the directory.
If the function modifier IO$M_DELETE is specified, the file is marked for
deletion. If the file is not currently open, it is deleted immediately. If the file
is open, it is deleted when the last accessor closes it.

1.6.6 Movefile Subfunction

The movefile subfunction permits you to move the contents of a file, or part of the
contents of a file, to a new disk location. This subfunction can, for example, form
the basis of a disk defragmentation application.
You can disable movefile operations on specific user files by specifying the
/NOMOVE qualifier on the SET FILE command. Use the DIRECTORY/FULL
and the DUMP/HEADER commands to find out if movefile operations are disabled
on a file.
1.6.6.1 Calling the Movefile Subfunction
A program can invoke a movefile subfunction by issuing a QIO request using
the function code IO$_MODIFY and the function modifier IO$M_MOVEFILE.
This section describes the various input parameters that control the processing of
movefile operations together with an operational description.

ACPQIO Interface 131

ACPQIO Interface
1.6 Major Functions
1.6.6.2 Input Parameters
Table 113 lists the FIB fields that control the processing of a movefile
subfunction.
Table 113 FIB Fields (Movefile)
Field

Subfields

FIB$L_ACCTL

Meaning
Movefile control flag. The following flags are
applicable:

FIB$V_NOVERIFY

Inhibits comparison of the moved blocks. If this

flag is clear, the movefile operation verifies that the
operation was carried out correctly by comparing the
moved blocks to the original blocks.

FIB$V_CHANGE_VOL

Enables the movefile operation to move blocks from

one volume to another within a volume set.
The movefile operation clears this flag if the
specified file is a directory.

FIB$W_FID

Specifies the file identification of the file to be

moved.

FIB$W_EXCTL

Movefile control flags. The following flags apply to

the movefile operation. All other FIB$W_EXCTL
flags must be clear.
FIB$V_ALCON

Specifies that the movefile operation must allocate

contiguous disk space to the moved blocks. If the
necessary contiguous space is not available, the
movefile operation fails.
The movefile operation sets this flag if the file was
previously marked as contiguous.

FIB$V_ALCONB

Specifies that the movefile operation should attempt

to allocate contiguous disk space to the moved
blocks. That is, if the movefile operation cannot
allocate contiguous space to all the moved blocks, it
allocates contiguous space to as many of the blocks
as possible.
The movefile operation sets this flag if the file was
previously marked as contiguous best try.

FIB$V_FILCON

Specifies that the entire file must be made

contiguous. Do not set this flag without also setting
the FIB$V_ALCON flag.
If the FIB$V_FILCON flag is set, and either the
FIB$V_ALCON flag is clear or the file would not
be made contiguous by moving the specified virtual
blocks, the movefile operation fails.
The movefile operation sets this flag if the file was
previously marked as contiguous.
(continued on next page)

132 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
Table 113 (Cont.) FIB Fields (Movefile)
Field

Subfields

Meaning

FIB$V_NOPLACE

Specifies that placement information will not be

recorded in the file header.
If this flag is clear and you specify exact placement
for the moved blocks, placement information for
those blocks will be recorded in the file header. If
this flag is set, the placement information will not
be recorded.
You specify exact placement through
the FIB$V_EXACT, FIB$C_LBN, and
FIB$L_LOC_ADDR fields.

FIB$B_ALOPTS

Flags that control the placement of the allocated

blocks. Currently, only the FIB$V_EXACT flag
applies to the movefile operation. All other FIB$B_
ALOPTS flags must be clear. The following flags are
applicable:
FIB$V_EXACT

Set to require exact placement. If this flag is set and

the specified blocks are not available, the movefile
operation fails.

FIB$B_ALALIGN

Contains the interpretation mode of the allocation

field (FIB$W_ALLOC). You can specify a field value
of 0 or you can specify the symbolic value FIB$C_
LBN. If you specify zero, the allocation field is
ignored.

FIB$W_ALLOC

Contains the desired location of the blocks being

allocated. Interpretation of the field is controlled by
the FIB$B_ALALIGN field. The following subfields
are defined:

FIB$L_MOV_SVBN

FIB$B_LOC_RVN

Specifies the relative volume number (RVN) of the

volume to which the blocks are moved. Do not
specify a value for this field unless you have set the
FIB$V_CHANGE_VOL flag.

FIB$L_LOC_ADDR

If the FIB$C_LBN and FIB$V_EXACT flags are set,

specifies the starting logical address to which the
blocks are moved.
Specifies the virtual block number (VBN) of the first
block to be moved.
The starting VBN must correspond to the first block
of a disk cluster. The value must be greater than 0
and it must not exceed the number of virtual blocks
allocated to the file. If you specify an invalid value,
the movefile operation fails.
(continued on next page)

ACPQIO Interface 133

ACPQIO Interface
1.6 Major Functions
Table 113 (Cont.) FIB Fields (Movefile)
Field

Subfields

FIB$L_MOV_VBNCNT

Meaning
Specifies the number of consecutive virtual blocks to
be moved.
This value must be a multiple of the disk cluster
size, and it must not exceed the difference between
the greatest VBN allocated to the file and the
FIB$L_MOV_SVBN value. If you specify a value
of 0, the movefile operation moves all the virtual
blocks between the FIB$L_MOV_SVBN value and
the greatest VBN.
If you specify an invalid value, the movefile
operation fails.

1.6.6.3 Operation
A program can perform a movefile operation on a file if the following conditions
are met:

The program has write and control access to the file.

The file is closed.

Movefile operations are not disabled on the file.

Movefile operations are automatically disabled on critical system files.
You can disable movefile operations on specific user files by specifying the
/NOMOVE qualifier with the SET FILE command.

The operation is not interrupted.

If the movefile operation is interrupted by any other operation, such as a read
or write operation, the movefile operation aborts and the file remains in its
original position.

The movefile operation moves a specified number of consecutive virtual blocks

to new logical blocks on disk, beginning with the virtual block specified in the
FIB$L_SVBN field.
The number of blocks moved is specified in the FIB$L_VBNCNT field. To move
an entire file, specify FIB$L_VBNCNT as 0 and FIB$L_SVBN as 1.
To specify a starting logical block for the moved blocks, specify the logical block
address in the FIB$L_LOC_ADDR subfield and set the FIB$C_LBN and the
FIB$V_EXACT flags.
To move the blocks to another volume, or move blocks that span more than one
volume, set the FIB$V_CHANGE_VOL flag of the FIB$L_ACCTL field. Use the
FIB$B_LOC_RVN subfield of the FIB$W_ALLOC field to specify the volume to
which the blocks are moved. If you do not specify a volume, the blocks are moved
to the volume containing the first virtual block. Note that you cannot move blocks
of a directory file to another volume.
If the file was previously marked as contiguous, the movefile operation sets the
FIB$V_ALCON, FIB$V_ALCONB, and FIB$V_FILCON flags. This ensures that
a contiguous file is not fragmented by a movefile operation.
For virtual blocks beyond the files highwater mark, the movefile operation
allocates new logical blocks but does not copy the contents. The position of the
files highwater mark remains unchanged.

134 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
1.6.7 Mount
On VAX and Alpha systems, mount is a virtual I/O function that informs the ACP
when a disk or magnetic tape volume is mounted. MOUNT privilege is required.
IO$_MOUNT takes no arguments or function modifiers. This function is part of
the volume mounting operation only, and it is not meant for general use. Most
of the actual processing is performed by the MOUNT command or the Mount
Volume ($MOUNT) system service.

1.6.8 ACP Control

ACP Control is a virtual I/O function that performs miscellaneous control
functions, depending on the arguments specified.
The following is the function code:

IO$_ACPCONTROL

The following is the function modifier:

IO$M_DMOUNTDismounts a volume.

1.6.8.1 Input Parameters

The following are the device- or function-dependent arguments for
IO$_ACPCONTROL:

P1The address of the file information block (FIB) descriptor.

P2The address of the file name string descriptor (optional).

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

P4The address of a descriptor for a buffer that is to receive the resultant

file name string (optional).

Table 114 lists FIB fields that control the processing of the
IO$_ACPCONTROL function.
Table 114 IO$_ACPCONTROL and the FIB
Field

Subfields

Meaning

FIB$W_CNTRLFUNC

Specifies the control function to be performed. This

field overlays FIB$W_EXCTL.

FIB$L_CNTRLVAL1

Specifies additional function-dependent data. This

field overlays FIB$L_EXSZ.

FIB$L_ACL_STATUS

Status of the requested ACL attribute operation, if

any. The ACL attributes are included in Table 17.
If no ACL attributes are given, SS$_NORMAL is
returned here. For Files-11 C/D, this field is always
set to SS$_NORMAL.

FIB$L_STATUS1

Alternate access status. The following bits are

supported:
FIB$V_ALT_REQ

1 Not

Set to indicate whether the alternate access bit is

required for the current operation. If not set, the
alternate access bit is optional.

supported or invalid for Files-11 C/D.

(continued on next page)

ACPQIO Interface 135

ACPQIO Interface
1.6 Major Functions
Table 114 (Cont.) IO$_ACPCONTROL and the FIB
Field

Subfields

Meaning

FIB$V_ALT_GRANTED

If FIB$V_ALT_REQ = 0 and the alternate access

check succeeded, the FIB bit returned from the file
system is set.

FIB$L_ALT_ACCESS1

1 Not

A 32-bit mask that represents an access mask to

check against file protection; for example, to open a
file for read and to check whether it can be deleted
or not. The mask has the same configuration as the
standard protection mask.

supported or invalid for Files-11 C/D.

1.6.8.2 Magnetic Tape Control Functions

Table 115 lists the FIB field applicable to magnetic tape operations.
Table 115 Magnetic Tape Operations and the FIB
Field

Subfields

FIB$W_CNTRLFUNC

Meaning
Several ACP control functions are used for magnetic
tape positioning. These functions are specified
by supplying a FIB with P1 containing the FIB
descriptor address. Modifiers and parameters P2,
P3, and P4 are not allowed. These functions clear
serious exceptions in magnetic tape drivers. The
following control functions can be specified to control
magnetic tape positioning:

FIB$C_REWINDFIL

Rewind to beginning-of-file.

FIB$C_REWINDVOL

Rewind to beginning-of-volume set.

FIB$C_POSEND

Position to end-of-volume set.

FIB$C_NEXTVOL

Force next volume.

FIB$C_SPACE

Space n blocks forward or backward. The FIB$L_

CNTRLVAL field specifies the number of magnetic
tape blocks to space forward if positive or to space
backward if negative.

FIB$C_CLSEREXCP

If set, clears the serious exception in the magnetic

tape driver (see FIB$C_USEREOT in Section 1.6.1
and Section 1.6.2). If writing, allows you to write
data blocks beyond the EOT marker, which can
result in the magnetic tape not conforming to
the ANSI standard for magnetic tapes (see ANSI
Standard X3.271978). If reading, allows you to
handle the move to the next volume or to stop
reading the tape. Do not attempt to read past EOV.

1.6.8.3 Miscellaneous Disk Control Functions

Several ACP control functions are available for disk volume control. The following
function does not use parameters P2, P3, and P4:

136 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
IO$M_DMOUNT

Specifying the dismount modifier on the IO$_ACPCNTRL

function executes a dismount QIO. No parameters in the
FIB are used; the FIB can be omitted. This function does
not perform a dismount by itself, but is used to synchronize
the ACP with the DISMOUNT command and the Dismount
Volume ($DISMOUNT) system service.

The FIB$W_CNTRLFUNC field of the FIB specifies the following miscellaneous

control functions (with no modifier on the IO$_ACPCONTROL function code).
These functions use no other parameters.
FIB$C_REMAP

Remap a file. The file window for the file open on the users
channel is remapped so that it maps the entire file.

FIB$C_LOCK_VOL

Allocation lock the volume. Operations that change the file

structure, such as file creation, deletion, extension, and
deaccess, are not permitted. If such requests are queued to
the file system for an allocation-locked volume, they are not
processed until the FIB$C_UNLK_VOL function is issued to
unlock the volume.
To issue the FIB$C_LOCK_VOL function, you must have
either a system UIC or SYSPRV privilege, or be the owner of
the volume.

FIB$C_UNLK_VOL

Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue

this function, you must have either a system UIC or SYSPRV
privilege, or be the owner of the volume.

1.6.8.4 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 volumes
master file directory (MFD) under the name QUOTA.SYS;1. This section
describes the control functions that operate on the quota file.
Table 116 lists the enable and disable quota control functions.
Table 116 Disk Quota Functions (Enable/Disable)
Value

Meaning

FIB$C_ENA_QUOTA

Enable the disk quota file. If a nonzero directory file ID is specified in

FIB$W_DID, a lookup subfunction is performed to locate the quota file (see
Section 1.3.1). To issue this function, you must have either a system UIC
or SYSPRV privilege, or be the owner of the volume.
The quota file specified by FIB$W_FID, if present, is accessed by the ACP,
and quota enforcement is turned on. By convention, the quota file is named
[0,0]QUOTA.SYS;1. Therefore, FIB$W_DID should contain the value 4,4,0
and the name string specified with P2 should be QUOTA.SYS;1.

FIB$C_DSA_QUOTA

Disable the disk quota file. The quota file is deaccessed and quota
enforcement is turned off. To issue this function, you must have either
a system UIC or SYSPRV privilege, or be the owner of the volume.

ACPQIO Interface 137

ACPQIO Interface
1.6 Major Functions
Table 117 lists the quota control functions that operate on individual entries in
the quota file. Each operation transfers quota file data to and from the ACP using
a quota data block. This block has the same format as a record in the quota file.
Figure 17 shows the format of this block.
Table 117 Disk Quota Functions (Individual Entries)
Value

Meaning

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.

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 search through the quota file using wildcards. The two
flags are:
FIB$V_ALL_MEM

Match all UIC members

FIB$V_ALL_GRP

Match all UIC groups

The ACP maintains position context in FIB$L_WCC. On the first examine

call, you specify 0 in FIB$L_WCC; the ACP returns a nonzero value so that
each succeeding examine call returns the next matching entry.
Read access to the quota file is required to examine all non-user entries.
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 the following three flags in FIB$L_CNTRLVAL:
FIB$V_MOD_PERM

Change the permanent quota

FIB$V_MOD_OVER

Change the overdraft quota

FIB$V_MOD_USE

Change the usage data

The usage data can be changed only if the volume is locked by FIB$C_
LOCK_VOL (see Section 1.6.8.3). FIB$C_MOD_QUOTA requires write
access to the quota file.
The P3 and P4 arguments return the modified quota entry to you.
By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can
search through the quota file using wildcards just as you would with the
FIB$C_EXA_QUOTA function.
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 P3 and P4 arguments return the removed quota file entry to you.
By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can
search through the quota file using wildcards just as you would with the
FIB$C_EXAQUOTA function.

138 ACPQIO Interface

ACPQIO Interface
1.6 Major Functions
Figure 17 Quota File Transfer Block
31

0
Flags Longword (DQF$L_FLAGS)
User Identification Code (DQF$L_UIC)
Current Usage (DQF$L_USAGE)
Permanent Quota (DQF$L_PERMQUOTA)
Overdraft Limit (DQF$L_OVERDRAFT)
(Reserved for Future Use)

ZK0643GE

IO$_ACPCONTROL functions that transfer quota file data between the caller and
the ACP use the following device- or function-dependent arguments:

P2The address of a descriptor for the quota data block being sent to the
ACP.

P3The address of a word that returns the data length.

P4The address of a descriptor for a buffer to receive the quota data block
returned from the ACP.

1.7 I/O Status Block

Figure 18 shows the I/O status block (IOSB) for ACPQIO functions.
Appendix A lists the status returns for these functions. (The OpenVMS system
messages documentation provides explanations and suggested user actions for
these returns.)
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 the number of blocks
allocated to the file. If a contiguous extend operation (FIB$V_ALCON) fails, the
second longword is used to return the size of the file after truncation.
Values returned in the IOSB are most useful during operations in compatibility
mode. When executing programs in the native mode, use the values returned in
FIB locations.
Figure 18 IOSB ContentsACP-QIO Functions
+2
Not Used

IOSB
Status
+4
ZK0644GE

ACPQIO Interface 139

ACPQIO Interface
1.7 I/O Status Block
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.

140 ACPQIO Interface

2
Disk Drivers
This chapter describes the use of disk drivers that support the disk devices listed
in the Software Product Description for the OpenVMS Operating System for Alpha
and VAX. The chapter also includes descriptions of many of the supported disks
and controllers; however, not all supported devices are described here. Refer to
the Software Product Description for the OpenVMS Operating System for Alpha
and VAX for the definitive list of supported devices.
All disk drivers support Files-11 On-Disk Structure Level 1 and Level 2 file
structures. Access to these file structures is through the DCL commands
INITIALIZE and MOUNT, followed by the RMS calls described in the OpenVMS
Record Management Services Reference Manual. Files in RT-11 format can be
read or written with the file exchange facility EXCHANGE.

2.1 Supported Disk Devices and Controllers

The following sections provide descriptions of disk devices.
To obtain more information about a device, use the DCL command SHOW
DEVICE with the /FULL qualifier, the Get Device/Volume Information
($GETDVI) system service (from a program), or the F$GETDVI lexical function
(in a command line or command procedure). Section 2.3 lists the information on
disk devices returned by $GETDVI.

2.1.1 UDA50 UNIBUS Disk Adapter

The UDA50 UNIBUS Disk Adapter is a microprocessor-based disk controller for
mass storage devices that implements the DIGITAL Storage Architecture (DSA);
for more information on the DSA, see Section 2.2.3.
The UDA50 controller is used to connect any combination of four RA60, RA80,
and RA81 disk drives to the UNIBUS. Two UDA50 controllers can be attached to
a single UNIBUS for a maximum of eight disk drives per UNIBUS. On the VAX11/780 processor, the operating system supports one UDA50 on the first UNIBUS,
which can accommodate certain other options. Adding a second UDA50 requires
a second UNIBUS. With the exception of the first UNIBUS, a maximum of two
UDA50 controllers per UNIBUS are supported. If two UDA50 controllers are on
a UNIBUS, no other options can be placed on that UNIBUS. The VAX-11/730
processor supports only one UDA50 per UNIBUS.
The UDA50, in implementing DSA, takes over the control of the physical disk
unit. The operating system processes request virtual or logical I/O on disks
controlled by the UDA50. The operating system maps virtual block addresses
into logical block addresses. The UDA50 then resolves logical block addresses
into physical block addresses on the disk.

Disk Drivers 21

Disk Drivers
2.1 Supported Disk Devices and Controllers
The UDA50 controller corrects bad blocks on the disk by requesting that the disk
class driver revector a failing physical block to another, error-free physical block
on the disk; the logical block number is not changed (see Section 2.2.11.1). Any
bad blocks that might exist on a disk attached to a UDA50 are transparent to the
operating system, which does logical or virtual I/O to such a disk. The UDA50
also corrects most data errors.

2.1.2 KDA50 Disk Controller

The KDA50 disk controller is a two-module disk controller that allows the RAseries DSA disk drives to be attached to Q-bus systems. The KDA50 performs the
same functions as the UDA50 (see Section 2.1.1).

2.1.3 KDB50 Disk Controller

The KDB50 disk controller is a two-module disk controller that allows the RAseries DSA disk drives to be attached to BI bus systems, such as the
VAX 8200 processor. The KDB50 performs the same functions as the UDA50 (see
Section 2.1.1).

2.1.4 HSC40, HSC50, and HSC70 Controllers

HSC controllers are high-speed, high-availability controllers for mass storage
devices that implement the DIGITAL Storage Architecture (DSA); for more
information about the DSA, see Section 2.2.3. An HSC controller is connected to
a processor by a CI bus (computer interconnect). The operating system supports
the use of the HSC controllers in controlling the RA family of disks.
The HSC40 can support up to 12 SDI (standard disk interface) disks from the SA
or RA families of disk drives or a combination of up to 12 SDI disk drives and
TA-series tape drives.
The HSC70 can support up to 32 SDI disks from the SA or RA families of disk
drives or a combination of SDI disk drives and TA-series tape drives.
HSC controllers, in implementing DSA, take over the control of the physical disk
unit. System processes request virtual or logical I/O on disks controlled by the
HSC controller. The operating system maps virtual block addresses into logical
block addresses. The HSC controller then resolves logical block addresses into
physical block addresses on the disk.
HSC controllers correct bad blocks on the disk by revectoring a failing physical
block to another, error-free physical block on the disk; the logical block number is
not changed. The operating system, which performs logical or virtual I/O to such
a disk, does not recognize that any bad blocks might exist on a disk attached to
an HSC controller. HSC controllers also correct most data errors.
The HSC series of controllers provides access to disks despite most hardware
failures. Use of an HSC controller permits two or more processors to access files
on the same disk.
Note
Only one system should have write access to a Files-11 On-Disk Structure
Level 1 disk or to a foreign-mounted disk; all other systems should only
have read access to the disk. For Files-11 On-Disk Structure Level 2
volumes, the operating system enables read/write access to all nodes that
are members of the same cluster.

22 Disk Drivers

Disk Drivers
2.1 Supported Disk Devices and Controllers
HSC-series controllers allow you to add or subtract disks from the device
configuration without rebooting the system.

2.1.5 SII Integral Adapter

The SII integral adapter on the MicroVAX 3300/3400 processor provides access
through the DIGITAL Storage Systems Interconnect (DSSI) bus to a maximum of
seven storage devices.
The term dual-host refers to pairs of CPUs connected to a bus. In dual-host
configurations of MicroVAX 3300/3400 CPUs, the DSSI bus must be connected
between the SII integral adapters present on both CPUs.
A maximum of six devices can be connected to the EDA640 adapter, which is
implemeneted by the SII chip, DXX chip, and 128K RAM chip, in dual-host
configurations.

2.1.6 KFQSA Adapter

The KFQSA adapter allows a maximum of seven storage devices for use on Q-bus
systems.
In dual-host configurations of MicroVAX 3800/3900 CPUs, the DSSI bus must be
connected between KFQSA adapters present on both CPUs.
A maximum of six devices can be connected to the KFQSA adapter in dual-host
configurations.

2.1.7 RQDX3 Disk Controller

The RQDX3 controller is a Q-bus controller used with the RD series of
Winchester-type disk drives and the RX33 and RX50 flexible diskette drives.

2.1.8 RA70 and RA90 Disk Drives

The RA70 is a 5.25-inch 280 MB high-performance DSA disk drive that uses
thin-film media. It has an average access time of 27.0 ms and average seek time
of 19.5 ms. The RA70 uses the Standard Disk Interface (SDI) and the KDA50
controller, and can be dual-ported.
The RA90 is a 1.2 GB disk drive designed with thin-film heads and 9-inch
thin-film media with an average seek time of 18.5 ms. The RA90 conforms to
DSA and uses the SDI. Both the RA70 and RA90 disk drives can be connected
to medium-sized systems with the HSC-series controllers, KDB50, or UDA50
controllers.

2.1.9 RA60 Disk

The RA60 device uses high-capacity, removable media that provides 205 MB
of usable storage (7.5 million bits of data per square inch) with transfer rates
of 1.9 MB per second (burst) and 950 kb per second (sustained). The RA60
belongs to the DIGITAL Storage Architecture (DSA) family of disk devices (see
Section 2.2.3). It is connected to either a UNIBUS Disk Adapter (UDA50) or an
HSC50 controller. Up to four disk drives can be connected to each UDA50. Up to
24 disk drives can be connected to each HSC50.

Disk Drivers 23

Disk Drivers
2.1 Supported Disk Devices and Controllers
2.1.10 RA80/RB80/RM80 and RA81 Fixed-Media Disks
The R80 disk drive is a high-capacity, moving-head disk whose nonremovable
media consists of 14 data surfaces. Depending on how it is connected to the
system, the R80 is identified internally as an RA80, RB80, or RM80, as follows:

RA80An R80 connected to the system through a UNIBUS disk adapter

(UDA50) or an HSC50 controller. Up to four disk drives can be connected to
each UDA50. Up to 24 disk drives can be connected to each HSC50.

RB80On VAX systems, an R80 connected to the system through an RB730

controller on a VAX-11/730 processor. Of the maximum of four drives that can
be connected to an RB730 controller, only one can be an RB80.

RM80On VAX and Alpha systems, an R80 connected to the system through
a MASSBUS adapter (MBA). Up to eight disk drives can be connected to each
MBA.

The RA81 is a high-capacity disk drive with nonremovable media that can hold
more than 890,000 blocks of data. This translates into more than 455 MB per
spindle. The RA81 is connected to a UDA50 or an HSC50 controller. Up to four
disk drives can be connected to each UDA50. Up to 24 drives can be connected to
each HSC50.
The RA80 and RA81 belong to the DIGITAL Storage Architecture (DSA) family of
disk devices (see Section 2.2.3).

2.1.11 RB02 and RL02 Cartridge Disk (VAX Only)

On VAX systems, the RL02 cartridge disk is a removable, random-access mass
storage device with two data surfaces. The RL02 is connected to the system by an
RL11 controller that interfaces with the UNIBUS adapter. Up to four RL02 disk
drives can be connected to each RL11 controller. For physical I/O transfers, the
track, sector, and cylinder parameters describe a physical 256-byte RL02 sector
(see Section 2.4).
When the RL02 is connected to an RB730 controller on a VAX-11/730 processor, it
is identified internally as an RB02 disk drive. Disk geometry is unchanged and
RL02 disk packs can be exchanged between drives on different controllers. Up to
four drives can be connected to the RB730 controller.

2.1.12 RC25 Disk (VAX Only)

On VAX systems, the RC25 disk is a self-contained, Winchester-type, mass
storage device that consists of a disk adapter module, a disk drive, and an
integrated disk controller. The drive contains two 8-inch, double-sided disks. One
of the disks (RCF25) is a sealed, nonremovable, fixed-media disk. The other disk
is a removable cartridge disk that is sealed until it is loaded into the disk drive.
The disks share a common drive spindle, and together they provide 52 million
bytes of storage. Adapter modules interface the RC25 with either a UNIBUS
system or a Q-bus system.

2.1.13 RD53 and RD54 Disks (VAX Only)

On VAX systems, the RD53 and RD54 are 5.25-inch, full-height, Winchester-type
drives with average access time of 38 ms and a data transfer rate of 0.625 MB
per second. The RD53 and RD54 have a formatted capacity of 71 MB and 159
MB, respectively. When used with the RQDX3 controller, the RD53 and RD54 are
DSA disks.

24 Disk Drivers

Disk Drivers
2.1 Supported Disk Devices and Controllers
See Section 2.2.12 for information about using RD series disks on the VAXstation
2000.

2.1.14 RF30 and RF71 Disks

The RF30 is a 150-MB, 5.25-inch, half-height disk drive while the RF71 is a 400MB full-height disk drive. The RF30 and RF71 include an embedded controller
for multihost access and a mass storage control protocol (MSCP) server. The
RF71 has a peak data transfer rate of 1.5 MB per second with average seek and
access time of 21 ms and 29 ms, respectively.
Both the RF30 and RF71 disks use DIGITAL Storage System Interconnect (DSSI)
bus and host adapters.

2.1.15 RK06 and RK07 Cartridge Disks (VAX Only)

On VAX systems, the RK06 cartridge disk is a removable, random-access, bulk
storage device with three data surfaces. The RK07 cartridge disk is a doubledensity RK06. The RK06 and RK07 are connected to the system by an RK611
controller that interfaces to the UNIBUS adapter. Up to eight disk drives can be
connected to each RK611.

2.1.16 RM03 and RM05 Pack Disks (VAX Only)

On VAX systems, the RM03 and RM05 pack disks are removable, moving-head
disks that consist of five data surfaces for the RM03 and 19 data surfaces for the
RM05. These disks are connected to the system by a MASSBUS adapter (MBA).
Up to eight disk drives can be connected to each MBA.

2.1.17 RP05 and RP06 Disk (VAX Only)

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

2.1.18 RP07 Fixed-Media Disk (VAX Only)

On VAX systems, the RP07 is a 516-MB, fixed-media disk drive that attaches to
the MASSBUS of the VAX-11/780 system. The RP07 transfers data at 1.3 million
bytes per second or as an option at a peak rate of 2.2 million bytes per second.
The nine platters rotate at 3600 rev/min and their data is accessed at an average
speed of 31.3 ms. These disks are connected to the system by an MBA. Up to
eight disk drives can be connected to each MBA.

2.1.19 RRD40 and RRD50 Read-Only Memory (CD-ROM)

The RRD40 and RRD50 are compact disc read-only memory (CD-ROM) devices
that use replicated media with a formatted capacity of approximately 600 MB.
The RRD40 is a 5.25-inch half-height, front-loading tabletop or embedded device
that attaches to the system using either the Small Computer System Interface
(SCSI) or Q-bus interface.
The RRD50 is a 5.25-inch, top-loading tabletop device that attaches to the system
using a Q-bus interface.
The RRD40 has an average access time of 0.5 second while the average access
time for the RRD50 is 1.5 seconds. Both the RRD40 and RRD50 have a data
transfer rate of 150 KB per second.

Disk Drivers 25

Disk Drivers
2.1 Supported Disk Devices and Controllers
The media for the RRD40 and the RRD50 are removable 4.7-inch (120-mm)
compact discs. However, the media for the RRD40 are enclosed in protective
self-loading carriers. The RRD40 with a SCSI interface is also available as an
embedded unit. The RRD40 and RRD50 Q-bus subsystems are standard disk
MSCP devices.

2.1.20 RX01 Console Disk (VAX Only)

On VAX systems, the RX01 disk uses a diskette. 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 logical and virtual block I/O operations, data is accessed with one block
resolution (four sectors). The sector numbers are interleaved to expedite data
transfers. Section 2.2.10 describes sector interleaving in greater detail.
For physical block I/O operations, the track, sector, and cylinder parameters
describe a physical, 128-byte RX01 sector (see Figure 21 and Section 2.4). Note
that the driver does not apply track-to-track skew, cylinder offset, or sector
interleaving to this physical medium address.
Figure 21 Disk Physical Address
31
P3:

16 15
Cylinder

8 7
Sector

Track

(Except RX01 and RX02)

31
P3:

16 15
Track

0
Sector

(RX01 and RX02 Only)

ZK0652GE

2.1.21 RX02 Disk (VAX Only)

On VAX systems, the RX02 disk is a mass storage device that uses removable
diskettes. The RX02 supports existing single-density, RX01-compatible diskettes.
A double-density mode allows diskettes to be recorded at twice the linear density.
An entire diskette must be formatted in either single or double density. Mixed
mode diskettes are not allowed.
The RX02 is connected to the system by an RX211 controller that interfaces with
the UNIBUS adapter. Up to two disk drives can be controlled by each RX211.
For logical and virtual block I/O operations, data is accessed with single block
resolution (four single-density sectors or two double-density sectors). The sector
numbers are interleaved to expedite data transfers. Section 2.2.10 describes this
feature in greater detail.

26 Disk Drivers

Disk Drivers
2.1 Supported Disk Devices and Controllers
For physical block I/O operations, the track and sector parameters shown in
Figure 21 describe a physical sector (128 bytes in single density; 256 bytes in
double density). The driver does not apply track-to-track skew, cylinder offset, or
sector interleaving to the physical medium address.

2.1.22 RX23 (VAX Only)

On VAX systems, the RX23 device is a 1-inch high, flexible diskette drive that
uses 3.5-inch microfloppy diskettes. The RX23 drive can access standard- and
high-density media. The following table summarizes capacities for standard- and
high-density media:
Density

Unformatted

Formatted

Standard

1.0 MB

700 KB

High

2.0 MB

1.4 MB

The RX23 is backward compatible in that it can read 1-MB media. It can also
read and write 2.0-MB double-sided, high-density (135 tracks per inch) media.
The RX23 communicates with the controller using the ST506 fixed-disk
interconnect (FDI).

2.1.23 RX33 (VAX Only)

On VAX systems, the RX33 is a 1.2-MB, 5.25-inch, half-height diskette drive.
The RX33 can record in either standard- or high-density mode. High-density
mode provides 1.2 MB of storage using 96 tracks per inch using double-sided,
high-density diskettes.
In standard-density mode, the RX33 drive is read- and write-compatible with
single-sided, standard-density RX50 diskettes.

2.1.24 RX50 (VAX Only)

On VAX systems, the RX50 dual-diskette drive stores data in fixed-length blocks
on 5.25-inch 0.8-MB, flexible diskettes using preformatted headers. The RX50
can accommodate two diskettes simultaneously.

2.1.25 RZ22, RZ23, and RZ55 Disks

The RZ22 and RZ23 are 3.5-inch, half-height SCSI drives with an average seek
rate of 33 ms and an average data transfer rate of 1.25 MB per second. The RZ22
and RZ23 have capacities of 52 MB and 104 MB, respectively.
The RZ55 is a 332-MB, 5.25-inch, full-height SCSI drive with an average access
rate of 24 ms.

2.1.26 TU58 Magnetic Tape (DECtape II)

The TU58 is a random-access, mass storage magnetic tape device capable
of reading and writing 256K bytes per drive of data on block-addressable,
preformatted cartridges at 800 bits per inch. Unlike conventional magnetic tape
systems, which store information at variable positions on the tape, the TU58
stores information at fixed positions on the tape, as do magnetic disk or floppy
disk devices. Therefore, blocks of data can be placed on tape in a random fashion,
without disturbing previously recorded data. In its physical geometry, the tape
is conceptually viewed as having one cylinder, four tracks per cylinder, and 128
sectors per track. Each sector contains one 512-byte block.

Disk Drivers 27

Disk Drivers
2.1 Supported Disk Devices and Controllers
The TU58 uses two vectors. NUMVEC=2 is required on the CONNECT command
when specifying system parameters.
The TU58 interfaces with the UNIBUS adapter through a DL11-series interface
device. Both the TU58 and the DL11 should be set to 9600 baud. (Because the
TU58 is attached to a DL11, the user cannot directly access the TU58 registers if
the TU58 is on the UNIBUS.) The TU58, which has its own controller, can access
either one or two tape drives.

2.2 Driver Features

Disk drivers provide the following features:

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

Multiple disk drives per controller (the exact number depends on the
controller)

Different types of disk drives on a single controller

Static dual porting (MBA drives only)

Overlapped seeks (except RL02, RX01, RX02, and TU58)

Data checks on a per-request, per-file, or per-volume basis (except RX01 and

RX02)

Full recovery from power failure for online disk drives with volumes mounted

Extensive error recovery algorithms, such as error code correction and offset
(except RB02, RL02, RX01, RX02, and TU58); for DSA disks, these algorithms
are implemented in the controller

Dynamic, as well as static, bad block handling

Logging of device errors in a file that can be displayed by field service

personnel or customer personnel

Online diagnostic support for drive level diagnostics

Multiple-block, noncontiguous, virtual I/O operations at the driver level

Logical-to-physical sector translation (RX01 and RX02 only)

The following sections describe these features in greater detail.

2.2.1 Dual-Pathed Disks

A dual-pathed disk is a dual-ported disk that is accessible to all the CPUs
in the cluster, not just to the CPUs that are connected physically to the disk.
Dual-pathed disks can be any of the following:

Dual-ported MASSBUS disks

Dual-ported HSC disks

Dual-pathed DSA disks on local UDA50, KDA50, and KDB50 controllers

Dual-ported RF-series disks

The term dual-pathed refers to the two paths through which clustered CPUs can
access a disk to which they are not directly connected. If one path fails, the disk
is accessed over the other path. (Note that with a dual-ported MASSBUS disk, a
CPU directly connected to the disk always accesses it locally.)

28 Disk Drivers

Disk Drivers
2.2 Driver Features
2.2.2 Dual Porting MASSBUS Disks
The MASSBUS disk drivers, DBDRIVER and DRDRIVER, support static dual
porting. Dual porting allows two MASSBUS controllers to access the same disk
drive. Figure 22 shows this configuration. The RP05, RP06, RP07, RM03,
RM05, and RM80 disk drives can be ordered, or upgraded in the field, with the
MASSBUS dual-port option.
Figure 22 Dual-Ported Disk Drives
VAX
CPU A

VAX
CPU B

Controller

Controller

Disk
Drive
ZK0650GE

2.2.2.1 Port Selection and Access Modes

The port select switches, on each disk drive, select the ports from which the drive
can be accessed. A drive can be in one of the following access modes:

Locked on Port AThe drive is in a single-port mode (Port A). It does not
respond to any request on Port B.

Locked on Port BThe drive is in a single-port mode (Port B). It does not
respond to any request on Port A.

Programmable A/BThe drive is capable of responding to requests on either

Port A or Port B. In this mode, the drive is always in one of the following
states:
The drive is connected and responding to a request on Port A. It is closed
to requests on Port B.
The drive is connected and responding to a request on Port B. It is closed
to requests on Port A.
The drive is in a neutral state. It is equally available to requests on
either port on a first-come, first-serve basis.

The operational condition of the drive cannot be changed with the port select
switches after the drive becomes ready. To change from one mode to another, the
drive must be in a nonrotating condition. After the new mode selection has been
made, the drive must be restarted.

Disk Drivers 29

Disk Drivers
2.2 Driver Features
If a drive is in the neutral state and a disk controller either reads or writes
to a drive register, the drive immediately connects a port to the requesting
controller. For read operations, the drive remains connected for the duration of
the operation. For write operations, the drive remains connected until a release
command is issued by the device driver or a 1-second timeout occurs. After the
connected port is released from its controller, the drive checks the other ports
request flag to determine whether there has been a request on that port. If no
request is pending, the drive returns to the neutral state.
2.2.2.2 Disk Use and Restrictions
If the volume is mounted foreign, read/write operations can be performed at both
ports provided the user maintains control of where information is stored on the
disk.
The Autoconfigure utility currently may not be able to locate the nonactive
port. For example, if a dual-ported disk drive is connected and responding at
Port A, the CPU attached to Port B might not be able to find Port B with the
Autoconfigure utility. If this problem occurs, execute the AUTOCONFIGURE
ALL/LOG command after the system is running.
2.2.2.3 Restriction on Dual-Ported Non-DSA Disks in a Cluster
Do not use SYSGEN to AUTOCONFIGURE or CONFIGURE a dual-ported, nonDSA disk that is already available on the system through use of an MSCP server.
Establishing a local connection to the disk when a remote path is already known
creates two uncoordinated paths to the same disk. Use of these two paths may
corrupt files and data on any volume mounted on the drive.
Note
If the disk is not dual-ported or is never served by an MSCP server on the
remote host, this restriction does not apply.

In a cluster, dual-ported non-DSA disks (MASSBUS or UNIBUS) can be connected

between two nodes of the cluster. These disks can also be made available to the
rest of the cluster using the MSCP server on either or both of the hosts to which
a disk is connected.
If the local path to the disk is not found during the bootstrap, then the MSCP
server path from the other host will be the only available access to the drive. The
local path will not be found during a boot if any of the following conditions exist:

The port select switch for the drive is not enabled for this host.

The disk, cable, or adapter hardware for the local path is broken.

There is sufficient activity on the other port to hide the existence of the port.

The system is booted in such a way that the SYSGEN AUTOCONFIGURE

ALL command in the SYS$SYSTEM:STARTUP.COM procedure was not
executed.

Use of the disk is still possible through the MSCP server path.
After the configuration of the disk has reached this state, it is important not to
add the local path back into the system I/O database. Because the operating
system does not provide an automatic method for adding this local path, the only
possible way that you can add this local path is to use the System Generation
utility (SYSGEN) qualifiers AUTOCONFIGURE or CONFIGURE to configure the

210 Disk Drivers

Disk Drivers
2.2 Driver Features
device. SYSGEN is currently not able to detect the presence of the disks MSCP
path, and will incorrectly build a second set of data structures to describe it.
Subsequent events could lead to incompatible and uncoordinated file operations,
which might corrupt the volume.
To recover the local path to the disk, it is necessary to reboot the system
connected to that local path.

2.2.3 Dual-Pathed DSA Disks

A dual-ported DSA disk can be failed over between the two CPUs that serve it to
the cluster under the following conditions: ( 1 ) the same disk controller letter and
allocation class are specified on both CPUs and ( 2 ) both CPUs are running the
MSCP server.
Caution
Failure to observe these requirements can endanger data integrity.

However, because a DSA disk can be on line to only one controller at a time,
only one of the CPUs can use its local connection to the disk. The second CPU
accesses the disk through the MSCP server. If the CPU that is currently serving
the disk fails, the other CPU detects the failure and fails the disk over to its local
connection. The disk is thereby made available to the cluster once more.
Note
A dual-ported DSA disk may not be used as a system disk.

2.2.4 Dual-Porting HSC Disks

By design, HSC disks are cluster accessible; therefore, if they are dual-ported,
they are automatically dual-pathed. CI-connected CPUs can access a dual-pathed
HSC disk by way of a path through either HSC-connected device.
For each dual-ported HSC disk, you can control failover to a specific port using
the port select buttons on the front of each drive. By pressing either port select
button (A or B) on a particular drive, you can cause the device failover to the
specified port.
With the port select button, you can select alternate ports to balance the disk
controller workload between two HSC subsystems. For example, you could set
half of your disks to use port A and set the other half to use port B.
The port select buttons also allow you to fail over all the disks to an alternate
port manually when you anticipate the shutdown of one of the HSC subsystems.

2.2.5 Dual-Pathed RF-Series Disks

In a dual-path configuration of MicroVAX 3300/3400 CPUs or MicroVAX
3800/3900 CPUs using RF-series disks, CPUs have concurrent access to any
disk on the DSSI bus. A single disk is accessed through two paths and can be
served to all satellites by either CPU.

Disk Drivers 211

Disk Drivers
2.2 Driver Features
If either CPU fails, satellites can access their disks through the remaining CPU.
Note that failover occurs in the following situations: ( 1 ) when the DSSI bus is
connected between SII integral adapters on both MicroVAX 3300/3400 CPUs or
( 2 ) when the DSSI bus is connected between the KFQSA adapters on pairs of
MicroVAX 3300/3400s or pairs of MicroVAX 3800/3900s.
Note
The DSSI bus should not be connected between a KFQSA adapter on one
CPU and an SII integral adapter on another.

2.2.6 Data Check

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

Per requestYou 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. IO$M_DATACHECK is not supported for the RX01 and RX01
drivers.

Per volumeYou can specify the characteristics data check all reads and
data check all writes when the volume is mounted. The OpenVMS DCL
Dictionary describes volume mounting and dismounting. The OpenVMS
System Services Reference Manual describes the Mount Volume ($MOUNT)
and Dismount Volume ($DISMOU) system services.

Per fileYou can specify the file access attributes data check on read and
data check on write. File access attributes are specified when the file is
accessed. Chapter 1 of this manual and the OpenVMS Record Management
Services Reference Manual describe file access.

Offset recovery is performed during a data check, but error code correction (ECC)
is not performed (see Section 2.2.9). For example, if a read operation is performed
and an ECC correction is 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 completed successfully, but the data check could not be
performed because of an ECC correction.
Data checks on read operations are extremely rare, and you 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.
A data check operation directed to a TU58 does not compare the data in memory
with the data on tape. Instead, either a read check or a write check operation is
performed (see Sections 2.4.1 and 2.4.2).

212 Disk Drivers

Disk Drivers
2.2 Driver Features
2.2.7 Effects of a Failure During an I/O Write Operation
The operating system ensures that when an I/O write operation returns a
successful completion status, the data is available on the disk or tape media.
Applications that must guarantee the successful completion of a write operation
can verify that the data is on the media by specifying the data check function
modifier IO$M_DATACHECK. Note that the IO$M_DATACHECK data check
function, which compares the data in memory with the data on disk, affects
performance because the function incurs the overhead of an additional read
operation to the media.
If a system failure occurs while a multiple-block write operation is in progress,
the operating system does not guarantee the successful completion of the write
operation. (OpenVMS does guarantee single-block write operations to DSA
drives.) When a failure interrupts a write operation, the data may be left in any
one of the following conditions:

The new data is written completely to the disk blocks on the media, but a
completion status was not returned before the failure.

The new data is partially written to the media so that some of the disk blocks
involved in the I/O contain the data from the write operation in progress,
and the remainder of the blocks contain the data that was present before the
write operation.

The new data was never written to the disk blocks on the media.

To guarantee that a write operation either finishes successfully or (in the event
of failure) is redone or rolled back as if it were never started, use additional
techniques to ensure data correctness and recovery. For example, using database
journaling and recovery techniques allows applications to recover automatically
from failures such as the following:

Permanent loss of the path between a CPU data buffer containing the data
being written and the disk being written to during a multiple-block I/O
operation. Communication path loss can occur due to node or controller
failure or a failure of node-to-node communications.

Failure of a CPU (such as a system failure, system halt, power failure, or

system shutdown) during a multiple-block write operation.

Mistaken deletion of a file.

Corruption of file system pointers.

File corruption due to a software error or incomplete bucket write operation

to an indexed file.

Cancellation of an in-progress multiple-block write operation.

2.2.8 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). Seek operations
can be overlapped except on RL02, RX01, RX02, TU58 drives, MicroVAX 2000,
VAXstation 2000, or on controllers with diskettes (for example, RQDX3) when the
disk is executing I/O requests. That is, when one drive performs a seek operation,
any number of other drives can also perform seek operations.

Disk Drivers 213

Disk Drivers
2.2 Driver Features
During the seek operation, the controller is free to perform transfers on other
units. Therefore, 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.
All DSA controllers perform extensive seek optimization functions as part of their
operation; IO$M_INHSEEK has no effect on these controllers.

2.2.9 Error Recovery

Error recovery in the operating system is aimed at performing all possible
operations to complete an I/O operation successfully. Error recovery operations
fall into the following categories:

Handling special conditions such as power failure and interrupt timeout.

Retrying nonfatal controller and drive errors. For DSA and SCSI disks, this
function is implemented by the controller.

Applying error correction information (not applicable for RB02, RL02, RX01,
RX02, and TU58 drives). For DSA and SCSI disks, error correction is
implemented by the controller.

Offsetting read heads to try to obtain a stronger recorded signal (not

applicable for RB02, RL02, RB80, RM80, RX01, RX02, and TU58 drives).
For DSA and SCSI disks, this function is implemented by the controller.

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 executed up to eight times before a fatal

error is returned.

All normal error recovery procedures (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.

2.2.9.1 Skip Sectoring

Skip sectoring is a bad block treatment technique implemented on R80 disk
drives (the RB80 and RM80 drives). In each track of 32 sectors, one sector is
reserved for bad block replacement. Consequently, an R80 drive has available
only 31 sectors per track. The Get Device/Volume Information ($GETDVI) system
service returns this value.

214 Disk Drivers

Disk Drivers
2.2 Driver Features
You can detect bad blocks when a disk is formatted. Most formatters place these
blocks in a bad block file. On an R80 drive, the first bad block encountered on a
track is designated as a skip sector. This is accomplished by setting a flag in the
sector header on the disk and placing the block in the skip sector file.
When a skip sector is encountered during a data transfer, it is skipped over, and
all remaining blocks in the track are shifted by one physical block. For example,
if block number 10 is a skip sector, and a transfer request was made beginning at
block 8 for four blocks, then blocks 8, 9, 11, and 12 will be transferred. Block 10
will be skipped.
Because skip sectors are implemented at the device driver level, they are not
visible to you. The device appears to have 31 contiguous sectors per track. Sector
32 is not directly addressable, although it is accessed if a skip sector is present on
the track.

2.2.10 Logical-to-Physical Translation (RX01 and RX02)

Logical-block-to-physical-sector translation on RX01 and RX02 drives adheres to
the standard format. For each 512-byte logical block selected, the driver reads or
writes four 128-byte physical sectors (or two 256-byte physical sectors if an RX02
is in double-density mode). To minimize rotational latency, the physical sectors
are interleaved. Interleaving allows the processor time to complete a sector
transfer before the next sector in the block reaches the read/write heads. To allow
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 1; track 0 is not used.
The translation procedure, in more precise terms, is as follows:
1. Compute an uncorrected medium address using the following dimensions:
Number of sectors per track = 26
Number of tracks per cylinder = 1
Number of cylinders per disk = 77
2. Correct the computed address for interleaving and track-to-track skew
(in that order) as shown in the following Compaq Fortran for OpenVMS
statements. ISECT is the sector address and ICYL is the cylinder address
computed in Step 1.
Interleaving: ITEMP = ISECT*2
IF (ISECT .GT. 12) ITEMP = ITEMP-25
ISECT = ITEMP
Skew:
ISECT = ISECT+(6*ICYL)
ISECT = MOD (ISECT, 26)
3. Set the sector number in the range of 1 through 26 as required by the
hardware:
ISECT = ISECT+1

Disk Drivers 215

Disk Drivers
2.2 Driver Features
4. Adjust the cylinder number to cylinder 1 (cylinder 0 is not used):
ICYL = ICYL+1

2.2.11 DIGITAL Storage Architecture (DSA) Devices

The DIGITAL Storage Architecture (DSA) is a collection of specifications that
cover all aspects of a mass storage product. The specifications are grouped into
the following general categories:

Media formatDescribes the structure of sectors on a disk and the algorithms

for replacing bad blocks

Drive-to-controller interconnectDescribes the connection between a drive

and its controller

Controller-to-host communicationsDescribes how hosts request controllers

to transfer data

Because the operating system supports all DSA disks, it supports all controllerto-host aspects of DSA. Some of these disks, such as the RA60, RA80, and RA81,
use the standard drive-to-controller specifications. Other disks, such as the RC25,
RD51, RD52, RD53, and RX50, do not. Disk systems that use the standard
drive-to-controller specifications employ the same hardware connections and use
the HSC50, KDA50, KDB50, and UDA50 interchangeably. Disk systems that do
not use the drive-to-controller specifications provide their own internal controller,
which conforms to the controller-to-host specifications.
DSA disks differ from MASSBUS and UNIBUS disks in the following ways:

DSA disks contain no bad blocks. The hardware and the disk class driver
(DUDRIVER) function to ensure a logically contiguous range of good blocks.
If any block in the user area of the disk develops a defective area, all further
access to that block is revectored to a spare good block. Consequently, it is
never necessary to run the Bad Block Locator utility (BAD) on DSA disks.
There is no manufacturers bad block list and the file BADBLK.SYS is empty.
(The Verify utility, which is invoked by the ANALYZE /DISK_STRUCTURE
/READ_CHECK command, can be used to check the integrity of newly
received disks.) See Section 2.2.11.1 for more information about bad block
replacement for DSA disks.

Insert a WAIT statement in your SYSTARTUP_V5.COM file on VAX systems,

or your SYSTARTUP_VMS.COM file on Alpha systems, prior to the first
MOUNT statement for a DSA disk. The wait period should be about 2 to
4 seconds for the UDA50 and about 30 seconds for the HSC50. The wait
time is controller-dependent and can be as much as several minutes if the
controller is offline or otherwise inoperative. If this wait is omitted, the
MOUNT request may fail with a no such device status.

The DUDRIVER and the DSA device controllers allow multiple, concurrently
outstanding QIO requests. The order in which these requests complete might
not be in the order in which they were issued.

All DSA disks can be dual-ported, but only one HSC/UDA controller can
control a disk at a time (see Section 2.2.3).

In many cases, you can attach a DSA disk to its controller on a running
system and then use it without manual intervention.

DSA disks and the DUDRIVER do not accept physical QIO data transfers or
seek operations.

216 Disk Drivers

Disk Drivers
2.2 Driver Features
2.2.11.1 Bad Block Replacement and Forced Errors for DSA Disks
Disks that are built according to the DSA specifications appear to be error free.
Some number of logical blocks are always capable of recording data. When a
disk is formatted, every user-addressable logical block is mapped to a functioning
portion of the actual disk surface, which is known as a physical block. The
physical block has the true data storage capacity represented by the logical block.
Additional physical blocks are set aside to replace blocks that fail during normal
disk operations. These extra physical blocks are called replacement blocks.
Whenever a physical block to which a logical block is mapped begins to fail, the
associated logical block is remapped (revectored) to one of the replacement blocks.
The process that revectors logical blocks is called a bad block replacement
operation. Bad block replacement operations use data stored in a special area of
the disk called the Replacement and Caching Table (RCT).
When a drive-dependent error threshold is reached, the need for a bad block
replacement operation is declared. Depending on the controller involved, the bad
block replacement operation is performed either by the controller itself (as is the
case with HSCs) or by the host (as is the case with UDAs). In either case, the
same steps are performed. After inspecting and altering the RCT, the failing
block is read and its contents are stored in a reserved section of the RCT.
The design goal of DSA disks is that this read operation proceeds without error
and that the RCT copy of the data is correct (as it was originally written). The
failing block is then tested with one or more data patterns. If no errors are
encountered in this test, the original data is copied back to the original block
and no further action is taken. If the data-pattern test fails, the logical block is
revectored to a replacement block. After the block is revectored, the original data
is copied back to the revectored logical block. In all these cases, the original data
is preserved and the bad block replacement operation occurs without the user
being aware that it happened.
However, if the original data cannot be read from the failing block, a best-attempt
copy of the data is stored in the RCT and the bad block replacement operation
proceeds. When the time comes to write-back the original data, the best-attempt
data (stored in the RCT) is written back with the forced error flag set. The
forced error flag is a signal that the data read is questionable. Reading a block
that contains a forced error flag causes the status SS$_FORCEDERROR to be
returned. This status is displayed by the following message:
%SYSTEM-F-FORCEDERROR, forced error flagged in last sector read
Writing into a block always clears the forced error flag.
Note that most utilities and DCL commands treat the forced error flag as a fatal
error and terminate operation when they encounter it. However, the Backup
utility (BACKUP) continues to operate in the presence of most errors, including
the forced error. BACKUP continues to process the file, and the forced error flag
is lost. Thus, data that was formerly marked as questionable may become correct
data.
System managers (and other users of BACKUP) should assume that forced errors
reported by BACKUP signal possible degradation of the data.
To determine what, if any, blocks on a given disk volume have the forced error flag
set, use the ANALYZE /DISK_STRUCTURE /READ_CHECK command, which
invokes the Verify utility. The Verify utility reads every logical block allocated
to every file on the disk and then reports (but ignores) any forced error blocks
encountered.
Disk Drivers 217

Disk Drivers
2.2 Driver Features
2.2.12 VAXstation 2000 and MicroVAX 2000 Disk Driver
The VAXstation 2000 and MicroVAX 2000 disk driver supports some DSA disk
operation. In particular, the driver supports block revectoring and bad block
replacement. This provides the system with a logically perfect disk medium.
Like other DSA disks, if a serious error occurs during a replacement operation,
the disk is write-locked to prevent further changes. This is done to preserve data
integrity and minimize damage that could be caused by failing hardware. Unlike
other DSA disks, there is no visible indication on the drive itself that the disk is
write-locked. However, the following indicators help you determine that the disk
has become write-protected:

ERRFMT messages show that the disk is write-locked.

The disk enters mount verification and hangs.

DCL command SHOW DEVICE output shows that the disk is write-locked.

Error messages occur from programs and utilities attempting to write to the
disk.

If the disk becomes write-locked, you should use the following procedure:
1. Shut down the system.
2. Use standalone BACKUP to create a full backup of the disk.
3. Format the disk with the disk formatter.
4. Restore the disk from the backup using standalone BACKUP. Note that any
files with sectors flagged with a forced error may be corrupted and may need
to be restored from a previous backup.
If errors occurring during replacement operations persist, call Compaq Customer
Services.

2.2.13 SCSI Disk Class Driver

The VAXstation 3100, 3520, and 3540 contain a SCSI bus that provides access to
as many as seven SCSI disks. The SCSI disk class driver controls SCSI disks on
all of the above systems. Although SCSI disks do not conform to DSA, they do
support the following error recovery features:

Static and dynamic bad block replacement (BBR)

Error correction code (ECC)

Reexecution of read or write operations within the SCSI drive

Reexecution of read or write operations by the SCSI disk class driver

All SCSI disks supplied by Compaq implement the REASSIGN BLOCKS

command, which relocates data for a specific logical block to a different physical
location on the disk. The SCSI disk class driver reassigns the block in the
following instances: ( 1 ) when the retry threshold is exceeded during an attempt
to read or write a block of data on the disk or ( 2 ) when an irrecoverable error
occurs during a write operation.
Unlike DSA, there is no forced error flag in SCSI. Blocks that produce
irrecoverable errors during read operations are not reassigned in order to
prevent undetected loss of user data. Instead, the SCSI disk class driver returns
the SS$_PARITY status whenever a read operation results in an irrecoverable
error.

218 Disk Drivers

Disk Drivers
2.2 Driver Features
2.2.14 Audio Extensions to the SCSI Disk Class Driver
This section describes SCSI disk class driver audio commands and the $QIO
interface by which the operating system provides audio functionality to the SCSI
disk.
Table 21 lists the SCSI audio commands supported by the SCSI disk class
driver.
Table 21 SCSI Disk Class Driver Audio Commands
Command

Audio Function Code1

Description

Play Audio MSF

AUDIO_PLAY_AUDIO_MSF (5)

Requests the CD-ROM to begin an audio

playback operation. The two required command
arguments specify absolute starting and ending
addresses of the playback in terms of minutes,
seconds, and frame (MSF).

Play Audio Track

AUDIO_PLAY_AUDIO_TRACK
(6)

Requests the CD-ROM to begin an audio

playback operation. The two required command
arguments specify the starting and ending tracks
of the playback in terms of track number and
index.

Play Audio

AUDIO_PLAY_AUDIO (4)

Requests the CD-ROM to begin an audio

playback operation. The two required command
arguments specify the starting logical block
address (LBA) and the transfer count, in blocks,
of the playback.

Pause

AUDIO_PAUSE (0)

Requests the CD-ROM to suspend any active

audio operations. In response, the CD-ROM
enters the hold-track state, muting the audio
output after playing the current block.

Resume

AUDIO_RESUME (1)

Requests the CD-ROM to resume any active

audio operations. In response, the CD-ROM
exits the hold-track state and resumes playback
at the block following the last block played.

Get Status

AUDIO_GET_STATUS (9)

Requests from the CD-ROM the status of the

currently active playback operation, as well as
the state of the current block. The Get Status
command corresponds to the SCSI II Read
Sub-channel command (READ SUBQ).

Set Volume

AUDIO_SET_VOLUME (11)

Requests the CD-ROM to adjust the output

channel selection and volume settings for
ports 0 through 3. The Set Volume command
corresponds to the SCSI II Mode Select command
for the CD-ROM Audio Control Parameters page.

Get Volume

AUDIO_GET_VOLUME (12)

Requests from the CD-ROM the output channel

selection and volume settings for ports 0 through
3. The Get Volume command corresponds to the
SCSI II Mode Sense command for the CD-ROM
Audio Control Parameters page.

Prevent Removal

AUDIO_PREVENT_REMOVAL
(2)

Prevents the removal of the CD caddy from the

CD-ROM drive.

1 Symbolic values for the function codes of SCSI audio commands are defined in SYS$EXAMPLES:CDVERIFY.C. Numeric
values appear within parentheses in this table column.

(continued on next page)

Disk Drivers 219

Disk Drivers
2.2 Driver Features
Table 21 (Cont.) SCSI Disk Class Driver Audio Commands
Command

Audio Function Code1

Description

Allow Removal

AUDIO_ALLOW_REMOVAL (3)

Allows the removal of the CD caddy from the

CD-ROM drive.

Get TOC

AUDIO_GET_TOC (10)

Requests from the CD-ROM a list of each

track on the disk, including information about
the audio or data contents of each track.
Applications that require a detailed knowledge
of the organization of a CD-ROM can use this
function to obtain that information. The Get
TOC command corresponds to the SCSI II Read
TOC command.

1 Symbolic values for the function codes of SCSI audio commands are defined in SYS$EXAMPLES:CDVERIFY.C. Numeric
values appear within parentheses in this table column.

2.2.14.1 $QIO Interface to Audio Functionality of the SCSI Disk Class Driver
To employ the audio functions of the RRD42 CD-ROM reader, the application
program issues a call to the $QIO system service using the following format:
status=SYS$QIO ([efn] ,[chan] ,func [,iosb] [,astadr] [,astprm]
[,p1] [,p2] [,p3] [,p4] [,p5] [,p6])
Arguments
[efn]
[chan]
[iosb]
[astadr]
[astprm]
These arguments apply to the $QIO system service completion, not to device
interrupt actions. For an explanation of these arguments, refer to the description
of the $QIO system service in the OpenVMS System Services Reference Manual.
func
The IO$_AUDIO function code allows the SCSI disk class driver to process SCSI
audio commands.
p1
Address of an audio control block (AUCB). The $QIO system service passes a
SCSI audio command and command-specific control information to the SCSI disk
class driver in the AUCB structure (see Section 2.2.14.2).
p2
Size of the AUCB.
2.2.14.2 Defining an Audio Control Block (AUCB)
An application program that issues a call to the $QIO system service that
specifies the IO$_AUDIO function code in the func argument must supply
the address of an AUCB structure in the p1 argument and its size in the p2
argument.
An AUCB defines a specific SCSI audio command and provides the SCSI disk
class driver with command-specific arguments and control information. Table 22
defines the fields that appear in an AUCB; these fields are shown in Figure 23.
See SYS$EXAMPLES:CDROM_AUDIO.C for a code example that shows how an
AUCB is defined in the C programming language.

220 Disk Drivers

Disk Drivers
2.2 Driver Features
Figure 23 Audio Control Block (AUCB)
AUCB Version Number

Audio Function Code

Argument 1

Argument 2

Argument 3

12

Reserved

16

Destination Buffer Address

20

Destination Buffer Count

24

Destination Buffer Transfer Count

28

Operating System Command Status

32

SCSI Command Status (optional)

36

Sense Data Buffer Address (optional)

40

Sense Data Buffer Count (optional)

44

Sense Data Buffer Transfer Count (optional)

48

Reserved

52
ZK4625A

Table 22 Contents of AUCB

Field

Use

Audio Function
Code

Numeric or symbolic code representing the audio function desired by

the application program. (See Table 21.) The application program
must provide a valid audio function code for each operation.

AUCB Version
Number

Version of the AUCB and SCSI disk class driver audio interface.
For the current version of the interface the value of this field should
be 1. This field must never contain a zero.

Argument 1

This field is audio command-specific and contains the first argument

of the function as follows:

1 For

Audio Function Code1

Field Contents

AUDIO_PLAY_
AUDIO_MSF (5)

Starting Frames | (Sec shifted left 8

bits) | (Min shifted left 16 bits)

AUDIO_PLAY_
AUDIO_TRACK (6)

Starting (Track shifted left 8 bits) | Index

AUDIO_PLAY_AUDIO
(4)

Starting logical block address.

AUDIO_GET_STATUS
(9)

0 if LBA format, 1 if MSF format.

Refer to the SCSI II specification for
information about these formats.

any function code not listed in this table, this field contains a zero.

(continued on next page)

Disk Drivers 221

Disk Drivers
2.2 Driver Features
Table 22 (Cont.) Contents of AUCB
Field

Argument 2

Use
AUDIO_SET_
VOLUME (11)

Longword representing the values to

be used to determine the new output
channel selection and volume settings for
CD-ROM ports 0 through 3. Figure 24
shows the format of this longword. Note
that many CD-ROM drives do not support
ports 2 and 3.

AUDIO_GET_
VOLUME (12)

Longword to receive the current values

determining output channel selection
and volume settings for CD-ROM ports 0
through 3. Figure 24 shows the format
of this longword. Note that many CDROM drives do not support ports 2 and
3.

AUDIO_GET_TOC
(10)

0 if LBA format, 1 if MSF format.

Refer to the SCSI II specification for
information about these formats.

This field is audio command-specific and contains the second

argument of the function as follows:
Audio Function Code1

Field Contents

AUDIO_PLAY_
AUDIO_MSF (5)

Starting frames | (sec shifted left 8

bits) | ( min shifted left 16 bits)

AUDIO_PLAY_
AUDIO_TRACK (6)

Ending (track shifted left 8 bits) | index

AUDIO_PLAY_AUDIO
(4)

Transfer count in number of contiguous

blocks to be played

AUDIO_GET_TOC
(10)

Starting track

Reserved

Must be zero.

Destination Buffer
Address

Address of the application programs buffer from which the status

from a GET_STATUS or GET_TOC function is returned.

Destination Buffer
Count

Size, in bytes, of the destination buffer specified in the Destination

Buffer Address field. For the GET_STATUS function, this field must
contain the value 48 to receive complete status information. For the
GET_TOC function, this field must contain the value 804 to receive
full status. The SCSI disk class driver truncates the status data, if
the destination buffer size is smaller than the size of the data.

1 For

any function code not listed in this table, this field contains a zero.

(continued on next page)

222 Disk Drivers

Disk Drivers
2.2 Driver Features
Table 22 (Cont.) Contents of AUCB
Field

Use

Destination Buffer
Transfer Count

The SCSI disk class driver returns to this field the actual number
of bytes transferred to the buffer specified in the Destination Buffer
Address field.
Before accessing data returned by the GET_TOC or GET_STATUS
commands, an application program must check the contents of this
field to determine precisely how many bytes were returned by the
CD-ROM.
The application program initializes this field to zero.

Operating System
Command Status

Completion status of the SCSI audio function. This value is also

returned in the I/O status block of specified in the iosb argument
to the $QIO system service call. See Table 23 for a description of
these status codes.
The application program initializes this field to zero.

SCSI Command
Status (optional)

SCSI status of the current operation. The SCSI disk class driver
returns the SCSI status byte for the SCSI audio command described
by this AUCB in the low byte of the low-order word of this field. It
returns the sense key in the low byte of the high-order word. Refer
to the SCSI specification for information regarding SCSI status and
SCSI sense keys.
The application program initializes this field to zero.

Sense Data Buffer

Address (optional)

Address of buffer to which the SCSI disk class driver returns sense
data when errors occur during audio function execution. When
this field is specified, in the event of a check condition on an Audio
command, the SCSI disk class driver automatically issues a Request
Sense command to retrieve the Sense Key/Sense Data from the
target. The target returns this data to the buffer specified in this
field before the failing $QIO audio function completes.

Sense Data Buffer

Count (optional)

Size, in bytes, of the buffer specified in the Sense Data Buffer

Address field. During request sense processing, the target device
truncates the sense data to fit in this buffer.

Sense Data Buffer

Transfer Count
(optional)

Actual number of bytes of sense data returned to the application in

the buffer specified in the Sense Data Buffer Address field.

Reserved

Must be zero.

The application program initializes this field to zero.

The output channel selection and volume settings for CD-ROM ports as used by
the SET_VOLUME function appear as shown in Figure 24.
2.2.14.3 Error Handling in Applications Using SCSI Audio Functions
As indicated in Table 22, the AUCB provides for three levels of error status
reporting:

Condition values, returned in the Operating System Command Status field of

the AUCB, as well as in the I/O status block of specified in the iosb argument
to the $QIO system service call. (See Table 23 for a description of these
status codes.)
If this status is SS$_NORMAL, the function has completed without error. If
the status is not SS$_NORMAL, the application program should check the
SCSI Command Status field and the Sense Data buffer to fully determine the
cause of the failure.

Disk Drivers 223

Disk Drivers
2.2 Driver Features
Figure 24 Output Channel Selection and Volume Settings for CD-ROM Ports
as Used by the SET_VOLUME Function
31

23
volume

output selection

Port 1 or 3

15

7
volume

output selection

Port 0 or 2

volume = 00 (muted) to FF
(maximum)
output selection <7:4> = 0
output selection <3:0> = 0000 (output muted on this channel)
0001 (connect audio channel 0 to this output port)
0010 (connect audio channel 1 to this output port)
0011 (connect audio channels 0 and 1 to this port)
ZK4626A

SCSI command status, returned in the SCSI Command Status field of the
AUCB. The SCSI disk class driver returns to this field SCSI status as well as
the sense key in the event of a check condition SCSI status. The sense key
can be used to determine the first level of error reporting supported by SCSI.
See the SCSI specification for further information.

Sense data, returned in the buffer specified in the Sense Data Buffer Address
field of the AUCB. Sense data bytes are assigned as defined in the SCSI II
specification. Sophisticated programmers can use the data in this to obtain
detailed information about the error-causing condition.

If the CD-ROM device is currently software-enabled (that is, the volume has
been mounted) and a unit attention is detected, then mount verification will
be initiated by the driver. However, if the CD-ROM is not software-enabled,
the event will simply be returned to the application issuing the Audio $QIO
function.

224 Disk Drivers

Disk Drivers
2.2 Driver Features

Table 23 Status Codes Returned to the IOSB and AUCB by the SCSI Disk
Class Driver
SS$_NORMAL

AUCB command completed successfully.

SS$_ABORT

Returned by the SCSI disk port driver. In general, you

should retry commands that fail with this status.

SS$_BADPARM

The driver detected an illegal value or missing value in

the AUCB.

SS$_CTRLERR

CD-ROM failed some part of its initialization sequence.

When this status is returned, it is unlikely that the
CD-ROM is usable.

SS$_DEVOFFLINE

Device returned a not-ready sense key or failed the TEST

UNIT READY/START sequence.

SS$_DRVERR

CD-ROM failed to execute the command, either because

the drive has failed or an illegal command was issued.
Such a command could be a command that requested
the drive to issue an audio command to a data track or
attempted to perform a play operation on nonexistent
tracks.

SS$_ILLIOFUNC

Illegal I/O function was specified in the func argument of

the $QIO request.

SS$_IVADDR

Specified block number is larger than UCB$L_

MAXBLOCK.

SS$_MEDOFL

Last command failed because the drive detected the

removal and replacement of the CD carrier, or the
unsuccessful completion of a Request Sense command
after a check condition error. In general, you should not
retry commands that fail with this status.

SS$_NOPRIV

Caller does not have sufficient privileges to execute this

function. If the CD-ROM has not been mounted before an
IO$_READVBLK function is issued, this status may be
returned.

SS$_OPINCOMPL

Number of bytes requested is less than the number of

bytes returned.

SS$_PARITY

Nonrecoverable media error (does not apply to audio

functions).

SS$_RECOVERR

Recovered media error (does not apply to audio functions).

SS$_VOLINV

CD-ROM has not been mounted.

SS$_WRITLCK

Write operations not permitted on read-only devices.

2.2.14.4 Using CD-ROM to Store Both Data and Audio Information

To make effective use of mixed data and audio CDs, an application program
requires detailed knowledge of the particular CD being played. The application
program must know which tracks include data and which tracks include audio so
it can use commands appropriate to the different track types. Issuing an audio
command on a data track results in the command failing with a status of SS$_
DRVERR.
By default, the SCSI disk class driver transfers all requests issued to a CD-ROM
in blocks of 512 bytes. This byte amount is referred to as the default block size.
Before attempting to issue READ operations to the CD-ROM, you must ensure
that the CD-ROM has been mounted as foreign or as a Files-11 volume. The
application program can then determine, by issuing a GET_TOC function, which

Disk Drivers 225

Disk Drivers
2.2 Driver Features
tracks (and, therefore, which logical blocks) contain data and which contain audio
information.
2.2.14.5 Programming Audio Applications
The following list contains information useful in avoiding problems when writing
code using the SCSI audio interfaces:

If you do not know the type of file system on the CD-ROM, you should mount
the CD-ROM as foreign and issue a $QIO request with the logical block I/O
read function (IO$_READLBLK) to read individual data blocks. The default
block size for all CD-ROMs is 512 bytes.

When using the GET_TOC command to obtain CD-ROM address information

in LBA format, be advised that the byte ordering of the returned data is in
big-endian form. Because VAX byte ordering is little-endian, you must switch
the LBA data bytes to get a logical block address that is valid on a VAX
computer. SYS$EXAMPLES:CDROM_AUDIO.C contains an example of how
to perform this exchange.

Before attempting to issue a $QIO request with the virtual block I/O read
function (IO$_READVBLK) to the CD-ROM, ensure that the CD-ROM has
been mounted. Typically, you have to foreign mount non-Files-11 disks. If an
IO$_READVBLK $QIO request is issued to an unmounted CD, the request
fails with a status of SS$_NOPRIV.

2.2.14.6 Application Program Example Using SCSI Audio Capabilities (VAX only)
The file SYS$EXAMPLES:CDROM_AUDIO.C contains an example of an
application program that performs the following tasks:

Defines standard symbolic names for the audio function codes representing
SCSI audio commands.

Defines representative AUCBs for each audio function code supported by the
SCSI disk class driver.

Issues a series of $QIO system service requests, each specifying the IO$_
AUDIO function, that exercise the SCSI disk class driver to test its support
for CD-ROM drives with audio capabilities.

Converts LBA data returned by a GET_STATUS command in big-endian

byte-ordering form to VAX little-endian byte-ordering form.

2.3 Disk Driver Device Information

You can obtain information on all disk device characteristics by using the Get
Device/Volume Information ($GETDVI) system service (refer to the OpenVMS
System Services Reference Manual).
$GETDVI returns disk characteristics when you specify the item codes DVI$_
DEVCHAR and DVI$_DEVCHAR2. Table 24 lists the possible characteristics
for disk devices.

226 Disk Drivers

Disk Drivers
2.3 Disk Driver Device Information
Table 24 Disk Device Characteristics
Characteristic1

Meaning
Dynamic Bits (Conditionally Set)

DEV$M_AVL

Device is on line and available.

DEV$M_CDP

2;3

Dual-path device with two unit control blocks (UCBs).

Device is available clusterwide.

DEV$M_CLU
DEV$M_2P

Device is dual-pathed.

DEV$M_FOR

Device is foreign.

DEV$M_MNT

Volume is mounted.

DEV$M_RCK

Perform data check on all reads.

DEV$M_WCK

Perform data check on all writes.

DEV$M_MSCP2

Device is accessed using the mass storage control protocol.

DEV$M_RCT

Disk contains replacement and caching table.

DEV$M_SRV

For a cluster, device is served by the MSCP server.

Static Bits (Always Set)

DEV$M_FOD

Device is file-oriented.

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

by the $DEVDEF macro.

bits are located in DVI$_DEVCHAR2.

3 MASSBUS

only.

DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default to be
used for disk transfers (this default is normally 512 bytes). DVI$_DEVTYPE and
DVI$_DEVCLASS return the device type and class names, which are defined by
the $DCDEF macro. The disk model determines the device type. For example,
the device type for the RA81 is DT$_RA81. (Foreign device types take the form
DT$_FD1 through DT$_FD8.) The device class for disks is DC$_DISK.
DVI$_CYLINDERS returns the number of cylinders per volume (that is, per
disk), DVI$_TRACKS returns the number of tracks per cylinder, and
DVI$_SECTORS returns the number of sectors per track. Values are returned as
4-byte decimal numbers.
DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512 bytes)
that can be contained on the volume (that is, on the disk). Values are returned as
4-byte decimal numbers. This information can be used, for example, to determine
the density of an RX02 diskette (single density = 494 blocks, double density = 988
blocks).

Disk Drivers 227

Disk Drivers
2.4 Disk Function Codes

2.4 Disk Function Codes

Disk drivers can perform logical, virtual, and physical I/O functions. Foreignmounted devices do not require privilege to perform logical and virtual I/O
requests.
Logical and physical I/O functions allow access to volume storage and require
only that the issuing process have access to the volume; however, DSA disks and
the disk class driver (DUDRIVER) do not accept physical QIO data transfers or
seek operations.
Note
The results of logical and physical I/O operations are unpredictable if
an ancillary control process (ACP) or extended QIO processing (XQP) is
present.

Virtual I/O functions require an ACP for Files-11 On-Disk Structure Level 1 files
or an XQP for Files-11 On-Disk Structure Level 2 files. Virtual I/O functions
must be executed in a prescribed order. First, you create and access a file, then
you write information to that file, and lastly you deaccess the file. Subsequently,
when you access the file, you read the information and then deaccess the file.
Delete the file when the information is no longer useful.
Non-DSA disk devices can read or write up to 65,535 bytes in a single request.
DSA devices connected to an HSC50 can transfer up to 4 billion bytes in a single
request. In all cases, the maximum size of the transfer is limited by the number
of pages that can be faulted into the process working set, and then locked into
physical memory. (The disk driver is responsible for any memory management
functions of this type.) The size of the transfer does not affect the applicable
quotas (direct I/O count, buffered I/O count, and asynchronous system trap (AST)
count limit). These quotas refer to the number of outstanding I/O operations of
each type, not the size of the I/O operation being performed.
The volume to which a logical or virtual function is directed must be mounted
for the function actually to 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 25 lists the logical, virtual, and physical disk I/O functions and their
function codes. Chapter 1 describes the QIO level interface to the disk device
ACP.

228 Disk Drivers

Disk Drivers
2.4 Disk Function Codes
Table 25 Disk I/O Functions
Function
Modifiers

Function Code

Arguments

Type1

IO$_ACCESS

P1, [P2],[P3],[P4],[P5]

IO$M_CREATE
IO$M_ACCESS

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

IO$_ACPCONTROL

P1,[P2],[P3],[P4],[P5]

IO$M_DMOUNT

Perform
miscellaneous
control
functions.

IO$_AVAILABLE

Function

Clear volume
valid; make DSA
units available.

IO$_CREATE

P1,[P2],[P3],[P4],[P5]

IO$_DEACCESS

P1,[P2],[P3],[P4],[P5]

IO$_DELETE

P1,[P2],[P3],[P4],[P5]

IO$_FORMAT

P1

Set density
(RX02 only).

IO$_MODIFY

P1,[P2],[P3],[P4],[P5]

Modify the file

attributes or
allocation, or
both.

Update UCB
fields if RX02;
initialize volume
valid on other
devices. Bring
DSA units on
line.

IO$_PACKACK

IO$M_CREATE
IO$M_ACCESS
IO$M_DELETE

Create a
directory entry
or a file.
Deaccess a file
and, if specified,
write final
attributes in
the file header.

IO$M_DELETE

Remove a
directory entry
or file header, or
both.

IO$_READLBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_INHRETRY

Read logical
block.

IO$_READPBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_INHRETRY
IO$M_INHSEEK3

Read physical
block.5

IO$_READVBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_INHRETRY

Read virtual
block.

1V

= virtual; L = logical; P = physical

2 Not
3 Not
5 Not
6 On

for RX01 and RX02 disks.

for TU58, RX01, RX02, RB02, and RL02 drives.
for DSA and SCSI disks.
OpenVMS Alpha, P1 supports a 64-bit address.

(continued on next page)

Disk Drivers 229

Disk Drivers
2.4 Disk Function Codes
Table 25 (Cont.) Disk I/O Functions
Function
Modifiers

Function Code

Arguments

Type1

IO$_SEARCH

P1

Search for
specified block or
sector (only for
TU58).

IO$_SEEK

P1

Seek to specified
cylinder.5

IO$_SENSECHAR

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

IO$_SENSEMODE

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

IO$_SETPRFPATH

P1

IO$_UNLOAD

IO$M_FORCEPTH

Function

Specifies a
preferred path
for DSA disks.

Clear volume
valid; make DSA
units available
and spin down
the volume.
Verify data
written to disk
by a previous
write QIO.2

IO$_WRITECHECK6

P1,P2,P3

IO$_WRITELBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_ERASE
IO$M_INHRETRY

Write logical
block.

IO$_WRITEPBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_ERASE
IO$M_INHRETRY
IO$M_INHSEEK3
IO$M_DELDATA4

Write physical
block.5

IO$_WRITEVBLK6

P1,P2,P3

IO$M_DATACHECK2
IO$M_ERASE
IO$M_INHRETRY

Write virtual
block.

1V

= virtual; L = logical; P = physical

2 Not
3 Not

for RX01 and RX02 disks.

for TU58, RX01, RX02, RB02, and RL02 drives.

4 RX02

only.

5 Not

for DSA and SCSI disks.

6 On OpenVMS Alpha, P1 supports a 64-bit address.

The function-dependent arguments for IO$_CREATE, IO$_ACCESS,

IO$_DEACCESS, IO$_MODIFY, and IO$_DELETE are as follows:

230 Disk Drivers

Disk Drivers
2.4 Disk Function Codes

P1The address of the file information block (FIB) descriptor.

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

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

P4The address of a descriptor for a buffer that is to receive the resulting

file name string (optional).

P5The address of a list of attribute descriptors (optional). If specified,

the indicated attributes are read (IO$_ACCESS) or written (IO$_CREATE,
IO$_DEACCESS, and IO$_MODIFY).

See Chapter 1 for more information on these functions.

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK,
IO$_WRITEVBLK, and IO$_WRITELBLK are as follows:

P1The starting virtual address of the buffer that is to receive the data from
a read operation; or, in the case of a write operation, the virtual address of
the buffer that is to be written on the disk. On OpenVMS Alpha, P1 can be a
64-bit address.

P2The 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, RL11, RX211, or UDA50.

P3The starting virtual/logical disk address of the data to be transferred in

a read operation; or, in a write operation, the disk address of the area that is
to receive the data.
In a virtual read or write operation, 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 numbers using mapping windows
that are set up by the file system ACP process.)
In a logical read or write operation, the address is expressed as a block
number relative to the start of the disk. For example, the first sector on the
disk contains block 0 (or at least the beginning of block 0).

The function-dependent arguments for IO$_WRITEVBLK, IO$_WRITELBLK,

and IO$_WRITEPBLK functions that include the IO$M_ERASE function modifier
are as follows:

P1The starting virtual address of the buffer that contains a 4-byte, userspecified erase pattern. If the P1 address is 0, a longword of 0 will be used
for the erase pattern. If the P1 address is nonzero, the contents of the 4
bytes starting at that address will be used as the erase pattern. Compaq
recommends that the user specify a P1 address of 0 to lower system overhead.
On OpenVMS Alpha, P1 can be a 64-bit address.
Note
DSA disk controllers provide controlled, assisted erasing for the IO$M_
ERASE modifier (with virtual and logical write functions) only when the
erase pattern is all zeros. If a nonzero erase pattern is used, there is a
significant performance degradation with these disks. DSA disks do not
accept physical QIO transfers.

Disk Drivers 231

Disk Drivers
2.4 Disk Function Codes

P2The number of bytes of erase pattern to write to the disk. The number
specified is rounded up to the next highest block boundary (512 bytes).

P3The starting virtual, logical, or physical disk address of the data to be

erased.

The function-dependent arguments for IO$_WRITECHECK,

IO$_READPBLK, and IO$_WRITEPBLK are as follows:

P1The starting virtual address of the buffer that is to receive the data in
a read operation; or, in a write operation, the starting virtual address of the
buffer that is to be written on the disk. Passed by reference. On OpenVMS
Alpha, P1 can be a 64-bit address.

P2The number of bytes that are to be read from the disk, or written from
memory to the disk. Passed by value. An even number must be specified if
the controller is an RK611, RL11, or UDA50.

P3The starting physical disk address of the data to be read in a read

operation; or, in a write operation, the starting physical address of the disk
area that is to receive the data. Passed by value. The address is expressed as
sector, track, and cylinder in the format shown in Figure 25. (On the RX01
and RX02, the high word specifies the track number rather than the cylinder
number.) Check the UCB of a currently mounted device to determine the
maximum physical address value for that type of device.
Note
On the RB80 and RM80, do not address cylinders 560 and 561. These two
cylinders are used for diagnostic testing only.

The function-dependent argument for IO$_SEARCH is as follows:

P1The physical disk address where the tape is positioned. The address is
expressed as sector, track, and cylinder in the format shown in Figure 25.
Figure 25 Starting Physical Address
31
P3:

16 15
Cylinder

8 7

0
Sector

Track

(Except RX01 and RX02)

16 15

31
P3:

Track

0
Sector

(RX01 and RX02 Only)

ZK0652GE

The function-dependent argument for IO$_SEEK is as follows:

P1The physical cylinder number where the disk heads are positioned. The
address is expressed in the format shown in Figure 26.
232 Disk Drivers

Disk Drivers
2.4 Disk Function Codes
Figure 26 Physical Cylinder Number Format
31

16 15
Not Used

0
Cylinder
ZK0653GE

The function-dependent argument for IO$_FORMAT is as follows:

P1The density at which an RX02 diskette is reformatted (see
Section 2.4.4).

2.4.1 Read
The read function reads data into a specified buffer from disk starting at a
specified disk address.
The operating system provides the following read function codes:

IO$_READVBLKRead virtual block

IO$_READLBLKRead logical block

IO$_READPBLKRead physical block

If a read virtual block function is directed to a volume that is mounted foreign,

that 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
same way as for a file-structured device.
Three function-dependent arguments are used with these codes: P1, P2, and P3.
These arguments are described in Section 2.4.
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 completes. A data check operation is also performed if
the volume that has been 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 RX01 and RX02 drivers do not support the data check function.
If IO$M_DATACHECK is specified with a read function code to a TU58, or if the
volume read has the characteristic data check all reads, a read check operation
is performed. This alters certain TU58 hardware parameters when the tape is
read. (The read threshold in the data recovery circuit is increased; if the tape has
any weak spots, errors are detected.)
The data check function modifier to a disk or tape can return five error codes in
the I/O status block:
SS$_CTRLERR

SS$_DRVERR

SS$_NONEXDRV

SS$_NORMAL

SS$_MEDOFL

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.
Disk Drivers 233

Disk Drivers
2.4 Disk Function Codes
2.4.2 Write
The write function writes data from a specified buffer to disk starting at a
specified disk address.
The operating system provides the following write function codes:

IO$_WRITEVBLKWrite virtual block

IO$_WRITELBLKWrite logical block

IO$_WRITEPBLKWrite 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
same way as for a file-structured device.
Three function-dependent arguments are used with these codes: P1, P2, and P3.
These arguments are described in Section 2.4.
The data check function modifier (IO$M_DATACHECK) can be used with all
write operations. If this modifier is specified, a data check operation is performed
after the write operation completes. 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 RX01
and RX02 drivers do not support the data check function.
If IO$M_DATACHECK is specified with a write function code to a TU58, or if
the volume written has the characteristic data check all writes, a write check
operation is performed. The write check verifies data written on the tape. First,
the specified data is written on the tape. Then the tape is reversed and the
TU58 controller reads the data internally to perform a checksum verification. If
the checksum verification is unsuccessful after eight attempts, the write check
operation is aborted and an error status is returned.
The inhibit retry function modifier (IO$M_INHRETRY) can be used
with all write functions. If that modifier is specified, all error recovery
attempts are inhibited. IO$M_INHRETRY takes precedence over
IO$M_DATACHECK. If both IO$M_INHRETRY and IO$M_DATACHECK 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. IO$M_INHRETRY has no effect on DSA disks.
The write deleted data function modifier (IO$M_DELDATA) can be used with the
write physical block (IO$_WRITEPBLK) function to the RX02. If this modifier is
specified, a deleted data address mark instead of the standard data address mark
is written preceding the data. Otherwise, the operation of the IO$_WRITEPBLK
function is the same; write data is transferred to the disk. When a successful
read operation is performed on this data, the status code SS$_RDDELDATA is
returned in the I/O status block rather than the usual SS$_NORMAL status code.
The IO$M_ERASE function modifier can be used with all write function codes to
erase a user-selected part of a disk. This modifier propagates an erase pattern
through the specified range. Section 2.4 describes the write function arguments
to be used with IO$M_ERASE.

234 Disk Drivers

Disk Drivers
2.4 Disk Function Codes
2.4.3 Sense Mode
Sense mode operations obtain current disk device-dependent characteristics that
are returned to the caller in the second longword of the I/O status block (see
Figure 28). The operating system provides the following function codes:

IO$_SENSEMODESense characteristics

IO$_SENSECHARSense characteristics

IO$_SENSEMODE is a logical function. IO$_SENSECHAR is a physical I/O

function and requires the access privilege necessary to perform physical I/O. No
device- or function-dependent arguments are used with either function.

2.4.4 Set Density

The set density function assigns a new density to an entire RX02 diskette.
The diskette is also reformatted: new data address marks are written (single
or double density) and all data fields are zeroed. Set density is a physical I/O
function and requires the access privilege necessary to perform physical I/O. The
following function code is provided:
IO$_FORMAT
IO$_FORMAT takes the following function-dependent argument:
P1The density at which the diskette is reformatted:
0 = single density (default)
1 = single density
2 = double density
The set density operation should not be interrupted before it is completed
(about 15 seconds). If the operation is interrupted, the resulting diskette might
contain illegal data address marks in both densities. The diskette must then be
completely reformatted and the function reissued.

2.4.5 Search
The search function positions a TU58 magnetic tape to the block specified. Search
is a physical I/O function and requires the access privilege necessary to perform
physical I/O. The operating system provides a single function code:
IO$_SEARCH
This function code takes the following function-dependent argument:
P1Specifies the block where the read/write head will be positioned. The low
byte contains the sector number in the range 0 to 127; the high byte contains
the track number in the range 0 to 3.
IO$_SEARCH can save time between read and write operations. For example,
nearly 30 seconds are required to completely rewind a tape. If the last read or
write operation is near the end of the tape and the next operation is near the
beginning of the tape, the search operation can begin after the last operation
completes, and the tape will rewind while the process is otherwise occupied. (The
search QIO is not completed until the search is completed. Consequently, if a
$QIOW system service request is issued, the process will be held up until the
search is completed.)

Disk Drivers 235

Disk Drivers
2.4 Disk Function Codes
2.4.6 Pack Acknowledge
The pack acknowledge 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. If directed to an RX02 disk, pack acknowledge also
determines the diskette density and updates the device-dependent information
returned by $GETDVI item codes DVI$_CYLINDERS, DVI$_TRACKS, DVI$_
SECTORS, DVI$_DEVTYPE, DVI$_CLASS, and DVI$_MAXBLOCK. If directed
to a DSA disk, pack acknowledge also sends the online packet to the controller.
The following 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 DCL commands INITIALIZE or MOUNT are issued.
For DSA disks, the IO$_PACKACK function locks the drives port selector on the
port that initiated the pack acknowledge function.
In addition, the IO$_PACKACK function updates device-dependent information
about DSA disks returned by $GETDVI.

2.4.7 Unload
The unload function clears the volume valid bit for all disk drives, makes
DSA disks available, and issues an unload command to the drive (spins down
the volume). The unload function reverses the function performed by pack
acknowledge (see Section 2.4.6). The following function code is provided:
IO$_UNLOAD
This function takes no function-dependent arguments.

2.4.8 Available
The available function clears the volume valid bit for all disk drives; that is, it
reverses the function performed by pack acknowledge (see Section 2.4.6). No
unload function is issued to the drive; therefore, those drives capable of spinning
down do not spin down. The following function code is provided:
IO$_AVAILABLE
This function takes no function-dependent arguments.

2.4.9 Seek
The seek function directs the read/write heads to move to the cylinder specified in
the P1 argument (see Sections 2.2.8 and 2.4, and Figure 26).

2.4.10 Write Check

The write check function verifies that data was written to disk correctly. The
data to be checked is addressed using physical disk addressing (sector, track, and
cylinder) (see Figure 25). If the request is directed to a DSA disk, you must
specify a logical block number, even though IO$_WRITECHECK is a physical I/O
function. The following function code is provided:
IO$_WRITECHECK

236 Disk Drivers

Disk Drivers
2.4 Disk Function Codes
A write QIO must be used to write data to disk before you enter this command.
IO$_WRITECHECK then reads the same block of data and compares it with the
data in the specified buffer. Three function-dependent arguments are used with
this code: P1, P2, and P3. These arguments are described in Section 2.4.
IO$_WRITECHECK is similar to the IO$M_DATACHECK function modifier for
write QIOs, except that IO$_WRITECHECK does not write the data to disk; it is
specified after data is written by a separate write QIO. Nonprivileged processes
can use the IO$M_DATACHECK modifier with IO$_WRITEVBLK (which does
not require access privilege) to determine whether data is written correctly. The
RX01 and RX02 drivers do not support the write check function.
The write check function and the data check function modifier to a TU58 can
return six error codes in the I/O status block: SS$_NORMAL,
SS$_CTRLERR, SS$_DRVERR, SS$_MEDOFL, SS$_NONEXDRV, and
SS$_WRTLCK.

2.4.11 Set Preferred Path

The set preferred path function specifies a preferred path for DSA disks. This
includes RA-series disks and disks accessed through the MSCP server. If a
preferred path is specified for a disk, the MSCP disk class drivers (DUDRIVER
and DSDRIVER) use the path as their first attempt to locate the disk and bring it
on line as a result of a DCL command MOUNT or failover of an already mounted
disk.
In addition, you can initiate failover of a mounted disk to force the disk to the
preferred path, or to use load-balancing information for disks accessed through
MSCP servers.
The function code is:
IO$_SETPRFPATH
The following is the function modifier:
IO$M_FORCEPATHCauses the disk class driver to select the server path
with the highest load available rating.
The P1 parameter contains the address of a counted ASCII string (.ASCIC). This
string is the node name of the HSC or system that is the preferred path. The
node name must match an existing node that is known to the local node and if
the node is a VAX or Alpha system, it must be running the MSCP server. This
function does not move the disk to the preferred path.
The PHYS_IO privilege is required for IO$_SETPRFPATH and
IO$M_FORCEPATH.
The following example shows the use of IO$_SETPRFPATH:
$assigndef
$qiodef
$iodef
$exitdef
dev:

.ascid /$254$DUA48:/

chnl:

.word

node:

.ascic /HSC001/

.entry start,0

Disk Drivers 237

Disk Drivers
2.4 Disk Function Codes
$assign_s
blbc

devnam=dev,chan=chnl

r0,done

$qiow_s

chan=chnl,func=#IO$_SETPRFPATH,p1=node

done:
$exit_s r0
.end start
This updates the local node I/O database to indicate that node HSC001 is the
preferred path for DUA48.
2.4.11.1 Forcing a Path Change
You can move a disk that is already mounted to its preferred path by specifying
the IO$M_FORCEPATH modifier. If a preferred path has not been specified for a
disk that is accessed through the MSCP server, the IO$M_FORCEPATH function
causes the disk class driver to use load-balancing information to select the server
path with the highest-load-available rating.
IO$M_FORCEPATH does not accept any arguments. If you intend to move a disk
to its preferred path, you must specify the preferred path in a separate $QIO
function.
The following example shows use of the IO$M_FORCEPATH function modifier:
$assigndef
$qiodef
$iodef
$exitdef
dev:

.ascid /$254$DUA197:/

chnl:

.word

.entry start,0
$assign_s
blbc

devnam=dev,chan=chnl

r0,done

$qiow_s

chan=chnl,func=#<IO$_SETPRFPATH!IO$M_FORCEPATH>

done:
$exit_s r0
.end

start

Note that forcing a path change places the disk in mount verification. New I/O
requests are suspended until mount verification is complete.
2.4.11.2 Using IO$_SETPRFPATH with Disks Dual-Pathed Between HSCs
You can use the IO$_SETPRFPATH and IO$M_FORCEPATH functions to load
balance disks that are dual-pathed between HSCs. The IO$M_FORCEPATH
function initiates failover of the disk on all nodes that have it mounted and
that have a direct path to the HSCs. Because the node that issues the IO$M_
FORCEPATH might not be the first one to attempt failover of the disk, it is
essential that all nodes with direct connections to the HSCs specify the same
preferred path for the disk. Only one node should issue the IO$M_FORCEPATH
request.

238 Disk Drivers

Disk Drivers
2.4 Disk Function Codes
2.4.11.3 Using IO$_SETPRFPATH with Disks Dual-Pathed Between Systems
You can use IO$M_FORCEPATH to load balance RA-series disks that are dualpathed between systems running the MSCP server. Both serving nodes should
specify the same preferred path. To move the disk between systems, the system
that currently has the disk on line through its local controller should issue the
IO$M_FORCEPATH request. The disk must be mounted on both serving nodes.
2.4.11.4 Using IO$_SETPRFPATH with Disks Accessed Through MSCP Servers
You can specify a preferred path for disks that are accessed through MSCP
servers; however, this specification overrides any load-balancing decisions.
Note that if a disk can be accessed through both HSC and MSCP servers, you
need not specify the HSC as a preferred path. HSC paths are always preferred to
server paths.
Using IO$M_FORCEPATH without a preferred path causes the disk class driver
to move the disk to the server with the highest available capacity.
2.4.11.5 Using IO$_SETPRFPATH with Phase I Volume Shadowing
You can specify IO$_SETPRFPATH for shadow set members, but not for virtual
units. IO$M_FORCEPATH is not supported for shadow set members or virtual
units.
2.4.11.6 Using IO$_SETPRFPATH with Phase II Volume Shadowing
IO$_SETPRFPATH and IO$M_FORCEPATH are supported for shadow set
members but not for virtual units.

2.5 I/O Status Block

Figure 27 shows the I/O status block (IOSB) for all disk device QIO functions
except sense mode. Figure 28 shows the I/O status block for the sense mode
function. Appendix A lists the status messages for all functions and devices. (The
OpenVMS system messages documentation provides explanations and suggested
user actions for these messages.)
Figure 27 IOSB Contents
31

16 15

Byte Count
(LowOrder Word)

Status

Byte Count
(HighOrder Word)
ZK0656GE

The byte count is a 32-bit integer that gives the actual number of bytes
transferred to or from the process buffer.

Disk Drivers 239

Disk Drivers
2.5 I/O Status Block
Figure 28 IOSB Contents for the Sense Mode Function
31

16 15

8 7

Status

Cylinders

Tracks

Sectors
ZK0657GE

The second longword of the I/O status block for the sense mode function returns
information about the cylinder, track, and sector configurations for the particular
device.

2.6 Disk Driver Programming Example

A sample VAX MACRO disk driver program, DISK_DRIVER.MAR, is shown in
Example 21. This sample program provides an example of optimizing access
time to a disk file. The program creates a file using Record Management Services
(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 ($QIO)
system service.
Example 21 DISK_DRIVER.MAR Disk Driver Programming Example
; ********************************************************************
;
.TITLE Disk Driver Programming Example
.IDENT /01/
;
; Define necessary symbols.
;
$FIBDEF
$IODEF
$RMSDEF

;Define file information block Offsets

;Define I/O function codes
;Define RMS-32 Return Status Values

;
; Local storage
;
; Define number of records to be processed.
;
NUM_RECS=100

;One hundred records

(continued on next page)

240 Disk Drivers

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
;
; Allocate storage for necessary data structures.
;
; Allocate File Access Block.
;
;
A file access block is required by RMS-32 to open and close a
;
file.
;
FAB_BLOCK:
;
$FAB
ALQ = 100,;Initial file size is to be
;100 blocks
FAC = PUT,;File Access Type is output
FNA = FILE_NAME,;File name string address
FNS = FILE_SIZE,;File name string size
FOP = CTG,;File is to be contiguous
MRS = 512,;Maximum record size is 512
;bytes
NAM = NAM_BLOCK,;File name block address
ORG = SEQ,;File organization is to be
;sequential
REM = FIX
;Record format is fixed length
;
; Allocate file information block.
;
;
A file information block is required as an argument in the
;
Queue I/O system service call that accesses a file.
;
FIB_BLOCK:
;
.BLKB FIB$K_LENGTH
;
;
; Allocate file information block descriptor.
;
FIB_DESCR:
.LONG
.LONG

FIB$K_LENGTH
FIB_BLOCK

;
;Length of the file
;information block
;Address of the file
;information block

;
; Allocate File Name Block
;
;
A file name block is required by RMS-32 to return information
;
concerning a file (for example, the resultant file name string
;
after logical name translation and defaults have been applied).
;
NAM_BLOCK:
$NAM

;
;
(continued on next page)

Disk Drivers 241

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
;
; Allocate Record Access Block
;
;
A record access block is required by RMS-32 for record
;
operations on a file.
;
RAB_BLOCK:
$RAB
FAB = FAB_BLOCK,;File access block address
RAC = SEQ,;Record access is to be
;sequential
RBF = RECORD_BUFFER,- ;Record buffer address
RSZ = 512
;Record buffer size
;
; Allocate direct address buffer
;
BLOCK_BUFFER:
.BLKB

1024

;Direct access buffer is 1024

;bytes

;
; Allocate space to store channel number returned by the $ASSIGN
; Channel system service.
;
DEVICE_CHANNEL:
;
.BLKW 1
;
;
; Allocate device name string and descriptor.
;
DEVICE_DESCR:
.LONG 20$-10$
.LONG 10$
10$:
.ASCII /SYS$DISK/
20$:

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

;
; Allocate file name string and define string length symbol.
;
FILE_NAME:
;
.ASCII /SYS$DISK:MYDATAFIL.DAT/
FILE_SIZE=.-FILE_NAME

;File name string

;File name string length

;
; Allocate I/O status quadword storage.
;
IO_STATUS:
.BLKQ 1
;
; Allocate output record buffer.
;

;
;

(continued on next page)

242 Disk Drivers

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
RECORD_BUFFER:
;
.BLKB 512
;Record buffer is 512 bytes
;
; ********************************************************************
;
;
Start Program
;
; ********************************************************************
;
;
;
;
;
;
;
;

The purpose of the program is to create a file called MYDATAFIL.DAT

using RMS-32; store information concerning the file; write 100
records, each containing its record number in every byte;
close the file; and then access, read, and write the file directly,
using the Queue I/O system service. If any errors are detected, the
program returns to its caller with the final error status in
register R0.
.ENTRY DISK_EXAMPLE,^M<R2,R3,R4,R5,R6> ;Program starting
;address

;
; First create the file and open it, using RMS-32.
;
PART_1:
;First part of example
$CREATE FAB = FAB_BLOCK
;Create and open file
BLBC
R0,20$
;If low bit = 0, creation
;failure
;
; Second, connect the record access block to the created file.
;
$CONNECT RAB = RAB_BLOCK
BLBC

R0,30$

;Connect the record access

;block
;If low bit = 0, creation
;failure

;
; Now write 100 records, each containing its record number.
;
MOVZBL #NUM_RECS,R6

;Set record write loop count

;
; Fill each byte of the record to be written with its record number.
;
10$:

SUBB3

R6,#NUM_RECS+1,R5

;Calculate record number

MOVC5

#0,(R6),R5,#512,RECORD_BUFFER ;Fill record buffer

;
; Now use RMS-32 to write the record into the newly created file.
;

(continued on next page)

Disk Drivers 243

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
$PUT
RAB = RAB_BLOCK
BLBC
R0,30$
SOBGTR R6,10$

;Put record in file

;If low bit = 0, 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 file information returned by
; RMS-32 and close the file.
;
MOVW

NAM_BLOCK+NAM$W_FID,FIB_BLOCK+FIB$W_FID ;Save file

;identification
MOVW
NAM_BLOCK+NAM$W_FID+2,FIB_BLOCK+FIB$W_FID+2 ;Save
;sequence number
MOVW
NAM_BLOCK+NAM$W_FID+4,FIB_BLOCK+FIB$W_FID+4 ;Save
;relative volume
$CLOSE FAB = FAB_BLOCK
;Close file
BLBS
R0,PART_2
;If low bit set, successful
;close
RET
;Return with RMS error status

20$
;
; Record stream connection or put record failure.
;
; Close file and return status.
;
30$:
PUSHL R0
;Save error status
$CLOSE FAB = FAB_BLOCK
;Close file
POPL
R0
;Retrieve error status
RET
;Return with RMS error status
;
; The second part of the example illustrates accessing the previously
; created file directly using the Queue I/O system service, randomly
; reading and writing various parts of the file, and then deaccessing
; the file.
;
; First, assign a channel to the appropriate device and access the
; file.
PART_2:
;
$ASSIGN_S DEVNAM = DEVICE_DESCR,- ;Assign a channel to file
CHAN = DEVICE_CHANNEL ;device
BLBC
R0,20$
;If low bit = 0, assign
;failure
MOVL
#FIB$M_NOWRITE!FIB$M_WRITE,- ;Set for read/write
FIB_BLOCK+FIB$L_ACCTL ;access
$QIOW_S CHAN = DEVICE_CHANNEL,- ;Access file on device channel
FUNC = #IO$_ACCESS!IO$M_ACCESS,- ;I/O function is
;access file
IOSB = IO_STATUS,;Address of I/O status
;quadword
P1 = FIB_DESCR
;Address of information block
;descriptor
BLBC
R0,10$
;If low bit = 0, access
;failure
MOVZWL IO_STATUS,R0
;Get final I/O completion
;status
(continued on next page)

244 Disk Drivers

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
BLBS
10$:

R0,30$

;If low bit set, successful

;I/O function
PUSHL R0
;Save error status
$DASSGN_S CHAN = DEVICE_CHANNEL ;Deassign file device channel
POPL
R0
;Retrieve error status
RET
;Return with I/O error status

20$:
;
; The file 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 of the record in the
; file. Thus a particular record can be read or written simply by
; specifying its record number in the file.
;
; The following code reads two 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 file in reverse order.
; This results in record 1 having the old contents of record 2 and
; record 2 having the old contents of record 1, and so forth. After
; the example has been run, it is suggested that the file dump
; utility be used to verify the change in data positioning.
;
30$

MOVZBL #1,R6

;Set starting record (block)

;number

;
; Read next two records into block buffer.
;
40$:

$QIO_S CHAN
FUNC
IOSB
P1 =
P2 =
P3 =

= DEVICE_CHANNEL,- ;Read next two records from

;file channel
= #IO$_READVBLK,- ;I/O function is read virtual
;block
= IO_STATUS,;Address of I/O status
;quadword
BLOCK_BUFFER,;Address of I/O buffer
#1024,;Size of I/O buffer
R6
;Starting virtual block of
;transfer
50$
;Check I/O completion status

BSBB
;
; Check each record to make sure it contains the correct data.
;
SKPC

R6,#512,BLOCK_BUFFER

;Skip over equal record

;numbers in data

BNEQ

60$

ADDL3

#1,R6,R5

;If not equal, data match

;failure
;Calculate even record number

SKPC

R5,#512,BLOCK_BUFFER+512 ;Skip over equal record

;numbers in data
60$
;If not equal, data match
;failure

BNEQ

;
; Record data matches.
;
; Write records in reverse order in file.
;
(continued on next page)

Disk Drivers 245

Disk Drivers
2.6 Disk Driver Programming Example
Example 21 (Cont.) DISK_DRIVER.MAR Disk Driver Programming Example
$QIOW_S CHAN = DEVICE_CHANNEL,FUNC = #IO$_WRITEVBLK,IOSB = IO_STATUS,P1 = BLOCK_BUFFER+512,P2 = #512,P3 = R6
BSBB
50$
ADDL3 #1,R6,R5
$QIOW_S CHAN = DEVICE_CHANNEL,FUNC = #IO$_WRITEVBLK,IOSB = IO_STATUS,P1 = BLOCK_BUFFER,P2 = #512,P3 = R5
BSBB
50$
ACBB
#NUM_RECS-1,#2,R6,40$

;Write even-numbered record in

;odd slot
;I/O function is write virtual
;block
;Address of I/O status
;quadword
;Address of even record buffer
;Length of even record buffer
;Record number of odd record
;Check I/O completion status
;Calculate even record number
;Write odd numbered record in
;even slot
;I/O function is write virtual
;block
;Address of I/O status
;quadword
;Address of odd record buffer
;Length of odd record buffer
;Record number of even record
;Check I/O completion status
;Any more records to be read?

BRB

70$

;
; Check I/O completion status.
;
50$:

BLBC

R0,70$

MOVZWL IO_STATUS,R0
BLBC
RSB

R0,70$

;If low bit = 0, service

;failure
;Get final I/O completion
;status
;If low bit = 0, I/O function
;failure

;
; Record number mismatch in data.
;
60$:

MNEGL

#4,R0

;
; All records have been read, verified,
;
70$:
PUSHL R0
$QIOW_S CHAN = DEVICE_CHANNEL,FUNC = #IO$_DEACCESS
$DASSGN_S CHAN = DEVICE_CHANNEL
POPL
R0
RET
.END

DISK_EXAMPLE

246 Disk Drivers

;Set dummy error status value

and odd/even pairs inverted
;Save final status
;Deaccess file
;I/O function is deaccess file
;Deassign file device channel
;Retrieve final status
;

3
Magnetic Tape Drivers
This chapter describes the use of magnetic tape drivers, drives, and controllers.

3.1 Magnetic Tape Controllers and Drives

The sections that follow describe magnetic tape controllers and drives; however,
note that not all supported devices are described here. Refer to the Software
Product Description for the OpenVMS Operating System for Alpha and VAX for
the definitive list of supported devices.

3.1.1 TM03 Magnetic Tape Controller (VAX Only)

On VAX systems, the TM03 magnetic tape controller supports up to eight TE16,
TU45, or TU77 tape drives. These dual-density (800 or 1600 bit/inch) drives
differ in speed: the TE16, TU45, and TU77 read and write data at 45, 75, and
125 inches per second, respectively. Each drive can hold one 2400-foot, 9-track
reel with a capacity of approximately 40 million characters. The TM03 controller
is connected to the MASSBUS through a MASSBUS adapter.

3.1.2 TS11 Magnetic Tape Controller (VAX Only)

On VAX systems, the TS11 magnetic tape controller connects to the UNIBUS
through a UNIBUS adapter and supports one TS04 tape drive. The TS11/TS04
is a single-density tape system that supports 1600-bit/inch, phase-encoded
recording.
The TSU05 and the TSV05 magnetic tape drives are used with UNIBUS and
Q-bus systems, respectively.

3.1.3 TM78 and TM79 Magnetic Tape Controllers (VAX Only)

On VAX systems, the TM78 and TM79 magnetic tape controllers support up to
four TU78 tape drives. These high-performance, dual-density drives (1600 or
6250 bit/inch) operate at 125 inches per second (ips) using a 2400-foot reel of tape
with a capacity of approximately 146 million characters when recorded in the
GCR (6250 bit/inch) mode. The TM78 and TM79 controllers are connected to the
MASSBUS through a MASSBUS adapter.

3.1.4 TU80 Magnetic Tape Subsystem (VAX Only)

On VAX systems, the TU80 is a single-density, dual-speed (25 or 100 ips)
magnetic tape subsystem that uses streaming tape technology (see Section 3.2.7).
It supports one drive per subsystem. The TU80 connects to the UNIBUS through
a UNIBUS adapter and completely emulates the TS11 magnetic tape controller.

Magnetic Tape Drivers 31

Magnetic Tape Drivers

3.1 Magnetic Tape Controllers and Drives
3.1.5 TA81 Magnetic Tape Subsystem
On VAX and Alpha systems, the TA81 is a high-performance, dual-density (1600
or 6250 bit/inch), dual-speed (25 or 75 ips) magnetic tape subsystem that uses
streaming tape technology (see Section 3.2.7). It attaches to an HSC50 controller,
and is managed with the TMSCP control protocol for tape mass storage.

3.1.6 TU81 Magnetic Tape Subsystem (VAX Only)

On VAX systems, the TU81 is a high-performance, dual-density (1600 or 6250
bit/inch), dual-speed (25 or 75 in/s) magnetic tape subsystem that uses streaming
tape technology (see Section 3.2.7). It connects to the UNIBUS through a
UNIBUS adapter, and is managed with the TMSCP control protocol for tape mass
storage.

3.1.7 TU81-Plus Magnetic Tape Subsystem (VAX Only)

On VAX systems, the TU81-Plus is an enhanced version of the TU81 streaming
tape subsystem. It is a 9-track, dual-speed, dual-density, ANSI-standard, halfinch magnetic tape subsystem. In addition, it has a 256-kilobyte (KB) cache
buffer that temporarily stores commands and data moving to and from the tape
unit. The buffer increases the amount of time the tape drive is able to stream,
thereby increasing performance. The TU81-Plus connects to all VAXBI, UNIBUS,
and Q-bus systems using the KLESI-B, KLESI-U, and KLESI-Q adapters.

3.1.8 TA90 Magnetic Tape Subsystem

On VAX and Alpha systems, the TA90 is a 5- by 4-inch, 200-MB cartridge tape,
fully read- and write-compatible with the IBM 3480 format. The TA90 includes
a master controller and a dual transport unit. As many as three additional dual
transport slave units can be connected to a single TA90 master controller for
a total of eight drives. The controller connects to the HSC 5X-DA high-speed
channel card in the HSC.
TA90 tape drives can be equipped with optional stack loaders for unattended
backup operations. Each TA90 master has two dual-port STI connections to the
HSC. Such dual pathing allows each control unit to service two HSC controllers,
which significantly increases tape drive availability. The TA90 subsystem
includes a 2-MB cache that allows the controller to prefetch upcoming commands
and store them while completing current data transfers. This behavior helps
optimize performance. The TA90 is a TMSCP device.

3.1.9 RV20 Write-Once Optical Drive (VAX Only)

On VAX systems, the RV20, a 2 GB, double-sided, write-once optical (WORM)
disk drive, is accessed sequentially similar to a tape. A 100-bit error correction
code (ECC) protects user data. The controller performs bad block replacement.
Three RV20 slaves can be daisy-chained to the subsystem controller in the RV20
master for a total of four drives.
RV02 cartridges can be used on any Compaq RV20 optical subsystem.
The average access time is 212.5 ms with an average seek rate of 150 ms. The
maximum data transfer rate is 262 KB per second (formatted and sustained) with
a burst rate of 1.33 MB per second.

32 Magnetic Tape Drivers

Magnetic Tape Drivers

3.1 Magnetic Tape Controllers and Drives
3.1.10 TK50 Cartridge Tape System (VAX Only)
On VAX systems, the TK50 is a 95-MB, 5.25-inch cartridge tape system that uses
streaming tape technology (see Section 3.2.7). The TK50 records data serially on
22 tracks using serpentine recording, rather than on separate (parallel) tracks.
Data written to tape is automatically read as it is written. A cyclic redundancy
check (CRC) is performed and the controller is notified immediately if an error
occurs on the tape.
The TQK50 is a dual-height Q-bus controller for the TK50 tape drive. The TUK50
is a UNIBUS controller for the same drive. The TZK50 is a SCSI controller for
the TK50 tape. Both the TQK50 and the TUK50 are TMSCP devices.
Section 3.1.13 describes compatibility among the TK50, TK70, and TZ30 magnetic
cartridge tape systems.

3.1.11 TK70 Cartridge Tape System (VAX Only)

On VAX systems, the TK70 is a 295-MB, 5.25-inch, streaming cartridge tape
system. (See Section 3.2.7 for information about streaming tape technology.) The
TK70 tape drive records data serially on 48 tracks using serpentine recording,
rather than separate (parallel) tracks. Data written to the tape is automatically
read as it is written. A CRC check is performed and the controller is notified
immediately if an error occurs on the tape.
The TQK70 is a dual-height, Q-bus controller for the TK70 magnetic tape drive.
The TK70 subsystem includes a 38-KB cache to optimize performance. The
TBK70 is a VAXBI-bus controller for the same drive. Section 3.1.13 describes
compatibility between the TK50 and TK70 magnetic cartridge tape systems.

3.1.12 TZ30 Cartridge Tape System

On VAX and Alpha systems, the TZ30 is a 95-MB, 5.25-inch, half-height cartridge
streaming tape drive with an embedded SCSI controller. See Section 3.2.7 for
information about streaming tape technology. The TZ30 uses TK50 cartridge
tapes. It records data serially on 22 tracks using serpentine recording, rather
than separate parallel tracks. Section 3.1.13 describes compatibility between the
TK50, TK70, and TZ30 magnetic cartridge tape systems.

3.1.13 Read and Write Compatibility Between Cartridge Tape Systems

When you insert a cartridge tape into the TZ30, TK50, and TK70 tape drives, the
hardware initializes the media to a device-specific recording density automatically.
Depending on the type of cartridge and the type of drive on which it is formatted
(inserted and initialized), full read and write access to tape cartridges may not be
permitted.
Formatting a Blank TK50 Cartridge Tape
A blank, unformatted TK50 cartridge can be formatted on the TK50, TK70, and
TZ30 cartridge systems. For example, a TK70 tape drive has full read and write
access to a TK50 cartridge formatted on a TK70 drive. Once the cartridge tape is
formatted on a particular tape drive, the tape drive has full read and write access
to the cartridge tape.

Magnetic Tape Drivers 33

Magnetic Tape Drivers

3.1 Magnetic Tape Controllers and Drives
Formatting a Previously Initialized TK50 Cartridge Tape
If a TK50 cartridge tape is formatted on a TZ30 or TK50 cartridge tape drive,
the TZ30 and TK50 drives initialize the TK50 cartridge to TK50 density. The
following table summarizes the types of access available:
TK50
Controller

Read

Write

Yes

Yes

TQK50

Yes

Yes

TQK70

Yes

No

TZ30

1 Has

an internal controller.

The TK70 tape drive can read data on a TK50 cartridge formatted on a TK50 or
TZ30 tape drive.
Formatting a TK50 or TK52 Cartridge Tape on a TK70 Tape Drive
If a TK50 or TK52 cartridge tape is formatted on a TK70 tape drive, the TK70
cartridge tape drive initializes the TK50 or TK52 cartridge tape to TK70 density.
The following table summarizes the types of access available:
TK50
Controller

TK52

Read

Write

Read

Write

No

No

No

No

TQK50

No

No

No

No

TQK70

Yes

Yes

Yes

Yes

TZ30

1 Has

an internal controller.

The TK50 and TZ30 tape drives cannot read or write data on a TK50 cartridge
tape formatted on a TK70 drive.

3.2 Driver Features

The magnetic tape drivers provide the following features:

Multiple master adapters and slave formatters

Different types of devices on a single MASSBUS adapter; for example, an

RP05 disk and a TM03 tape formatter

Reverse read function (except for the TZ30 and TK50 on TUK50 and TQK50
controllers)

Reverse data check function (except for the TZ30, TS11, and TK50 on TUK50
and TQK50 controllers)

Data checks on a per-request, per-file, or per-volume basis (except for the

TS11)

Full recovery from power failure for online drives with volumes mounted,
including repositioning by the driver (except on VAXstation 2000 and
MicroVAX 2000 systems)

34 Magnetic Tape Drivers

Magnetic Tape Drivers

3.2 Driver Features

Extensive error recovery algorithms; for example, non-return-to-zero-inverted

(NRZI) error correction

Logging of device errors in a file that may be displayed by field service or

customer personnel

Online diagnostic support for drive-level diagnostics

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

3.2.1 Dual-Path HSC Tape Drives

A dual-path HSC tape drive is a drive that connects to two HSCs, both of which
have the same nonzero tape allocation class. The operating system recognizes the
dual-pathed capability of such a tape drive under the following circumstances:
( 1 ) the operating system has access to both HSCs and ( 2 ) select buttons for both
ports are depressed on the tape drive.
If one port fails, the operating system switches access to the operational port
automatically, provided that the allocation class information has been defined
correctly.

3.2.2 Dynamic Failover and Mount Verification

Dynamic failover occurs on dual-pathed tape drives if mount verification is unable
to recover on the current path and an alternate path is available. The failover
occurs automatically and transparently and then mount verification proceeds.
A device enters mount verification when an I/O request fails because the device
has become inoperative. This might occur in the following instances:

The device is accidentally placed off line.

The active port of an HSC-connected drive fails.

A hardware error occurs.

The device is set to write protected during a write operation.

When the device comes back on line, either through automatic failover or operator
intervention, the operating system validates the volume, restores the tape to the
position when the I/O failure occurred, and retries the failed request.

3.2.3 Tape Caching

The RV20, TA90, TK70, and TU81-Plus contain write-back volatile caches. The
host enables write-back volatile caches explicitly, either on a per-unit basis or
on a per-command basis. To enable caching on a per-unit basis, enter the DCL
MOUNT command specifying the qualifier /CACHE=TAPE_DATA.
The Backup utility enables caching on a per-command basis. The user can
implement caching on a per-command basis at the QIO level by using the IO$M_
NOWAIT function modifiers on commands where it is legal (see Table 34). In
the unlikely event that cached data is lost, the system returns a fatal error and
the device accepts no further I/O requests. Use the IO$M_FLUSH function code
to ensure that all write-back-cached data is written out to the specified tape unit.
The IO$_PACKACK, IO$_UNLOAD, IO$_REWINDOFF, and IO$_AVAILABLE
function codes also flush the cache.

Magnetic Tape Drivers 35

Magnetic Tape Drivers

3.2 Driver Features
3.2.4 Master Adapters and Slave Formatters
The operating system supports the use of many 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.
The operating system also supports the use of multiple slave formatters per
master adapter on a system. For example, more than one TM03 or TM78
magnetic tape formatter per MBA can be used on a system. A slave formatter
accepts data and commands from a master adapter and directs the operation of
one or more slave drives. The TM03 and the TM78 are slave formatters. The
TE16, TU45, TU77, and TU78 magnetic tape drives are slave drives.

3.2.5 Data Check

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

Per requestYou 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 volumeYou can specify the characteristics data check all reads and
data check all writes when the volume is mounted. The OpenVMS DCL
Dictionary describes volume mounting and dismounting. The OpenVMS
System Services Reference Manual describes the Mount Volume ($MOUNT)
and Dismount Volume ($DISMOU) system services.

Per fileYou 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 1 of this manual and the OpenVMS Record Management Services
Reference Manual both describe file access.

Data check is distinguished from a BACKUP/VERIFY operation, which writes an

entire save set, rewinds, and then compares the tape to the original tape.
See Section 3.1.10 for information on TK50 data check.
Note
Read and write operations with data check can result in very slow
performance on streaming tape drives.

36 Magnetic Tape Drivers

Magnetic Tape Drivers

3.2 Driver Features
3.2.6 Error Recovery
Error recovery is aimed at performing all possible operations that enable an I/O
operation to complete successfully. Magnetic tape error recovery operations fall
into the following two categories:

Handling special conditions, such as power failure and interrupt timeout

Retrying nonfatal controller or drive errors

The error recovery algorithm uses a combination of these types of error recovery
operations to complete an I/O operation.
Power failure recovery consists of repositioning the reel to the position held at
the start of the I/O operation in progress at the time of the power failure, and
then reexecuting this operation. This repositioning might or might not require
operator intervention to reload the drives. When such operator intervention
is required, device not ready messages are sent to the operator console to
solicit reloading of mounted drives. Power failure recovery is not supported on
VAXstation 2000 and MicroVAX 2000 systems.
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.
If a nonfatal controller/drive error occurs, the driver (or the controller, depending
on the type of drive) attempts to reexecute the I/O operation up to 16 times before
returning a fatal error. The driver repositions the tape before each retry.
The inhibit retry function modifier (IO$M_INHRETRY) inhibits all normal
(nonspecial conditions) error recovery. If an error occurs, and the request includes
that modifier, the operation is terminated immediately and the driver returns
a failure status. IO$M_INHRETRY has no effect on power failure and timeout
recovery.
The driver can write up to 16 extended interrecord gaps during the error
recovery for a write operation. For the TE16, TU45, and TU77 magnetic tape
drives, writing these gaps can be suppressed by specifying the inhibit extended
interrecord gap function modifier (IO$M_INHEXTGAP). This modifier is ignored
for the other magnetic tape drives.

3.2.7 Streaming Tape Systems

Streaming tape systems, such as the TK50, TK70, TU80, TU81, TU81-Plus, TA81,
and TZ30, use the supply and takeup reel mechanisms to control tape speed and
tension directly, which eliminates the need for more complex and costly tension
and drive components. Streaming tapes have a very simple tape path, much like
an audio reel-to-reel recorder.
Note
Read and write operations with data check can result in very slow
performance on streaming tape drives.

Because the motors driving the reels are low-powered and because there is no
tape buffering, streaming tape drives are not capable of starting and stopping in
the interrecord gaps like conventional tape drives. When a streaming tape does
have to stop, the following events occur:
1. The tape slowly coasts forward to a stop.
Magnetic Tape Drivers 37

Magnetic Tape Drivers

3.2 Driver Features
2. It backs up over a section previously processed.
3. It halts to await the next command.
4. It accelerates so that, when the original interrecord gap is encountered, the
tape is moving at full speed.
These steps, allowing the tape to reposition, require approximately one-half
second to complete on TU8x tapes and about 3 seconds on TK50 tapes. If the
operating system is not capable of writing to, or reading from, a streaming tape
drive at a rate that will keep the drive in constant motion (streaming) the drive
repositions itself when it runs out of commands to execute. That produces a
situation known as thrashing, in which the relatively long reposition times
exceed the time spent processing data and the result is lower-than-expected data
throughput.
Thrashing is entirely dependent on how fast the system can process data relative
to the tape drive speed while streaming. Consequently, the greatest efficiency is
obtained when you provide sufficient buffering to ensure continuous tape motion.
Some streaming tape drives such as the TU80, TU81, TU81-Plus, and TA81 are
dual-speed devices that automatically adjust the tape speed to maximize data
throughput and minimize thrashing.
The TK50 writes up to seven filler records to keep the tape in motion. These
records are ignored when the data is read.

3.3 Magnetic Tape Driver Device Information

You can obtain information on all magnetic tape device characteristics by using
the Get Device/Volume Information ($GETDVI) system service. (Refer to the
OpenVMS System Services Reference Manual.)
$GETDVI returns magnetic tape characteristics when you specify the item
codes DVI$_DEVCHAR, DVI$_DEVCHAR2, DVI$_DEVDEPEND, and DVI$_
DEVDEPEND2. Tables 31, 32, and 33 list these characteristics. The
$DEVDEF macro defines the device-independent characteristics, the $MTDEF
macro defines the device-dependent characteristics, and the $MT2DEF macro
defines the extended device characteristics. The extended device characteristics
apply only to the TU81-Plus tape drive.
Table 31 Magnetic Tape Device-Independent Characteristics
Characteristic1

Meaning
Dynamic Bits (Conditionally Set)

DEV$M_AVL

Device is on line and available.

DEV$M_FOR

Volume is foreign.

DEV$M_MNT

Volume is mounted.

DEV$M_RCK

Perform data check on all read operations.

DEV$M_WCK

Perform data check on all write operations.

1 Defined

by the $DEVDEF macro.

(continued on next page)

38 Magnetic Tape Drivers

Magnetic Tape Drivers

3.3 Magnetic Tape Driver Device Information
Table 31 (Cont.) Magnetic Tape Device-Independent Characteristics
Characteristic1

Meaning
Static Bits (Always Set)

DEV$M_FOD

Device is file-oriented.

DEV$M_IDV

Device is capable of input.

DEV$M_ODV

Device is capable of output.

DEV$M_SQD
DEV$M_WBC
1 Defined
2 This

Device is capable of sequential access.

2

Device is capable of write-back caching.

by the $DEVDEF macro.

bit is located in DVI$_DEVCHAR2.

Table 32 Device-Dependent Information for Tape Devices

Characteristic1

Meaning

MT$M_LOST

If set, the current tape position is unknown.

MT$M_HWL

If set, the selected drive is hardware write-locked.

MT$M_EOT

If set, an end-of-tape (EOT) condition was encountered by the

last operation to move the tape in the forward direction.

MT$M_EOF

If set, a tape mark was encountered by the last operation to

move the tape.

MT$M_BOT

If set, a beginning-of-tape (BOT) marker was encountered by

the last operation to move the 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 non-return-to-zero-inverted recording at 800
bits/inch 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 as follows:

MT$V_FORMAT
MT$S_FORMAT

MT$K_GCR_6250

Group-coded recording, 6250 bits/inch

MT$K_PE_1600

Phase-encoded recording, 1600 bits/inch

MT$K_NRZI_800

Non-return-to-zero-inverted recording,
800 bits/inch

MT$K_BLK_833

Cartridge block mode recording2

Specifies the format in which all data transfers are performed.

A possible format value is as follows:
MT$K_NORMAL11

MT$_FASTSKIP_USED

1 Defined
2 Only

Normal PDP-11 format. Data bytes

are recorded sequentially on tape with
each byte occupying exactly one frame.

If set, the most recent IO$_SKIPFILE function was performed

using the optimized SCSI space-by-file-marks algorithm.
(See Section 3.4.4 for more information about the IO$M_
ALLOWFAST modifier to the IO$_SKIPFILE function.)

by the $MTDEF macro.

for the TK50 and TZ30 tape drives.

Magnetic Tape Drivers 39

Magnetic Tape Drivers

3.3 Magnetic Tape Driver Device Information
Table 33 Extended Device Characteristics for Tape Devices
Characteristic1

Meaning

MT2$V_WBC_ENABLE

If set, write-back caching is enabled for this unit.

MT2$V_RDC_DISABLE

If set, read caching is disabled for this unit.

1 Defined by the $MT2DEF macro. Only for the TU81-Plus. Initial device status will show both of
these bits cleared; write-back caching will be disabled, read caching will be enabled.

DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class names,
which are defined by the $DCDEF macro. DVI$_DEVBUFSIZ returns the buffer
size. The buffer size is the default to be used for tape transfers (normally 2048
bytes). The device class for magnetic tapes is $DCTAPE, and the device type is
determined by the magnetic tape model. For example, the device type for the
TA78 is DT$_TA78; for the TA81 it is DT$_TA81.

3.4 Magnetic Tape Function Codes

The magnetic tape driver can perform logical, virtual, and physical I/O functions.
Foreign-mounted devices do not require privileges to perform logical and virtual
I/O requests.
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. The results of logical and physical I/O operations are
unpredictable if an ACP is present.
Virtual I/O functions require intervention by an ACP and must be executed
in a prescribed order. The normal order is to create and access a file, write
information to that file, and deaccess the file. Subsequently, when you access the
file, you read the information and then deaccess the file. You can write over the
file when the information it contains is no longer useful and the file has expired.
Any number of bytes (from a minimum of 14 to a maximum of 65,535) 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 for
the function actually to be executed. If it is not, either a device not mounted or
invalid volume status is returned in the I/O status block.
Table 34 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 1 describes the QIO level interface to the magnetic tape
device ACP. Chapter 10 describes features to improve performance for larger file
transfers.

310 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Table 34 Magnetic Tape I/O Functions
Function Code

Arguments

Type1

Function Modifiers

Function

IO$_ACCESS

P1,[P2],[P3],[P4],[P5]

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
(EOT) marker.

IO$_ACPCONTROL

P1,[P2],[P3],[P4], [P5]

IO$M_DMOUNT

Perform
miscellaneous
control functions.2

IO$_AVAILABLE

IO$_CREATE

P1,[P2][,[P3],[P4],[P5]

IO$_DEACCESS

P1,[P2],[P3],[P4],[P5]

Clear volume valid

bit.
IO$M_CREATE
IO$M_ACCESS

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

IO$_DSE3

IO$_FLUSH

Flush the controller

cache to tape.

Write user labels.

Initialize volume
valid bit.

IO$_MODIFY

P1,[P2],[P3],[P4],[P5]

IO$_PACKACK

IO$M_NOWAIT

Erase a prescribed
section of the tape.

IO$_READLBLK10

P1,P2

IO$M_DATACHECK4
IO$M_INHRETRY
IO$M_REVERSE5

Read logical block.

IO$_READPBLK10

P1,P2

IO$M_DATACHECK4
IO$M_INHRETRY
IO$M_REVERSE5

Read physical block.

IO$_READVBLK10

P1,P2

IO$M_DATACHECK4
IO$M_INHRETRY
IO$M_REVERSE5

Read virtual block.

IO$_REWIND

IO$M_INHRETRY
IO$M_NOWAIT
IO$M_RETENSION

Reposition tape to
the beginning-oftape (BOT) marker.

IO$_REWINDOFF

IO$M_INHRETRY
IO$M_NOWAIT
IO$M_RETENSION

Rewind and unload

the tape on the
selected drive.

1V

= virtual; L = logical; P = physical.

2 See

Section 1.6.8 for more information.

for TMSCP drives, and TZK50, and TZ30 tape devices.

3 Only
4 Not

for TS04 and TU80 tape devices.

5 Not

for TUK50 and TQK50 tape devices.

10 On

OpenVMS Alpha, P1 supports a 64-bit address.

(continued on next page)

Magnetic Tape Drivers 311

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Table 34 (Cont.) Magnetic Tape I/O Functions
Type1

Function Modifiers

Function

IO$_SENSECHAR

[P1],[P2]

IO$M_INHRETRY

Sense the tape

characteristics and
return them in the
I/O status block.

IO$_SENSEMODE

[P1],[P2]6

IO$M_INHRETRY

Sense the tape

characteristics and
return them in the
I/O status block.

IO$_SETCHAR

P1,[P2]6

Set tape
characteristics
for subsequent
operations.

IO$_SETMODE

P1,[P2]6

Set tape
characteristics
for subsequent
operations.

IO$_SKIPFILE

P1

IO$M_INHRETRY
IO$M_NOWAIT7
IO$M_ALLOWFAST

Skip past a specified

number of tape
marks in either a
forward or reverse
direction.

IO$_SKIPRECORD

P1

IO$M_INHRETRY
IO$M_NOWAIT7

Skip past a specified

number of blocks in
either a forward or
reverse direction.

IO$M_INHRETRY
IO$M_NOWAIT

Rewind and unload

the tape on the
selected drive.

IO$M_ERASE8
IO$M_DATACHECK4
IO$M_INHRETRY
IO$M_INHEXTGAP9
IO$M_NOWAIT7

Write logical block.

IO$M_INHRETRY
IO$M_INHEXTGAP9
IO$M_NOWAIT7

Write an extended
interrecord gap
followed by a tape
mark.

IO$M_ERASE8
IO$M_DATACHECK4
IO$M_INHRETRY
IO$M_INHEXTGAP9
IO$M_NOWAIT7

Write physical
block.

Function Code

Arguments

IO$_UNLOAD

IO$_WRITELBLK10

P1,P2

IO$_WRITEOF10

IO$_WRITEPBLK10

1V

P1,P2

= virtual; L = logical; P = physical.

4 Not

for TS04 and TU80 tape devices.

6 The

P1 and P2 arguments for IO$_SENSEMODE and IO$_SENSECHAR and the P2 argument for IO$_SETMODE and
IO$_SETCHAR are for TMSCP drives only.
7 Only

for RV20, TA90, TK70, and TU81-Plus drives.

8 Takes
9 Only
10 On

no arguments; valid only for TMSCP drives, and TZK50 and TZ30 tape devices.

for TE16, TU45, and TU77 tape drives.

OpenVMS Alpha, P1 supports a 64-bit address.

(continued on next page)

312 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Table 34 (Cont.) Magnetic Tape I/O Functions
Function Code

Arguments

IO$_WRITEVBLK

1V

10

P1,P2

Type1
V

Function Modifiers

Function
4

IO$M_DATACHECK
IO$M_INHRETRY
IO$M_INHEXTGAP9
IO$M_NOWAIT7

Write virtual block.

= virtual; L = logical; P = physical.

4 Not

for TS04 and TU80 tape devices.

7 Only

for RV20, TA90, TK70, and TU81-Plus drives.

9 Only

for TE16, TU45, and TU77 tape drives.

10 On

OpenVMS Alpha, P1 supports a 64-bit address.

The function-dependent arguments for IO$_CREATE, IO$_ACCESS,

IO$_DEACCESS, IO$_MODIFY, IO$_ACPCONTROL are as follows:

P1The address of the file information block (FIB) descriptor.

P2Optional. The address of the file name string descriptor. If specified

with IO$_ACCESS, the name identifies the file being sought. If specified with
IO$_CREATE, the name is the name of the created file.

P3Optional. The address of the word that is to receive the length of the
resultant file name string.

P4Optional. The address of a descriptor for a buffer that is to receive the

resultant file name string.

P5Optional. The 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, P5 is the address of the attribute descriptor list for the
new file. All file attributes for IO$_MODIFY are ignored.

See Chapter 1 for more information on these functions.

The function-dependent arguments for IO$_READVBLK,
IO$_READLBLK, IO$_READPBLK, IO$_WRITEVBLK,
IO$_WRITELBLK, and IO$_WRITEPBLK are as follows:

P1The 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 buffer that is to be written on the tape. On OpenVMS Alpha,
P1 can be a 64-bit address.

P2The length of the buffer specified by P1.

The function-dependent argument for IO$_SKIPFILE and IO$_SKIPRECORD is:

P1The 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 P1 can specify is 32,767.)

Magnetic Tape Drivers 313

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Example 31 shows the correct method of defining the P1 parameter in an
IO$_SKIPRECORD QIO.
Example 31 Defining the P1 Parameter in a IO$_SKIPRECORD QIO
.
.
.
TAPE_CHAN:
.WORD
0
IOSB: .WORD
0
.WORD
0
.LONG
0
DEVICE: .ASCID /$127$MUA0:/
RECORD: .LONG
2000
;
.PSECT CODE,EXE,NOWRT
;
.ENTRY MT_IO,^M<>
;
$ASSIGN_S
CHAN=TAPE_CHAN,DEVNAM=DEVICE
BLBC
R0,EXIT_ERROR
;
$QIOW_S CHAN=TAPE_CHAN,FUNC=#IO$_SKIPRECORD,IOSB=IOSB,P1=RECORD
BLBC
R0,EXIT_ERROR
$EXIT_S R0
.
.
.
EXIT_ERROR:
$EXIT_S R0
.END
MT_IO

3.4.1 Read
The read function reads data into a specified buffer in the forward or reverse
direction starting at the next block position.
The operating system provides the following read function codes:

IO$_READVBLKRead virtual block

IO$_READLBLKRead logical block

IO$_READPBLKRead physical block

If a read virtual block function is directed to a volume that is mounted foreign,

it is converted to a read logical block function. If a read virtual block function is
directed to a volume that is mounted structured, the volume is handled the same
way as a file-structured device.
Two function-dependent arguments are used with these codes: P1 and P2. These
arguments are described in Section 3.4.
If the read function code includes the reverse function modifier
(IO$M_REVERSE), the drive reads the tape in the reverse direction instead of
the forward direction. IO$M_REVERSE cannot be specified for the TUK50 and
TQK50 devices.

314 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
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 completes. (The drive performs a space reverse or space
forward between the read and data check operations.) A data check operation
is also performed if the volume that was 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 TS04 and TU80 tape drives do not support the data check
function.
For read physical block and read logical block functions, the drive returns the
status SS$_NORMAL (not end-of-tape status) if either of the following conditions
occurs and no other error condition exists:

The tape is positioned past the end-of-tape (EOT) position at the start of the
read (forward or reverse) operation.

The tape enters the EOT region as a result of the read (forward) operation.

The transferred byte count reflects the actual number of bytes read.
If the drive reads a tape mark during a logical or physical read operation in
either the forward or reverse direction, any of the following conditions can return
an end-of-file (EOF) status:

The tape is positioned past the EOT position at the start of the read
operation.

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

The drive reads a tape mark as a result of a read operation but the tape does
not enter the EOT region.

An EOF status is also returned if the drive attempts a read operation in the
reverse direction when the tape is positioned at the beginning-of-tape (BOT)
marker. All conditions that cause an EOF status result in a transferred byte
count of zero.
If the drive attempts to read a block that is larger than the specified memory
buffer during a logical or physical read operation, a data overrun status is
returned. The buffer receives only the first part of the block. On a read in the
reverse direction (on drives other than the TK50 and TZ30) the buffer receives
only the latter part of the block. The transferred byte count is equal to the actual
size of the block. Read reverse starts at the top of the buffer. Therefore, the start
of the block is at P1 plus P2 minus the length read. The TUK50 and TZ30 cannot
actually perform read reverse operations; they must be simulated by the driver.
Therefore, the data returned are those that would have been returned had the
block been read in the forward direction.
It is not possible to read a block that is less than 14 bytes in length. Records that
contain less than 14 bytes are termed noise blocks and are completely ignored
by the driver.

Magnetic Tape Drivers 315

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
3.4.2 Write
The write function writes data from a specified buffer to tape in the forward
direction starting at the next block position.
The operating system provides the following write function codes:

IO$_WRITEVBLKWrite virtual block

IO$_WRITELBLKWrite logical block

IO$_WRITEPBLKWrite physical block

If a write virtual block function is directed to a volume that is mounted foreign,

the function is converted to a write logical block. If a write virtual block function
is directed to a volume that is mounted structured, the volume is handled the
same way as a file-structured device.
Two function-dependent arguments are used with these codes: P1 and P2. These
arguments are described in Section 3.4.
The IO$M_ERASE function modifier can be used with the IO$_WRITELBLK and
IO$_WRITEPBLK function codes to erase a user-selected part of a tape. This
modifier propagates an erase pattern of all zeros from the current tape position to
10 feet past the EOT position and then rewinds to the BOT marker.
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 completes. (The drive performs a space reverse between
the write and the data check operations.) The driver forces a data check operation
when an error occurs during a write operation. This ensures that the data can
be reread. 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 TS04 and TU80 tape drives do
not support the data check function.
If the IO$M_NOWAIT function modifier is specified, write-back caching is enabled
on a per-command basis. IO$M_NOWAIT is applicable only to TU81-Plus drives.
If the drive performs a write physical block or a write logical block operation, an
EOT status is returned if either of the following conditions occurs and no other
error condition exists:

The tape is positioned past the EOT position at the start of the write
operation.

The tape enters the EOT region as a result of the write operation.

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.

3.4.3 Rewind
The rewind 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.

316 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
If the IO$M_RETENSION function modifier is specified and the device supports
the retension operation, the rewind function positions the tape to the physicalend-of-tape (EOT) marker and rewinds the tape to the BOT marker. If the tape
does not support the IO$M_RETENSION modifer, a SS$_ILLIOFUNC error is
returned.
IO$_REWIND has no function-dependent arguments.

3.4.4 Skip File

The skip file function (IO$_SKIPFILE) skips past a specified number of tape
marks in either a forward or reverse direction. A function-dependent argument
(P1) is provided to specify the number of tape marks to be skipped, as shown
in Figure 31. 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 as an unsigned number in the I/O status block.)
Figure 31 IO$_SKIPFILE Argument
31
P1:

16 15
Not Used

0
File Count
ZK0671GE

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-oftape (EOT) marker does not terminate a skip file function in either the forward
or reverse direction. A negative skip file function leaves the tape positioned just
before a tape mark (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.
A skip file function in the forward direction can also be terminated if two
consecutive tape marks are encountered. Section 3.4.5.1 describes this feature.
The IO$M_ALLOWFAST modifier can be used with the IO$_SKIPFILE function
to provide better performance on SCSI tape drives that support the SCSI
space-by-file-marks command and the SCSI read position command.
When the IO$M_ALLOWFAST modifier is specified, a tape operation skips over
consecutive tape marks that are not immediately before the end-of-data position
on the medium. However, if two consecutive tape marks are detected immediately
before the end-of-data position on the tape, the tape is positioned between these
two tape marks and the SS$_ENDOFVOLUME status is returned.
The IO$M_ALLOWFAST modifier allows a SCSI tape subsystem to use the
optimized IO$_SKIPFILE if it is capabable. If a specific tape device does not
adequately support the optimized IO$_SKIPFILE that uses the SCSI space-byfile-marks command, the tape subsystem will use the standard space-by-records
algorithm.

Magnetic Tape Drivers 317

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
3.4.5 Skip Record
The skip record function skips past a specified number of physical tape blocks in
either a forward or reverse direction. A device- or function-dependent argument
(P1) specifies the number of blocks to skip, as shown in Figure 32. 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 as an unsigned number in the I/O status block. If a tape mark is
detected, the count is the number of blocks skipped, plus 1 (forward tape motion)
or minus 1 (reverse tape motion).
Figure 32 IO$_SKIPRECORD Argument
31
P1:

16 15
Not Used

0
Block Count
ZK0672GE

A skip record operation is terminated by the end-of-file (EOF) marker when

the tape moves in either direction, by the BOT marker when the tape moves in
reverse, and by the EOT marker when the tape moves forward.
A skip record function in the forward direction can also be terminated if the tape
was originally positioned between two tape marks. Section 3.4.5.1 describes this
feature.
3.4.5.1 Logical End-of-Volume (EOV) Detection
A skip file or skip record operation that uses the standard space-by-records
algorithm is terminated when two consecutive tape marks are encountered when
the tape moves in the forward direction. After the operation terminates, the
tape remains positioned between the two tape marks that were detected. The
I/O status block (IOSB) returns the status SS$_ENDOFVOLUME and the actual
number of files (or records) skipped during the operation prior to the detection of
the second tape mark. The skip count is returned in the high-order word of the
first longword of the IOSB.
An optimized skip file that uses the IO$M_ALLOWFAST modifier is terminated
when the end-of-data position is encountered. If two consecutive tape marks
immediately precede the end-of-data position on the tape, the tape is positioned
between these two tape marks. The SS$_ENDOFVOLUME status and the skip
count are returned in the IOSB.
Subsequent skip record (or skip file) requests terminate immediately when the
tape is positioned between the two tape marks, producing no net tape movement
and returning the SS$_ENDOFVOLUME status with a skip count of zero.
To move the tape beyond the second tape mark, you must employ another I/O
function. For example, the IO$_READLBLK function, if issued after receipt of
the SS$_ENDOFVOLUME status return, terminates with an
SS$_ENDOFFILE status and with the tape positioned just past the second tape
mark. From this new position, other skip functions could be issued to produce
forward tape motion (assuming there is additional data on the tape).

318 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
If three consecutive tape marks are encountered during a skip file function, you
must issue two IO$_READLBLK functions, the first to get the
SS$_ENDOFFILE return and the second to position the tape past the third tape
mark.

3.4.6 Write End-of-File

The write end-of-file (EOF) function writes an extended interrecord gap (of
approximately 3 inches for non-return-to-zero-inverted (NRZI) recording and 1.5
inches for phase-encoded (PE) recording) followed by a tape mark. No device- or
function-dependent arguments are used with IO$_WRITEOF.
An end-of-tape (EOT) status is returned in the I/O status block if either of the
following conditions is present and no other error conditions occur:

A write EOF function is executed while the tape is positioned past the EOT
marker.

A write EOF function causes the tape position to enter the EOT region.

3.4.7 Rewind Offline

The rewind offline function rewinds and unloads the tape on the selected drive.
The I/O operation is completed as soon as the tape movement is initiated. The
actual finish of the mechanical rewind or unload operation may occur long after
the I/O operation completes.
If the IO$M_RETENSION function modifier is specified and the device supports
the retension operation, the rewind offline function positions the tape to the
physical end-of-tape (EOT) marker and rewinds the tape to the beginning-of-tape
(BOT) marker. If the tape does not support the IO$M_RETENSION modifer, a
SS$_ILLIOFUNC error is returned.
No device- or function-dependent arguments are used with IO$_REWINDOFF.

3.4.8 Unload
The unload function rewinds and unloads the tape on the selected drive. The
unload function is functionally the same as the rewind offline function. If the
IO$M_NOWAIT function modifier is specified, the I/O operation is completed
as soon as the rewind operation is initiated. No device- or function-dependent
arguments are used with IO$_UNLOAD.

3.4.9 Sense Tape Mode

The sense tape mode function senses the current device-dependent and extended
device characteristics (see Tables 32 and 33).
The operating system provides the following function codes:

IO$_SENSEMODESense mode

IO$_SENSECHARSense characteristics

Sense mode requires logical I/O privilege. Sense characteristics requires physical
I/O privilege. For TMSCP drives, the sense mode function returns magnetic
tape information in a user-supplied buffer, which is specified by the following
function-dependent arguments:

P1Optional. Address of a user-supplied buffer.

P2Optional. Length of a user-supplied buffer.

Magnetic Tape Drivers 319

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
If P1 is not zero, the sense mode buffer returns the tape characteristics. (If P2=8,
the second longword of the buffer contains the device-dependent characteristics.
If P2=12, the second longword contains the device-dependent characteristics and
the third longword contains the tape densities that the drive supports and the
extended tape characteristics.) The extended characteristics are identical to the
information returned by DVI$_DEVDEPEND2 (see Table 33). Figure 33 shows
the contents of the P1 buffer.
Figure 33 Sense Mode P1 Buffer
P2=8:
31

16 15

8 7
Type

Buffer Size

0
Class

Tape Characteristics *
* From UCB$L_DEVDEPEND

P2=12:
31

16 15
Buffer Size

8 7
Type

0
Class

Tape Characteristics *
Extended Tape Characteristics * *

Supported Densities * *

* From UCB$L_DEVDEPEND
** From UCB$L_DEVDEPND2
ZK4854GE

Regardless of whether the P1 buffer is specified, the I/O status block returns the
device-dependent characteristics in the second longword (see Figure 36). These
characteristics are identical to the information returned by DVI$_DEVDEPEND
(see Table 32 in Section 3.3).

3.4.10 Set Mode

Set mode operations affect the operation and characteristics of the associated
magnetic tape device. The operating system defines 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. The following function codes are provided:

IO$_SETMODESet mode

IO$_SETCHARSet characteristics

These functions take the following device- or function-dependent arguments

(other arguments are ignored):

P1The address of a characteristics buffer.

320 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes

P2Optional. The length of the characteristics buffer. The default is 8 bytes.

If a length of 12 bytes is specified, the third longword (which is for TMSCP
drives only) specifies the extended tape characteristics.

Figure 34 shows the P1 characteristics buffer for IO$_SETMODE. Figure 35

shows the same buffer for IO$_SETCHAR.
Figure 34 Set Mode Characteristics Buffer for IO$_SETMODE
P2=8:
31

16 15
Buffer Size

0
Not Used

Tape Characteristics

P2=12:
31

16 15
Buffer Size

0
Not Used

Tape Characteristics
Extended Tape Characteristics

Reserved
ZK4856GE

Magnetic Tape Drivers 321

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Figure 35 Set Mode Characteristics Buffer for IO$_SETCHAR
P2=8:
31

16 15
Buffer Size

8 7
Type

0
Class

Tape Characteristics

P2=12:
31

16 15
Buffer Size

8 7
Type

0
Class

Tape Characteristics
Extended Tape Characteristics

Reserved
ZK4855GE

The first longword of the P1 buffer for the set characteristics function contains
information on device class and type, and the buffer size. The device class for
tapes is DC$_TAPE.
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 second longword of the P1 buffer for both the set mode and set
characteristics functions contains the tape characteristics. Table 35 lists the
tape characteristics and their meanings. The $MTDEF macro defines the symbols
listed. If P2=12, the third longword contains the extended tape characteristics for
TMSCP drives, which are listed in Table 36. The extended tape characteristics
are defined by the $MT2DEF macro and are identical to the information returned
by DVI$_DEVDEPEND2.
Table 35 Set Mode and Set Characteristics Magnetic Tape Characteristics
Characteristic1

Meaning

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 non-return-to-zeroinverted recording at 800 bits/inch. Even parity cannot be
selected for phase-encoded recording (tape density is MT$K_
PE_1600) or group-coded recording (tape density is MT$K_
GCR_6250) and is ignored.

1 Defined

by the $MTDEF macro.

(continued on next page)

322 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Table 35 (Cont.) Set Mode and Set Characteristics Magnetic Tape
Characteristics
Characteristic1

Meaning

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 drives tape
position is at the BOT marker. Possible density values are as
follows:

MT$V_FORMAT
MT$S_FORMAT

1 Defined
2 Only

MT$K_DEFAULT

Default system density.

MT$K_GCR_6250

Group-coded recording, 6250

bits/inch.

MT$K_PE_1600

Phase-encoded recording, 1600

bits/inch.

MT$K_NRZI_800

Non-return-to-zero-inverted
recording, 800 bits/inch.

MT$K_BLK_833

Cartridge block mode recording2 .

Specifies the format in which all data transfers are performed.

Possible format values are as follows:
MT$K_DEFAULT

Default system format.

MT$K_NORMAL11

Normal PDP-11 format. Data bytes

are recorded sequentially on tape
with each byte occupying exactly one
frame.

by the $MTDEF macro.

for the TK50 and TZ30.

Table 36 Extended Device Characteristics for Tape Devices

Characteristic1

Meaning

MT2$V_WBC_ENABLE

Enable write-back caching on a per-unit basis.

MT2$V_RDC_DISABLE

Disable read caching on a per-unit basis.

1 Defined

by the $MT2DEF macro. Only for TU81-Plus drives.

Application programs that change specific magnetic tape characteristics should

perform the following steps, as shown in Example 32 in Section 3.6:
1. Use the IO$_SENSEMODE function to read the current characteristics.
2. Modify the characteristics.
3. Use the set mode function to write back the results.
Failure to follow this sequence will result in clearing any previously set
characteristic.

3.4.11 Multiple Tape Density Support (Alpha Only)

As of Version 7.2, OpenVMS Alpha permits the selection of any density and any
compression supported by a tape drive. You can write to tapes using any density
and any compression algorithm supported by the tape drive. Exchanging tapes
among tape drives with different default settings for density or compression is
much easier with this enhancement.

Magnetic Tape Drivers 323

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
Mutiple tape density support is provided by changes in the QIO interface.
These changes are guided by device/density tables in system libraries and the
corresponding class drivers. This enhancement functions with tape drives that
support multiple tape density switching via the standard MODE_SENSE and
MODE_SELECT mechanisms. All density and compression options available for
a given drive will be accessible by the system. The QIO interface uses MT3DEF
to identify the drives, and to match them with their density and compression code
options. Some newer drives may not be included in the module.
Note
After the media has been initialized to a specific density, it will remain
that density until the media is initialized to a different density. For
example, if a COMPAC III media has been initialized with TK86
density, the DCL command MOUNT/DENSITY=TK85 will have no
effect because the media is initialized at TK86 density. Likewise,
BACKUP/DENSITY=TK85 will have no effect if the media is initialized
at TK86 density. However, BACKUP/DENS=TK85/INITIALIZE will
initialize the media to TK85 density.

These enhancements allow IO$_SETMODE and IO$_SENSEMODE to function

with most density values and a wider variety of drives. The system management
utilities BACKUP and MOUNT take advantage of this added functionality. For
more information about multiple tape density support with these utilities, refer
to the OpenVMS System Management Utilities Reference Manual. For more
information about enchancements in INITIALIZE, refer to the OpenVMS DCL
Dictionary.

3.4.12 Data Security Erase

The data security erase function erases all data from the current position of
the volume to 10 feet beyond the EOT reflective strip, and then rewinds the
tape to the BOT marker. It is a physical I/O function and requires the access
privilege necessary to perform physical I/O functions. The following function code
is provided:
IO$_DSE
If the function is issued when a tape is positioned at the BOT marker, all data on
the tape will be erased.
IO$_DSE takes no device- or function-dependent arguments.

3.4.13 Modify
Specifying the ATR$C_USERLABEL or ATR$C_ENDLBLAST attributes with
IO$_MODIFY results in a bad attribute error. If any other attributes are
specified, the IO$_MODIFY function is treated as a no-operation; that is, the
function returns success, but no action is performed.

324 Magnetic Tape Drivers

Magnetic Tape Drivers

3.4 Magnetic Tape Function Codes
3.4.14 Pack Acknowledge
The pack acknowledge function sets the volume valid bit for all magnetic tape
devices. It is a physical I/O function and requires the access privilege to perform
physical I/O. The following 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 is placed in
a magnetic tape drive. IO$_PACKACK is issued automatically when the DCL
commands INITIALIZE or MOUNT are issued.

3.4.15 Available
The available function clears the volume valid bit for all magnetic tape drives,
that is, it reverses the function performed by the pack acknowledge function (see
Section 3.4.14). A rewind of the tape is performed (applicable to all tape drives).
No unload function is issued to the drive. The following function code is provided:
IO$_AVAILABLE
This function takes no function-dependent arguments.

3.4.16 Flush
The flush function is used to ensure that all previously issued cached commands
have fully completed. Normally, hosts use this function to establish or maintain
synchronization with write-back cached commands issued to the specified
tape unit. The I/O request does not complete until all cached data is written
successfully to the media in the exact order that the user specified.
IO$_FLUSH
This function code takes no function-dependent arguments.

3.5 I/O Status Block

The I/O status block (IOSB) for QIO functions on magnetic tape devices is
shown in Figure 36. Appendix A lists the status returns for these functions.
(The OpenVMS system messages documentation provides explanations and
suggested user actions for these returns.) Table 32 (in Section 3.3) lists the
device-dependent data returned in the second longword. The IO$_SENSEMODE
function can be used to return that data.
Figure 36 IOSB Contents
31

16 15
Byte Count

0
Status

DeviceDependent Data
ZK0675GE

Magnetic Tape Drivers 325

Magnetic Tape Drivers

3.5 I/O Status Block
The byte count is the actual number of bytes transferred to or from the process
buffer or the number of files or blocks skipped. (If an IO$_SKIPRECORD function
is terminated by the detection of a tape mark, the count returned in the IOSB is
an unsigned number reflecting the number of blocks skipped, plus 1.

3.6 Magnetic Tape Driver Programming Examples

This section presents magnetic tape driver VAX MACRO programming examples.
Example 32 shows the recommended sequence for changing a
device characteristic. It retrieves the current characteristics using an
IO$_SENSEMODE request, sets the new characteristics bits, and then uses
IO$_SETMODE to set the new characteristics.
Example 33 shows ways of specifying sense mode and set mode, both with and
without a user buffer specified, and with user buffers of different lengths.
In addition, Example 34 shows how data is written to and read from magnetic
tape through the magnetic tape ACP.
Example 32 Device Characteristic Program Example
$QIOW_S FUNC
= #IO$_SENSEMODE,CHAN
= CHANNEL,IOSB
= IO_STATUS,P1
= BUFFER,P2
= #12
.
.
.
(Check for errors)
.
.
.
(Set desired characteristics bits)
.
.
.

;
;
;
;
;
;

Get current characteristics.

- Sensemode
- Channel
- IOSB
- User buffer supplied
- Buffer length = 12

$QIOW_S FUNC
=
CHAN
=
IOSB
=
P1
=
P2
=
.
.
.
(Check for errors)
.
.
.

;
;
;
;
;
;

Set new characteristics.

- Set Mode
- Channel
- IOSB
- User buffer address
- Buffer length = 12

326 Magnetic Tape Drivers

#IO$_SETMODE,CHANNEL,IO_STATUS,BUFFER,#12

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 33 Set Mode and Sense Mode Program Example
.PSECT

IMPURE, NOEXE, NOSHR

$IODEF
DEVICE_NAME:
.ASCID

; Name of device
;

/MUA0/

CHANNEL:
.WORD

; Channel to device
;

BUFFER: .BLKL

; Set/Sense characteristics
; buffer

IO_STATUS:
.QUAD

; Final I/O status

;

.PSECT

CODE, RD, NOWRT, EXE

.ENTRY

MAIN,^M<>

$ASSIGN_S DEVNAM
CHAN
BSBW

ERR_CHECK2

$QIOW_S FUNC
CHAN
IOSB
BSBW

BSBW

=
=
=
=

; Get current characteristics

#IO$_SENSEMODE,-; User buffer supplied, length
CHANNEL,; defaulted
IO_STATUS,;
BUFFER
;
; Check for errors

=
=
=
=
=

; Get current characteristics

#IO$_SENSEMODE,-; User buffer supplied, length
CHANNEL,; = 8
IO_STATUS,;
BUFFER,;
#8
;
; Check for errors

; Get extended characteristics

= #IO$_SENSEMODE,-; User buffer supplied, length
= CHANNEL,; = 12
= IO_STATUS,;
= BUFFER,;
= #12
;

ERR_CHECK

$QIOW_S FUNC
CHAN
IOSB
P1
BSBW

; Check for errors

ERR_CHECK

$QIOW_S FUNC
CHAN
IOSB
P1
P2
BSBW

; Get current characteristics

= #IO$_SENSEMODE,-; No user buffer supplied
= CHANNEL,;
= IO_STATUS
;

ERR_CHECK

$QIOW_S FUNC
CHAN
IOSB
P1
P2

ERR_CHECK

; Assign a channel to device

;
;
; Check for errors

ERR_CHECK

$QIOW_S FUNC
CHAN
IOSB
P1
BSBW

= DEVICE_NAME,= CHANNEL

; Check for errors

=
=
=
=

#IO$_SETMODE,CHANNEL,IO_STATUS,BUFFER

; Set new characteristics

; Length defaulted
;
;
;
; Check for errors
(continued on next page)

Magnetic Tape Drivers 327

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 33 (Cont.) Set Mode and Sense Mode Program Example
$QIOW_S FUNC
CHAN
IOSB
P1
P2
BSBW

=
=
=
=
=

ERR_CHECK

$QIOW_S FUNC
CHAN
IOSB
P1
P2
BSBW

#IO$_SETMODE,CHANNEL,IO_STATUS,BUFFER,#8

; Set new characteristics

; Length = 8
;
;
;
;
; Check for errors

= #IO$_SETMODE,= CHANNEL,= IO_STATUS,= BUFFER,= #12

ERR_CHECK

; Set extended characteristics

; Length = 12
;
;
;
;
; Check for errors

RET
.ENABLE LSB
ERR_CHECK:
BLBS
IO_STATUS,ERR_CHECK2
MOVZWL IO_STATUS,-(SP)
BRB
10$

; Continue if good IOSB

; Otherwise, set up for stop
; Branch to common code

ERR_CHECK2:
BLBS
PUSHL
10$:
CALLS

; Continue if good status

; Otherwise, set up for stop
; Stop execution

20$:

R0,20$
R0
#1,G^LIB$STOP

RSB
.DISABLE LSB
.END

MAIN

Example 34 MAGNETIC_TAPE.MAR Device Characteristic Program Example

; *********************************************************************
;
.TITLE MAGTAPE PROGRAMMING EXAMPLE
.IDENT /01/
;
; Define necessary symbols.
;
$FIBDEF

;Define file information block

;symbols
;Define I/O function codes

$IODEF
;
; Allocate storage for the necessary data structures.
;

;
; Allocate magtape device name string and descriptor.
;

(continued on next page)

328 Magnetic Tape Drivers

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 34 (Cont.) MAGNETIC_TAPE.MAR Device Characteristic Program Example
TAPENAME:
.LONG 20$-10$
.LONG 10$
10$:
.ASCII /TAPE/
20$:

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

;
; Allocate space to store assigned channel number.
;
TAPECHAN:
;
.BLKW 1
;Tape channel number
;
; Allocate space for the I/O status quadword.
;
IOSTATUS:
;
.BLKQ 1
;I/O status quadword
;
; Allocate storage for the input/output buffer.
;
BUFFER:
.REPT 256
.ASCII /A/
.ENDR
;
;
;
;
;
;

;
;Initialize buffer to
;contain A
;

Now define the file information block (FIB), which the ACP uses
in accessing and deaccessing the file. Both the user and the ACP
supply the information required in the FIB to perform these
functions.

FIB_DESCR:
.LONG
.LONG
FIB:
.LONG
.WORD
.WORD
.LONG
.WORD
.WORD
ENDFIB:

;Start of FIB
ENDFIB-FIB
;Length of FIB
FIB
;Address of FIB
FIB$M_WRITE!FIB$M_NOWRITE ;Read/write access allowed
0,0,0
;File ID
0,0,0
;Directory ID
0
;Context
0
;Name flags
0
;Extend control
;Reference label

;
; Now define the file name string and descriptor.
;
NAME_DESCR:
;
.LONG END_NAME-NAME
;File name descriptor
.LONG NAME
;Address of name string
NAME: .ASCII "MYDATA.DAT;1"
;File name string
END_NAME:
;Reference label
;
; *********************************************************************
;
;
Start Program
;
; *********************************************************************
;
(continued on next page)

Magnetic Tape Drivers 329

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 34 (Cont.) MAGNETIC_TAPE.MAR Device Characteristic Program Example
;
;
;
;
;
;
;
;
;
;
;
;
;
;
;
;
;

The program first assigns a channel to the magnetic tape unit and
then performs an access function to create and access a file called
MYDATA.DAT. Next, the program writes 26 blocks of data (the letters
of the alphabet) to the tape. The first block contains all As, the
next, all Bs, and so forth. The program starts by writing a block of
256 bytes, that is, the block of As. Each subsequent block is reduced
in size by two bytes so that by the time the block of Zs is written,
the size is only 206 bytes. The magtape ACP does not allow the reading
of a file that has been written until one of three events occurs:
1. The file is deaccessed.
2. The file is rewound.
3. The file is backspaced.
In this example the file is backspaced zero blocks and then read in
reverse (incrementing the block size every block); the data is
checked against the data that is supposed to be there. If no data
errors are detected, the file is deaccessed and the program exits.
.ENTRY MAGTAPE_EXAMPLE,^M<R3,R4,R5,R6,R7,R8>

;
; First, assign a channel to the tape unit.
;
$ASSIGN_S TAPENAME,TAPECHAN
CMPW
#SS$_NORMAL,R0
BSBW
ERRCHECK

;Assign tape unit

;Success?
;Find out

;
; Now create and access the file MYDATA.DAT.
;
$QIOW_S CHAN=TAPECHAN,;Channel is magtape
FUNC=#IO$_CREATE!IO$M_ACCESS!IO$M_CREATE,-;Function
;is create
IOSB=IOSTATUS,;Address of I/O status
;word
P1=FIB_DESCR,;FIB descriptor
P2=#NAME_DESCR
;Name descriptor
CMPW
#SS$_NORMAL,R0
;Success?
BSBW
ERRCHECK
;Find out
;
; LOOP1 consists of writing the alphabet to the tape (see previous
; description).
;
MOVL
MOVL

#26,R5
#256,R3

LOOP1:
$QIOW_S CHAN=TAPECHAN,FUNC=#IO$_WRITEVBLK,P1=BUFFER,P2=R3
CMPW
#SS$_NORMAL,R0
BSBW
ERRCHECK

;Set up loop count

;Set up initial byte count
;in R3
;Start of loop
;Perform QIOW to tape channel
;Function is write virtual
;block
;Buffer address
;Byte count
;Success?
;Find out

;
; Now decrement the byte count in preparation for the next write
; operation and set up a loop count for updating the character
; written; LOOP2 performs the update.
(continued on next page)

330 Magnetic Tape Drivers

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 34 (Cont.) MAGNETIC_TAPE.MAR Device Characteristic Program Example
SUBL2

#2,R3

MOVL

R3,R8

MOVAL
LOOP2: INCB
SOBGTR
SOBGTR

BUFFER,R7
(R7)+
R8,LOOP2
R5,LOOP1

;Decrement byte count for

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

;
; The alphabet is now complete. Fall through LOOP1 and update the
; byte count so that it reflects the actual size of the last block
; written to tape.
;
ADDL2
;
;
;
;
;
;
;

#2,R3

;Update byte count

The tape is now read, but first the program must perform one of
the three functions described previously before the ACP allows
read access. The program performs an ACP control function,
specifying skip zero blocks. This is a special case of skip reverse
and causes the ACP to allow read access.
CLRL
MOVW

FIB+FIB$L_CNTRLVAL
;Set up to space zero blocks
#FIB$C_SPACE,FIB+FIB$W_CNTRLFUNC ;Set up for space
;function
$QIOW_S CHAN=TAPECHAN,;Perform QIOW to tape channel
FUNC=#IO$_ACPCONTROL,- ;Perform an ACP control
;function
P1=FIB_DESCR
;Define the FIB
CMPW
#SS$_NORMAL,R0
;Success?
BSBW
ERRCHECK
;Find out
;
; Read the file in reverse.
;
MOVL
MOVB

#26,R5
#^A/Z/,R6

;Set up loop count

;Get first character in R6
LOOP3:
;
MOVAL BUFFER,R7
;And buffer address to R7
$QIOW_S CHAN=TAPECHAN,;Channel is magtape
FUNC=#IO$_READVBLK!IO$M_REVERSE,- ;Function is read
;reverse
IOSB=IOSTATUS,;Define I/O status quadword
P1=BUFFER,;And buffer address
P2=R3
;R3 bytes
CMPW
#SS$_NORMAL,R0
;Success?
BSBW
ERRCHECK
;Find out

(continued on next page)

Magnetic Tape Drivers 331

Magnetic Tape Drivers

3.6 Magnetic Tape Driver Programming Examples
Example 34 (Cont.) MAGNETIC_TAPE.MAR Device Characteristic Program Example
;
; Check the data read to verify that it matches the data written.
;
MOVL
CHECKDATA:
CMPB
BNEQ
SOBGTR
DECB
ADDL2

R3,R4
(R7)+,R6
MISMATCH
R4,CHECKDATA
R6
#2,R3

SOBGTR R5,LOOP3
;
; Now deaccess the file.
;
$QIOW_S CHAN=TAPECHAN,FUNC=#IO$_DEACCESS,P1=FIB_DESCR,IOSB=IOSTATUS

;Copy R3 to R4 for loop count

;
;Check each character
;If error, print message
;Continue until finished
;Go through alphabet in reverse
;Update byte count by 2 for
;next block
;Read next block

;Channel is magtape
;Deaccess function
;File information block (required)
;I/O status

;
; Deassign the channel and exit.
;
EXIT:

$DASSGN_S CHAN=TAPECHAN
RET

;Deassign channel
;Exit

;
; If an error had been detected, a program would normally
; generate an error message here. But for this example the
; program simply exits.
;
MISMATCH:
BRB

EXIT

;
;Exit

ERRCHECK:
BNEQ
RSB

EXIT

;
;If not success, exit
;Otherwise, return

.END

MAGTAPE_EXAMPLE

332 Magnetic Tape Drivers

4
Mailbox Driver
The operating system supports a virtual device, called a mailbox, that is used for
communication between processes. Mailboxes provide a controlled, synchronized
method for processes to exchange data. Although mailboxes transfer information
much like other I/O devices, they are not hardware devices. Rather, mailboxes
are a software-implemented way to perform read and write operations between
processes.
The OpenVMS Programming Concepts Manual and the OpenVMS System
Services Reference Manual contain additional information about using
mailboxes.

4.1 Mailbox Operations

This section describes the following mailbox operations:

Creating mailboxes

Deleting mailboxes

Protecting mailboxes

4.1.1 Creating Mailboxes

To create a mailbox and assign a channel and logical name to it, a process uses
the Create Mailbox and Assign Channel ($CREMBX) system service. A logical
name can optionally be associated with the mailbox. If a logical name is specified
for the mailbox, the system enters the logical name in a 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, a permanence indicator, maximum
message size, buffer quota, and direction in which I/O can be performed (read,
write, or read/write). A mailbox is created as either temporary or permanent;
both types require privilege to create. Applications and restrictions on how
to use temporary and permanent mailboxes are described in the following
sections. (Refer to the OpenVMS System Services Reference Manual for additional
information on creating mailboxes.)
Other processes can assign additional channels to a mailbox using either the
$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. Channels assigned to the mailbox can specify
the direction that I/O can be performed on the channel.
Figure 41 shows the use of $CREMBX and $ASSIGN.

Mailbox Driver 41

Mailbox Driver
4.1 Mailbox Operations
Figure 41 Multiple Mailbox Channels

User or
system
process
creates
mailbox.

Process

$CREMBX
assigns
channel.

Cooperating
processes use
$ASSIGN or $CREMBX
to define additional
channels.

Mailbox

Process

Process

ZK0676GE

If sufficient dynamic memory for the mailbox data structure is not available when
a mailbox is created, a resource wait occurs if resource wait mode is enabled.
When a mailbox is created, a certain amount of space is specified for buffering
messages that have been written to the mailbox but have not yet been read.
The bufquo argument to the $CREMBX system service specifies this amount or
quota. If that argument is omitted, its value defaults to the system parameter
DEFMBXBUFQUO.
A message written to a mailbox, in the absence of an outstanding read request,
is queued to the mailbox, and the size of the message (the QIO P2 argument) is
subtracted from the available buffering space. After the message is read, it is
added back to the available buffering space.
If a process attempts to write to a mailbox that is full or has insufficient buffering
space and if the process has resource wait enabled (which is the default case),
the process is placed in miscellaneous resource wait mode until sufficient space is
available in the mailbox. If resource wait is not enabled, the I/O completes with
the status return SS$_MBFULL in the I/O status block (IOSB).

42 Mailbox Driver

Mailbox Driver
4.1 Mailbox Operations
Channels can be assigned to mailboxes as bidirectional (read/write), read only, or
write only. This allows for greater synchronization between users of the mailbox.
To specify a unidirectional channel to the mailbox, specify the flags argument for
the $CREMBX or $ASSIGN system services.
The flags argument is a longword bit mask that enables you to specify that the
channel assigned to the mailbox is a read-only or write-only channel. If the flags
argument is not specified, the default channel behavior is read/write. A channel
assigned to the mailbox as read only is considered a reader. A channel assigned
to the mailbox as write only is considered a writer. A channel assigned to the
mailbox as read/write is considered both a reader and a writer.
For the $ASSIGN system service, the $AGNDEF macro defines a symbolic name
for each flag bit. These flags are as follows:

AGN$M_READONLYWhen this flag is specified, $ASSIGN assigns a readonly channel to the mailbox device. An attempt to issue a $QIO WRITE
operation on the mailbox channel causes an illegal I/O operation error.

AGN$M_WRITEONLYWhen this flag is specified, $ASSIGN assigns a

write only channel to the mailbox device. An attempt to issue a $QIO READ
operation on the mailbox channel causes an illegal I/O operation error.

For the $CREMBX system service, the $CMBDEF macro defines a symbolic name
for each flag bit. These flags are as follows:

CMB$M_READONLYWhen this flag is specified, $CREMBX assigns a

read-only channel to the mailbox device. An attempt to issue a $QIO WRITE
operation on the mailbox channel causes an illegal I/O operation error.

CMB$M_WRITEONLYWhen this flag is specified, $CREMBX assigns a

write-only channel to the mailbox device. An attempt to issue a $QIO READ
operation on the mailbox channel causes an illegal I/O operation error.

Refer to the OpenVMS System Services Reference Manual for a syntax description
of the $CREMBX and $ASSIGN system services.
The programming examples at the end of this section (Section 4.5) show mailbox
creation, interprocess communication, and synchronization.

4.1.2 Deleting Mailboxes

As each process finishes using a mailbox, it deassigns the channel using the
Deassign I/O Channel ($DASSGN) system service. Temporary mailboxes or
permanent mailboxes that have been marked for deletion are actually deleted
when no more channels are assigned to them.
If a mailbox channel is deassigned, any incomplete I/O requests on the mailbox
channel for the process deassigning the channel are removed.
Permanent mailboxes that have not been marked for deletion must be explicitly
deleted using the Delete Mailbox ($DELMBX) system service. An explicit deletion
can occur at any time. As is true for temporary mailboxes, the mailbox is deleted
when no processes have channels assigned to it.
When a temporary mailbox is deleted, its message buffer quota is returned to the
process that created it. (No quota charge is made for permanent mailboxes.)

Mailbox Driver 43

Mailbox Driver
4.1 Mailbox Operations
4.1.3 Mailbox Message Format
There is no standardized format for mailbox messages and none is imposed on
users.

4.1.4 Mailbox Protection

Mailboxes (both temporary and permanent) are protected by a code, or mask,
that is similar to the code used in protecting volumes. As with volumes, four
types of users (defined by UIC) can gain access to a mailbox: SYSTEM, OWNER,
GROUP, and WORLD; however, only three types of accesslogical I/O, read, and
writeare meaningful to users of a mailbox. Therefore, when creating a mailbox,
you can specify logical I/O, read, and write access to the mailbox separately for
each type of user. Logical I/O access is required for any mailbox operation. The
set protection function modifier provides additional control of mailbox access (see
Section 4.3.6).
For additional information on temporary mailboxes and mailbox protection, see
the description of the $CREMBX system service in the OpenVMS System Services
Reference Manual.

4.2 Mailbox Driver Device Information

You can obtain information on mailbox characteristics by using the Get
Device/Volume Information ($GETDVI) system service. (Refer to the OpenVMS
System Services Reference Manual.)
$GETDVI returns mailbox characteristics when you specify the item code
DVI$_DEVCHAR. Table 41 lists these characteristics, which are defined by the
$DEVDEF macro.
Table 41 Mailbox Characteristics
Characteristic1

Meaning
Dynamic Bits (Conditionally Set)

DEV$M_SHR

Device is shareable.

DEV$M_AVL

Device is available.
Static Bits (Always Set)

DEV$M_REC

Device is record-oriented.

DEV$M_IDV

Device is capable of input.

DEV$M_ODV

Device is capable of output.

DEV$M_MBX

Device is a mailbox.

1 Defined

by the $DEVDEF macro.

DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device

type names, which are defined by the $DCDEF macro. The device class for
mailboxes is DC$_MAILBOX. The device type is DT$_MBX (or DT$_SHRMBX if
the mailbox is a shared memory mailbox). DVI$_DEVBUFSIZ returns the buffer
size, which is the maximum message size in bytes.
DVI$_DEVDEPEND returns a longword field in which the two low-order bytes
contain the number of messages in the mailbox. (The two high-order bytes are
not used and should be ignored.)
44 Mailbox Driver

Mailbox Driver
4.2 Mailbox Driver Device Information
DVI$_UNIT returns the mailbox unit number. Using mailbox to hold a
termination message for a subprocess or a detached process requires that
the parent process obtain this number to pass to the mbxunt argument of the
$CREPRC system service.

4.3 Mailbox Function Codes

The mailbox I/O functions are read, write, write end-of-file, set attention AST,
wait for writer/reader, and get mailbox information.
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.

4.3.1 Read
Read mailbox functions are used to obtain messages written to the mailbox. The
operating system provides the following mailbox function codes:

IO$_READVBLKRead virtual block

IO$_READLBLKRead logical block

IO$_READPBLKRead physical block

IO$_READLBLK, IO$_READVBLK, and IO$_READPBLK all perform the same

operation. To issue a read request, a process can specify any of the read function
codes.
The following device- or function-dependent arguments are used with these codes:

P1The starting virtual address of the buffer that is to receive the message.
If P2 specifies a zero-length buffer, P1 is ignored. On OpenVSM Alpha, P1
can be a 64-bit address.

P2The size of the buffer in bytes (limited by the maximum message size for
the mailbox). A zero-length buffer may be specified. If a message longer than
the buffer is read, the alternate success status SS$_BUFFEROVF is returned
in the I/O status block. In such cases, the message is truncated to fit the
buffer. The driver does not provide a means for recovering the deleted portion
of the message.

The following function modifiers can be specified with a read request:

IO$M_WRITERCHECKCompletes the I/O operation with SS$_NOWRITER

status if the mailbox is empty and no write channels are assigned to the
mailbox. If no writer is assigned to the mailbox when the $QIO is issued
and no data is in the mailbox, the $QIO completes immediately. If no data
is in the mailbox but a writer is assigned, the $QIO operation completes
when either a message is written or all writers deassign their channels to
the mailbox. IO$M_WRITERCHECK is ignored if the channel on which it is
issued is read/write because a writer is always assigned.

IO$M_NOWCompletes the I/O operation immediately with no wait for a

write request from another process.

IO$M_STREAMIgnores QIO record boundaries. The read operation

transfers message data to the users buffer until either P2 bytes are
transferred, all message data currently in the mailbox is transferred, or
an end-of-file message is encountered. If a WRITEOF message is within the
records required to be read in order to fulfill the request for P2 bytes, the
Mailbox Driver 45

Mailbox Driver
4.3 Mailbox Function Codes
read request terminates successfully with the bytes it was able to read before
finding the WRITEOF message and the end-of-file message becomes the
first message in the mailbox. The next read request processes the end-of-file
message. If the read request is a READ STREAM, then the request must be
for greater than 0 bytes. $QIO READ STREAM can return fewer than P2
bytes with a return value of SS$_NORMAL if the mailbox is emptied by the
$QIO READ STREAM request or a WRITEOF message is encountered.
Figure 42 shows $QIO READ STREAM operations.
A READ IO$M_STREAM (without IO$M_NOW specified) on an empty
mailbox waits until some data has been written to the mailbox. It terminates
with:
0 bytes read if the next data written is an end-of-file message.
Fewer than P2 bytes read if the next data written is less than P2 bytes
but greater than 0 bytes. (READ IO$M_STREAM ignores writes of 0
bytes.)
P2 bytes read if the next data written is greater than or equal to P2
bytes.
If a $QIO READ STREAM is fulfilled by multiple $QIO WRITE requests,
the sender PID returned in the IOSB of the $QIO READ STREAM reflects
the first write request. A $QIO READ STREAM is charged BUFQUO for the
request. This BUFQUO is released when the read request is met. A $QIO
READ STREAM request that would cause BUFQUO to be exceeded for the
mailbox when the mailbox has no writes pending returns an SS$_EXQUOTA
error.
A $QIO READ STREAM issued to a mailbox that would cause BUFQUO to be
exceeded because BUFQUO is occupied by write requests still executes. This
happens because by allowing the mailbox to temporarily exceed BUFQUO,
BUFQUO is freed. Similarly, a $QIO WRITE that is issued to a mailbox that
would cause BUFQUO to be exceeded, because the BUFQUO is occupied by
read stream requests, still executes.
Reads of 0 bytes are handled differently depending on which functional modifiers
are specified. If IO$M_STREAM is specified, then the $QIO returns SS$_
NORMAL with 0 bytes read. The contents of the mailbox remain exactly as
they were before the $QIO was issued. A $QIO READ STREAM of 0 bytes does
not remove a 0 byte record, nor does it remove an end-of-file marker. If IO$M_
STREAM is not specified, then $QIO returns one of the following:

SS$_NORMAL (if 0 bytes were written with the corresponding $QIO WRITE
performed)

SS$_BUFFEROVF (if the corresponding $QIO WRITE wrote more than 0

bytes with 0 bytes read)

SS$_ENDOFFILE (if a WRITEOF function was performed as the

corresponding $QIO write function)

For a 0-byte nonstream read, a record is actually removed from the mailbox to
meet the $QIO READ request. Note that the use of the word immediately does
not imply that synchronization of the $QIO request should not be performed.

46 Mailbox Driver

Mailbox Driver
4.3 Mailbox Function Codes
Figure 42 $QIO READ STREAM Operation
1. CREMBX

Empty Mailbox

2. WRITE 20 bytes

Mailbox contains 1 record, 20 bytes long

3. READ (Record) 10 bytes

Empty Mailbox

4. WRITE 20 bytes

Mailbox contains 1 record, 20 bytes long

5. READ STREAM 10 bytes

Mailbox contains 1 record, 10 bytes long

6. WRITE 50 bytes

Mailbox contains 2 records, 10 and 50 bytes long

7. READ STREAM 30 bytes

Mailbox contains 1 record, 30 bytes long

8. Read (Record) 40 bytes

Empty Mailbox

Diagram reflects state of Mailbox after specified operation has been performed.
ZK3853AGE

Mailbox Driver 47

Mailbox Driver
4.3 Mailbox Function Codes
Figure 43 shows 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; the read request can either
precede or follow the write request.
Figure 43 Read Mailbox
1

or

Read QIO

Process
A

or

Write QIO

Process
B

Mailbox

Data

Data

Note: Numbers indicate order of events.

ZK0679GE

If Process A issues a read request before Process B issues a write request, one of
two events can occur. If Process A did not specify the function modifier IO$M_
NOW, Process As request is queued before Process B issues the write request.
When Process Bs write 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, no data is transferred from Process
B to Process A, and Process As request is not queued until Process B issues
the write request. In this case, the I/O status returned to Process A is SS$_
ENDOFFILE.
If Process B sends a message (with no function modifier; see Section 4.3.2) before
Process A issues a read request (with or without a function modifier), Process A
finds a message in the mailbox. The data is transferred and the I/O operation
is completed immediately, regardless of whether IO$M_NOW is specified on the
read request.

48 Mailbox Driver

Mailbox Driver
4.3 Mailbox Function Codes
4.3.2 Write
Write mailbox functions are used to transfer data from a process to a mailbox.
The operating system provides the following mailbox function codes:

IO$_WRITEVBLKWrite virtual block

IO$_WRITELBLKWrite logical block

IO$_WRITEPBLKWrite physical block

IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK all perform the

same operation. To issue a write request, a process can specify any of the write
function codes.
These function codes take the following device- or function-dependent arguments:

P1The starting virtual address of the buffer that contains the message
being written. If P2 specifies a zero-length buffer, P1 is ignored. On
OpenVMS Alpha, P1 can be a 64-bit address.

P2The size of the buffer in bytes (limited by the maximum message size for
the mailbox). A zero-length buffer produces a zero-length message to be read
by the mailbox reader.

The following function modifiers can be specified with a write request:

IO$M_READERCHECKCompletes the I/O operation immediately, with

SS$_NOREADER status, if no read channels are assigned to the mailbox. If
a $QIO WRITE with IO$M_READERCHECK is issued and is outstanding
and all read channels assigned to the mailbox are then deassigned, the $QIO
completes with SS$_NOREADER status. IO$M_READERCHECK is ignored
if the channel on which it is issued is bidirectional read/write, because there
is always a reader assigned. If SS$_NOREADER is returned for a write
request, the $QIO WRITE operation does not place any data in the mailbox.
If SS$_NOREADER is returned for a write end-of-file message request, the
$QIO WRITE operation does not place the end-of-file marker in the mailbox.

IO$M_NOWCompletes the I/O operation immediately without waiting for

another process to read the mailbox message. $QIO WRITE, without IO$M_
NOW specified, does not complete until the data is read. $QIO WRITE NOW
completes when the data is in the mailbox. If both IO$M_READERCHECK
and IO$M_NOW are specified and no read channel is assigned to the mailbox,
a status of SS$_NOREADER is returned and the data is not placed in the
mailbox. If a read channel is assigned, the IO$M_READERCHECK modifier
is ignored.

IO$M_NORSWAITIf the mailbox is full, the I/O operation fails with a

status return of SS$_MBFULL rather than placing the process in resource
wait mode. Note that IO$M_NORSWAIT does not disable resource waits that
may occur elsewhere in the $QIO operation. For example, IO$M_NORSWAIT
does not affect any resource waiting that occurs when I/O processing routines
try to allocate an I/O request packet while passing the I/O request to the
mailbox driver.

A $QIO WRITE of 0 bytes causes a 0-byte long message to be placed in the

mailbox. When this data is read by a $QIO READ without IO$M_STREAM
specified, the $QIO READ returns an SS$_NORMAL status and 0 bytes. When
this data is read by a $QIO READ STREAM in an attempt to read P2 bytes (P2
being greater than 0), the data is ignored. However, a $QIO READ STREAM of 0
bytes has no effect on the mailbox. A $QIO WRITE READERCHECK of 0 bytes,

Mailbox Driver 49

Mailbox Driver
4.3 Mailbox Function Codes
when no read channel is assigned to the mailbox, returns an SS$_NOREADER
error and the 0-byte record is not placed in the mailbox. A message that is 0
bytes long is charged 1 byte of mailbox BUFQUO.
Figure 44 shows the write mailbox function. In this figure, Process A writes a
message to be read by Process B. As in the read request example, a mailbox write
request requires a corresponding mailbox read request (unless an error occurs)
and the requests can be made in any sequence.
If Process A issues a write request before Process B issues a read request, one of
two events can occur. If Process A did not specify the function modifier IO$M_
NOW, Process As write request is queued before Process B issues a read request.
When this request occurs, the data is transferred from Process A to Process B to
complete the I/O operation.
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 request in the mailbox. The data is transferred and the I/O operation is
completed immediately.
Figure 44 Write Mailbox
1

or

Write QIO

Process
A

or

Read QIO

Process
B

Mailbox

Data

Data

Note: Numbers indicate order of events.

ZK0680GE

410 Mailbox Driver

Mailbox Driver
4.3 Mailbox Function Codes
4.3.3 Write End-of-File Message
Write end-of-file message functions 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. The message count of the Get
Mailbox Information function reflects this end-of-file message; however, the
mailbox byte count of this function does not include end-of-file markers. An
end-of-file message is charged 1 byte of mailbox BUFQUO.
This function takes no arguments. The operating system provides the following
function code:
IO$_WRITEOFWrite end-of-file message
The following function modifiers can be specified with a write end-of-file request:

IO$M_READERCHECKCompletes the I/O operation immediately, with

SS$_NOREADER status, if no read channels are assigned to the mailbox. If
a $QIO WRITEOF with IO$M_READERCHECK is issued and is outstanding
and all read channels assigned to the mailbox are then deassigned, the $QIO
completes with SS$_NOREADER status. IO$M_READERCHECK is ignored
if the channel on which it is issued is bidirectional read/write, because there
is always a reader assigned. If SS$_NOREADER is returned for a write
end-of-file message request, the $QIO WRITEOF operation does not place the
end-of-file marker in the mailbox.

IO$M_NOWCompletes the I/O operation immediately without waiting for

another process to read the mailbox message. If both IO$M_READERCHECK
and IO$M_NOW are specified, and no read channel is assigned to the
mailbox, a status of SS$_NOREADER is returned and the end-of-file message
is not placed in the mailbox.

IO$M_NORSWAITIf the mailbox is full, the I/O operation fails with a status
return of SS$_MBFULL instead of placing the process in resource wait mode.
Note that IO$M_NORSWAIT does not disable resource waits that may occur
elsewhere in the $QIO operation. For example, IO$M_NORSWAIT does not
affect any resource waiting that occurs when I/O processing routines try to
allocate an I/O request packet while passing the I/O request to the mailbox
driver.

4.3.4 Set Attention AST

Set attention AST functions specify that an asynchronous system trap (AST) be
delivered to the requesting process in the following cases:

When a cooperating process places a read request for which no write request
is pending in a designated mailbox. This is called an unsolicited read request.

When a cooperating process places a write request for which no read request
is pending in a designated mailbox. This is called an unsolicited write
request.

When room becomes available in the mailbox.

If a message exists in the mailbox when a request to enable a write attention

AST is issued, the AST routine is activated immediately. If no message exists, the
AST is delivered when a write request message arrives; therefore, the requesting
process need not repeatedly check the mailbox status. You must have both logical
I/O and read access to the mailbox prior to performing a set attention AST
function.

Mailbox Driver 411

Mailbox Driver
4.3 Mailbox Function Codes
The operating system provides the following function codes:

IO$_SETMODE!IO$M_READATTNRead attention AST

IO$_SETMODE!IO$M_WRTATTNWrite attention AST

IO$_SETMODE!IO$M_MB_ROOM_NOTIFYRoom in the mailbox attention

AST

These function codes take the following device- or function-dependent arguments:

P1AST address (request notification is disabled if the address is 0)

P2AST parameter returned in the argument list when the AST service
routine is called

P3Access mode to deliver AST; maximized with requesters mode

These functions are enabled only once; they must be explicitly reenabled after
the AST has been delivered if you desire repeat notification. All types of enable
functions, and more than one of each type, can be set at the same time. The
number of enable functions is limited only by the AST quota for the process.
Figure 45 shows the write attention AST function. In this figure, an AST is set
to notify Process A when Process B sends an unsolicited message.
Figure 45 Write Attention AST (Read Unsolicited Data)

AST

1
AST Specified by
IO$_SETMODE
!IO$M_WRTATTN

Read QIO
+IO$M_NOW

Unsolicited
Write QIO

Process
A

Process
B

Mailbox

Data

Data

Note: Numbers indicate order of events.

ZK0681GE

412 Mailbox Driver

Mailbox Driver
4.3 Mailbox Function Codes
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
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. Therefore, when the next process to respond to an AST
issues a read request to the mailbox, it might find the mailbox empty. If this
request does not include the function modifier IO$M_NOW, it is queued before
the next message arrives in the mailbox.
Figure 46 shows the read 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.
Figure 46 Read Attention AST

AST

1
AST Specified by
IO$_SETMODE
!IO$M_READATTN

Write QIO
+IO$M_NOW

Read QIO

Process
A

Process
B

Mailbox

Data

Data

Note: Numbers indicate order of events.

ZK0682GE

Process A uses the IO$_SETMODE!IO$M_READATTN function to specify an

AST. When Process B issues 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.

Mailbox Driver 413

Mailbox Driver
4.3 Mailbox Function Codes
If several requesting processes set ASTs for read requests for 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.

4.3.5 Wait for Writer/Reader

The wait for writer/reader mailbox driver function waits until a channel is
assigned to the mailbox with the requested access direction. This function
returns immediately if a channel is already assigned to the mailbox with the
proper access direction. This function always returns immediately if issued on
a bidirectional mailbox channel. Any channel assigned bidirectionally to the
mailbox satisfies both types of wait requests.
The wait function requires the same synchronization techniques as all other
$QIO functions. $QIO Wait should not be issued without any synchronization of
its completion. If no synchronization is performed, the program behaves as if no
$QIO Wait function had been issued (except for the small delay caused by issuing
the $QIO Wait).
The following function codes and modifiers are provided:

IO$_SETMODE!IO$M_READERWAITWaits for a read channel to be

assigned to the mailbox.

IO$_SETMODE!IO$M_WRITERWAITWaits for a write channel to be

assigned to the mailbox.

These function codes require no function-dependent arguments.

These functions are enabled only once. Once the $QIO operation completes, these
functions must be explicitly reenabled.

4.3.6 Set Protection

On VAX and Alpha systems, the set protection functions allow the user to set
volume protection on a mailbox (see Section 4.1.4). The requester must either be
the owner of the mailbox or have BYPASS privilege. The OpenVMS operating
system provides the following function code:
IO$_SETMODE!IO$M_SETPROTSet protection
This function code takes the following device- or function-dependent argument:
P2A volume protection mask
The protection mask specified by P2 is a 16-bit mask with 4 bits for each class of
owner: SYSTEM, OWNER, GROUP, and WORLD, as shown in Figure 47.
Only logical I/O, read, and write functions have meaning for mailboxes. A clear
(0) bit implies that access is allowed. If P2 is 0 or unspecified, the mask is set to
allow all read, write, and logical operations.
The I/O status block for the set protection function (see Figure 410) returns
SS$_NORMAL in the first word if the request was successful. If the request
was not successful, the $QIO system service returns SS$_NOPRIV and both
longwords of the I/O status block are returned as zeros.

414 Mailbox Driver

Mailbox Driver
4.3 Mailbox Function Codes
Figure 47 Protection Mask
15

11

World

Group

Owner

System

11

10

Log I/O

Write

Read

* Not Used
ZK0683GE

4.3.7 Get Mailbox Information

The get mailbox information function allows the user to find out the number
of unread messages and bytes in the mailbox. The following function code is
provided:
IO$_SENSEMODEGet mailbox contents information
The following function codes and modifiers are provided:

IO$_SENSEMODE!IO$M_READERCHECKIf a $QIO SENSEMODE with

IO$M_READERCHECK is issued and no read channels are assigned to the
mailbox, then the SS$_NOREADER condition value is returned in the IOSB.

IO$_SENSEMODE!IO$M_WRITERCHECKIf a $QIO SENSEMODE with

IO$M_WRITERCHECK is issued and no write channels are assigned to the
mailbox, then the SS$_NOWRITER condition value is returned in the IOSB.

These function codes require no function-dependent arguments.

4.4 I/O Status Block

On VAX and Alpha systems, the I/O status blocks (IOSB) for mailbox read, write,
set protection, and get mailbox information QIO functions are shown in Figures
48, 49, 410, and 411.
Appendix A lists the I/O status returns for these functions. In addition to the
IOSB return values, the following statuses can be returned in R0 by the call to
the system service:
SS$_ACCVIO
SS$_EXQUOTA
SS$_ILLIOFUNC
SS$_INSFMEM
SS$_MBFULL
SS$_MBTOOSML
SS$_NOPRIV
SS$_NORMAL

Mailbox Driver 415

Mailbox Driver
4.4 I/O Status Block
(The OpenVMS system messages documentation provides explanations and
suggested user actions for both types of returns.)
Figure 48 IOSB ContentsRead Function
+2

IOSB

Byte Count

Status

Sender Process Identification (PID) *

+4

* 0 if the sender was a system process.

ZK0684GE

Figure 49 IOSB ContentsWrite Function

+2

IOSB

Byte Count *

Status
+4

Receiver Process Identification (PID) * *

* Equals P2 buffer size if successful request.
* * 0 if IO$M_NOW was specified.
ZK0685GE

Figure 410 IOSB ContentsSet Protection Function

+2

IOSB

Status
+4

Protection Mask (P2) Value

ZK1201GE

Figure 411 IOSB ContentsGet Mailbox Information Function

31

16

Number of Messages in Mailbox

15

0
Condition Value

Number of Message Bytes in Mailbox

ZK3797A

416 Mailbox Driver

Mailbox Driver
4.5 Mailbox Driver Programming Examples

4.5 Mailbox Driver Programming Examples

This section contains the following programming examples:

Example 41 shows a MACRO32 program that creates a mailbox and puts

mail into it.

Example 42 assigns a read-only channel to the mailbox.

Example 43 assigns a write-only channel to the mailbox.

Example 41 creates a mailbox and puts mail into it; no matching read is pending
on the mailbox. First, the program shows that if the function modifier IO$M_
NOW is not used when mail is deposited, the write function waits until a read
operation is performed. 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 is no mail in the mailbox, the program waits
because IO$M_NOW is not specified. IO$M_NOW should be specified if there is
any doubt about the availability of data in the mailbox, and it is important for
the program not to wait.
It is up to the user to coordinate the data that 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.
Example 42 and Example 43 work together from two separate processes
and show the unidirectional mailbox synchronization features. Note that these
examples require the /STANDARD=VAXC qualifier when compiled on Alpha
systems.
Example 42 performs the following functions:
1. Assigns a read-only channel to the mailbox.
2. Waits for another program to assign a writable channel to the mailbox.
3. Reads, using the IO$M_WRITERCHECK function modifier, what has been
written to the mailbox.
4. When SS$_NOWRITER is returned from the read operation, goes back to
Step 2 and waits for another writer.
Example 43 is a writer to the mailbox. It performs the following functions:
1. Assigns a write-only channel to the mailbox.
2. Waits for a reader.
3. Gathers user input until the user enters Ctrl/Z, then writes that input to the
mailbox.

Mailbox Driver 417

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 41 Mailbox Driver Program Example 1
; *********************************************************************
;
.TITLE MAILBOX DRIVER PROGRAM EXAMPLE
.IDENT /01/
;
; Define necessary symbols.
;
$IODEF

;Define I/O function codes

;
; Allocate storage for necessary data structures.
;
;
; Allocate output device name string and descriptor.
;
DEVICE_DESCR:
.LONG 20$-10$
.LONG 10$
10$:
.ASCII /SYS$OUTPUT/
20$:

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

;
; Allocate space to store assigned channel number.
;
DEVICE_CHANNEL:
.BLKW 1

;
;Channel number

;
; Allocate mailbox name string and descriptor.
;
MAILBOX_NAME:
.LONG ENDBOX-NAMEBOX
.LONG NAMEBOX
NAMEBOX: .ASCII /146_MAIN_ST/
ENDBOX:

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

;
; Allocate space to store assigned channel number.
;
MAILBOX_CHANNEL:
.BLKW 1

;
;Channel number

;
; Allocate space to store the outgoing and incoming messages.
;
IN_BOX_BUFFER:
.BLKB 40
IN_LENGTH=.-IN_BOX_BUFFER
OUT_BOX_BUFFER:
.ASCII /SHEEP ARE VERY DIM/
OUT_LENGTH=.-OUT_BOX_BUFFER

;
;Allocate 40 bytes for
;received message
;Define input buffer length
;
;Message to send
;Define length of message to
;send

;
; Finally, allocate space for the I/O status quadword.
;
(continued on next page)

418 Mailbox Driver

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 41 (Cont.) Mailbox Driver Program Example 1
STATUS:
.QUAD

;
;I/O status quadword

;
; *********************************************************************
;
;
Start Program
;
; *********************************************************************
;
;
;
;
;
;
;
;

The program first creates a mailbox and assigns a channel to the

process output device. Then a message is placed in the mailbox and
a message is received from the mailbox (the same message). Finally,
the program prints the contents of the mailbox on the process output
device.

START: .WORD 0
;Entry mask
$CREMBX_S CHAN=MAILBOX_CHANNEL,- ;Channel is the mailbox
PROMSK=#^X0000,;No protection
BUFQUO=#^X0060,;Buffer quota is hex 60
LOGNAM=MAILBOX_NAME,- ;Logical name descriptor
MAXMSG=#^X0060
;Maximum message is hex 60
CMPW
#SS$_NORMAL,R0
;Successful mailbox creation?
BSBW
ERROR_CHECK
;Find out
$ASSIGN_S ;Assign channel
DEVNAM=DEVICE_DESCR,- ;Device descriptor
CHAN=DEVICE_CHANNEL
;Channel
CMPW
#SS$_NORMAL,R0
;Successful channel assign?
BSBW
ERROR_CHECK
;Find out
;
;
;
;
;
;

The program now writes to the mailbox using a write request that
includes the function modifier IO$M_NOW so that it need not wait for
a read request to the mailbox before continuing to the next step in
the program.
$QIOW_S FUNC=#IO$_WRITEVBLK!IO$M_NOW,- ;Write message NOW
CHAN=MAILBOX_CHANNEL,- ;to the mailbox channel
P1=OUT_BOX_BUFFER,;Write buffer
P2=#OUT_LENGTH
;Buffer length
CMPW
#SS$_NORMAL,R0
;Successful write request?
BSBW
ERROR_CHECK
;Find out

;
; Read the mailbox.
;
$QIOW_S FUNC=#IO$_READVBLK,CHAN=MAILBOX_CHANNEL,IOSB=STATUS,P1=IN_BOX_BUFFER,P2=#IN_LENGTH
CMPW
#SS$_NORMAL,R0
BSBW
ERROR_CHECK

;Read the message

;in the mailbox channel
;Define status block to
;receive message length
;Read buffer
;Buffer length
;Successful read request?
;Find out
(continued on next page)

Mailbox Driver 419

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 41 (Cont.) Mailbox Driver Program Example 1
;
; The program now determines how much mail is in the mailbox (this
; information is in STATUS+2) and then prints the mailbox message on
; the process output device.
;
MOVZWL STATUS+2,R2
$QIOW_S FUNC=#IO$_WRITEVBLK,CHAN=DEVICE_CHANNEL,P1=IN_BOX_BUFFER,P2=R2,P4=#32

;Byte count into R2

;Write function to the
;output device channel
;Address of buffer to write
;How much to write
;Carriage control

;
; Finally, deassign the channel and exit.
;
EXIT:

$DASSGN_S CHAN=DEVICE_CHANNEL
RET

;Deassign channel
;Return

;
; This is the error checking part of the program. Normally, some kind
; of error recovery would be attempted at this point if an error was
; detected. However, this example program simply exits.
;
ERROR_CHECK:
BNEQ
RSB
.END

;
;System service failure, exit
;Otherwise, return

EXIT
START

Example 42 assigns a read-only channel to the mailbox.

Example 42 Mailbox Driver Program Example 2
/*
* C program to demonstrate the new features of the Mailbox driver
* This program is a Mailbox READER. It assigns a READ_ONLY channel to the
* mailbox. Its partner program is a Mailbox WRITER.
*/
#include
#include
#include
#include
#include
#include
#include

"sys$library:descrip"
"sys$library:libdef"
"sys$library:stdio"
"decc$library:[include]ssdef"
"decc$library:[include]cmbdef"
"decc$library:[include]agndef"
"decc$library:[include]iodef"

/*
/*
/*
/*
/*
/*
/*

Descriptor structure definitions */

LIB RTL symbol definitions
*/
Standard C symbol definitions
*/
System Service status code defns */
CREMBX definitions
*/
ASSIGN definitions
*/
I/O definitions
*/

#define $ARRAY_DESCRIPTOR(name,size,array_name)
char array_name[ size ];
struct dsc$descriptor_s name =
{ size, DSC$K_DTYPE_T, DSC$K_CLASS_S, array_name }

\
\
\

main()
(continued on next page)

420 Mailbox Driver

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 42 (Cont.) Mailbox Driver Program Example 2
{
# define max_msg_len 256
$DESCRIPTOR(mailbox_name_desc,"MAILBOX_EXAMPLE");
$ARRAY_DESCRIPTOR(read_buffer_desc,max_msg_len,read_buffer);
int status, mailbox_channel;
int true=1, false = 0;
struct io_status_block {
/* I/O status block */
short int condition;
short int count;
int dev;
} iosb;
/*
* Create a permanent mailbox with a READONLY channel. Its logical name
* will be entered into the LNM$PERMANENT_MAILBOX logical name table.
*/
SYS$CREMBX(1,&mailbox_channel,0,0,0,0,&mailbox_name_desc,CMB$M_READONLY);
/*
* Mark it for deletion
*/
SYS$DELMBX(mailbox_channel);
/*
* Loop forever, first waiting til a WRITE channel is assigned to the mailbox
* and then reading data from it until the WRITER deassigns.
*/
while (TRUE)
{
/* First, check to see if there is a WRITER assigned to the mailbox */
status = SYS$QIOW (
0,
mailbox_channel,
IO$_SENSEMODE|IO$M_WRITERCHECK,
&iosb,
0,0,
0,0,0,0,0,0);
/* If there was no WRITER, then wait for one.*/
if (iosb.condition == SS$_NOWRITER)
status = SYS$QIOW (
0,
mailbox_channel,
IO$_SETMODE|IO$M_WRITERWAIT,
&iosb,
0,0,
0,0,0,0,0,0);
(continued on next page)

Mailbox Driver 421

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 42 (Cont.) Mailbox Driver Program Example 2
/*
* While the status is good, READ from the mailbox, and write it to
*/
while (status == SS$_NORMAL)
{
status = SYS$QIOW(
0,
mailbox_channel,
IO$_READVBLK|IO$M_WRITERCHECK,
&iosb,
0,0,
read_buffer_desc.dsc$a_pointer,max_msg_len,
0,0,0,0);
status=iosb.condition;
read_buffer_desc.dsc$w_length = iosb.count;
lib$put_output(&read_buffer_desc);
}
}
}
Example 43 assigns a write-only channel to the mailbox.
Example 43 Mailbox Driver Program Example 3
/*
* C program to demonstrate the new features of the Mailbox driver
* This program is a Mailbox WRITER. It assigns a WRITE_ONLY channel to the
* mailbox. Its partner program is a Mailbox READER.
*/
#include
#include
#include
#include
#include
#include
#include
#include

"sys$library:descrip"
"sys$library:libdef"
"sys$library:rmsdef"
"sys$library:stdio"
"decc$library:[include]ssdef"
"decc$library:[include]cmbdef"
"decc$library:[include]agndef"
"decc$library:[include]iodef"

/*
/*
/*
/*
/*
/*
/*
/*

Descriptor structure definitions */

LIB RTL symbol definitions
*/
RMS status code defns
*/
Standard C symbol definitions
*/
System Service status code defns */
CREMBX definitions
*/
ASSIGN definitions
*/
I/O definitions
*/

#define $ARRAY_DESCRIPTOR(name,size,array_name)
char array_name[ size ];
struct dsc$descriptor_s name =
{ size, DSC$K_DTYPE_T, DSC$K_CLASS_S, array_name }

\
\
\

(continued on next page)

422 Mailbox Driver

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 43 (Cont.) Mailbox Driver Program Example 3
main()
{
#define max_msg_len 256
$DESCRIPTOR(mailbox_name_desc,"MAILBOX_EXAMPLE");
$DESCRIPTOR(prompt_string_desc,"DATA TO SEND TO MAILBOX
(<CTRL Z> to terminate) >>>");
$ARRAY_DESCRIPTOR(write_buffer_desc,max_msg_len,write_buffer);
int status, mailbox_channel, wait_efn;
int true=1, false = 0;
int MORE_ROOM_AST();
struct io_status_block {
/* I/O status block */
short int condition;
short int count;
int dev;
} iosb;
/*
* Create a permanent mailbox with a WRITEONLY channel. Its logical name
* will be entered into the LNM$PERMANENT_MAILBOX logical name table.
*/
SYS$CREMBX(1,&mailbox_channel,0,0,0,0,&mailbox_name_desc,CMB$M_WRITEONLY);
/*
* Mark it for deletion
*/
SYS$DELMBX(mailbox_channel);
/*
* Loop forever, first waiting til a READ channel is assigned to the mailbox
* and then write data until there is no more data to write.
*/
while (TRUE)
{
/*
* Wait for a READER to assign a channel. If a READER is already
* assigned, this will return immediatly.
*/
status = SYS$QIOW (
0,
mailbox_channel,
IO$_SETMODE|IO$M_READERWAIT,
&iosb,
0,0,
0,0,0,0,0,0);
while (status)
{
write_buffer_desc.dsc$w_length = max_msg_len;
status = lib$get_input(
&write_buffer_desc,
&prompt_string_desc,
&write_buffer_desc.dsc$w_length);
/*
* If at end of file (user typed <CTRL Z>)
* then stop here.
*/
if (status == RMS$_EOF) SYS$EXIT(SS$_NORMAL);
(continued on next page)

Mailbox Driver 423

Mailbox Driver
4.5 Mailbox Driver Programming Examples
Example 43 (Cont.) Mailbox Driver Program Example 3
/* Keep trying to write the message, until it fits in the mailbox
* Note that if the NORSWAIT function modifier had been eliminated
* below, then the ROOM_NOTIFY and the retry loop could have been
* removed. ROOM_NOTIFY was used in this example simply to show
* its use. It would be more appropriately used when the program
* has other things it can be working on, as opposed to the
* example below in which the program is not doing anything except
* WAITING for room in the mailbox.
*/
status = SS$_NOREADER;
/* Force attempt to WRITE */
while (status != SS$_NORMAL)
{
status = SYS$QIOW(
0,
mailbox_channel,
IO$_WRITEVBLK|IO$M_READERCHECK|IO$M_NORSWAIT,
&iosb,
0,0,
write_buffer_desc.dsc$a_pointer, write_buffer_desc.dsc$w_length,
0,0,0,0);
if (iosb.condition == SS$_NOREADER) SYS$EXIT(SS$_NOREADER);
if (status == SS$_MBFULL)
{
LIB$GET_EF(&wait_efn);
SYS$CLREF(wait_efn);
SYS$QIOW (
0,
mailbox_channel,
IO$_SETMODE|IO$M_MB_ROOM_NOTIFY,
&iosb,
0,0,
MORE_ROOM_AST,wait_efn,0,0,0,0);
SYS$WAITFR(wait_efn);
}
}
}
}
}
MORE_ROOM_AST(efn_to_set)
int efn_to_set;
{
SYS$SETEF(efn_to_set);
}

424 Mailbox Driver

5
Terminal Driver
This chapter describes the use of the terminal driver (TTDRIVER) and the
LAT port driver (LTDRIVER). The terminal driver supports the asynchronous,
serial line multiplexers listed in Table 51. The terminal driver also supports
the console terminal. The LAT port driver accommodates I/O requests from
application programs; for example to make connections to remote devices, such as
a printer, on a server (see Section 5.4.4).

5.1 Supported Terminal Devices

In addition to the multiplexers listed in Table 51, the terminal driver supports
serial line interfaces. At least one such interface is always provided and is
used to attach the system console terminal. This interface does not allow the
setting of multiple terminal speeds, parity, or any maintenance functions,
with the exception of the interface included with the VAX 8200 processor. The
terminal devices supported by the operating system for this interface are listed in
Table 51.
The remote command terminal, used by the DCL command SET HOST, also
makes use of the features listed in Section 5.2.
Table 51 Supported Terminal Devices
Terminal

No.of

Interface

Lines

CXY08

Outout
Silo

Split

International

DMA

Speed

Bus

Modem Control

Yes

Yes

Q-bus

Full

Yes

CXA16

16

Yes

Yes

Yes

Q-bus

No

CXB16

16

Yes1

Yes

Yes

Q-bus

No

DZQ11

No

No

Yes

Q-bus

No

DZQ11-CR

No

No

Yes

Q-bus

No

MicroVAX 2000

No

No

Yes

None

No

MicroVAX 3100

No

No

Yes

None

No

DZV11

No

No

No

Q-bus

No

Yes

Yes

Q-bus

Full

DHQ11

Yes

DHU11

16

Yes

Yes

Yes

UNIBUS

Full

DHV11

No

Yes

Yes

Q-bus

Full

DMB32

No

Yes

Yes

VAXBI bus

Full

DHB32

16

No

Yes

Yes

VAXBI bus

Full

1 Depends

on whether the DHV or DHU mode is selected when the board is installed.

(continued on next page)

Terminal Driver 51

Terminal Driver
5.1 Supported Terminal Devices
Table 51 (Cont.) Supported Terminal Devices
Outout

Terminal

No.of

Interface

Lines

Silo

DMA

Speed

Bus

Modem Control

DSH32

Yes

No

Yes

MicroVAX
2000,
MicroVAX
3100

No

DMF32

Yes

Yes2

Yes2

UNIBUS

Yes

DMZ32

24

Yes

Yes

Yes

UNIBUS

Full

DZ11

8/16

No

No

No

UNIBUS

No

DZ32

No

No

Limited

UNIBUS

No

LAT

Yes

No

Split

International

N/A

VAX 8200
serial lines

No

No

No

None

No

VAXstation 3100

No

No

Yes

None

No

VAXstation 4000

No

No

Yes

None

No

DEC 2000
Model 300

No

No

No

None

Full

DEC 2000
Model 3007

4, 8

Yes

No

No

EISA

Full

AlphaServer 2100

No

No

No

None

Full

AlphaServer7

4, 8

Yes

No

No

EISA

Full

DEC 3000
Model 300

No

Yes

No

None

Full

DEC 3000
Model 400

No

Yes6

No

None

Full

DEC 3000
Model 500

No

Yes6

No

None

Full

DEC 4000
Model 600

No

No

No

None

Full

2 Lines

0 and 1.
dependent.

3 Server

4 The operating system always supports the first serial line as a console interface. The first serial line and the remaining
three serial lines are also supported as user terminal interfaces at a maximum speed of 1200 baud in configurations that
can include a LAT terminal interface, but do not include other terminal interfaces.
5 Communications

only if not booted as alternate console.

6 Communications

only.

7 Optional

multifunctional serial/parallel PC4XD-AA adapter card. You can daisy-chain up to four boards in one system,
resulting in 16, 32, or 64 ports.

5.2 Terminal Driver Features

The terminal driver provides the following features:

Input processing
Command-line editing and command recall
Control characters and special keys
Input character validation (read verify)

52 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
American National Standard Institute (ANSI) escape sequence detection
Type-ahead feature
Specifiable or default input terminators
Special operating modes, such as NOECHO and PASTHRU

Output processing
Efficiency
Limited full-duplex operation
Formatted or unformatted output

Dialup support
Modem control
Hangup on logout
Preservation of process across hangups

Miscellaneous
Terminal/mailbox interaction
Autobaud detection
Out-of-band control character handling

5.2.1 Input Processing

The terminal driver defines many terminal characteristics and read function
modifiers, which provide a wide range of options to an application program.
These options allow multiple levels of control over the terminal drivers input
process, ranging from the default of command line editing that provides a highly
flexible user interface, to the PASTHRU mode, which inhibits input process
interpretation of data.
5.2.1.1 Command-Line Editing and Command Recall
The terminal driver input process defines a bounded set of line editing functions.
You can access these functions with control keys on all keyboards, and with
some special keys on certain keyboards as well. You can move the cursor
in single-character increments (left arrow or Ctrl/D, right arrow or Ctrl/F)
or in multicharacter increments, to the beginning of the line (Ctrl/H) or end
of the line (Ctrl/E). The terminal driver supports both insert character and
overstrike character modes. The insert or overstrike mode is the terminals
default characteristic1 at the beginning of a read operation, but you can change it
with the toggle insert/overstrike key (Ctrl/A). You can delete characters in word
increments (Ctrl/J or line feed) and beginning-of-the-line increments (Ctrl/U).
When you use the terminal drivers editing functions, the following restrictions
result:

You cannot move the cursor to a previous line after a line wrap.

You cannot insert a character if the insertion would force a line wrap or if a
tab follows the current cursor position.

You cannot delete a word at the beginning of a line after a line wrap.

Compaq suggests that new users specify overstrike mode.

Terminal Driver 53

Terminal Driver
5.2 Terminal Driver Features

You cannot assign the line editing function to other keys.

Command recall, initiated by Ctrl/B or the up arrow, returns the last line entered
to the command-line buffer. At this point, you edit or reenter the line by pressing
the Return key. DCL extends command recall to the last 20 commands by using
the TRM$M_TM_NORECALL modifier to disable the terminal drivers recall
mechanism.
Any control key that is not defined by line editing is ignored. For application
programs that require control key input but do not perform QIO functions with
special read modifiers, the SET TERMINAL/NOLINE_EDIT DCL command
restores most of the terminal driver behavior described under OpenVMS Versions
3.0 through 3.7.
5.2.1.2 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 0
and 31, and 127 (hexadecimal 0 through 1F, and 7F); that is, all normal control
characters plus DELETE. (Table C1 lists the numeric values for all control
characters.)
You enter some control characters at the terminal by simultaneously pressing the
Ctrl key and a character key, such as Ctrl/x. Table 52 lists the terminal control
characters. You can change control character echo strings (Ctrl/C, Ctrl/Y, Ctrl/O,
and Ctrl/Z) on a systemwide basis (refer to the OpenVMS System Management
Utilities Reference Manual). You enter special keys, such as Return, Line Feed,
and Escape, by pressing a single key.
Several of the control characters do not function as described if the DCL command
SET TERMINAL/LINE_EDIT is not specified. Refer to the OpenVMS DCL
Dictionary for information on line editing function keys and the SET TERMINAL
command.

54 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Table 52 Terminal Control Characters
Control Character

Meaning

Cancel
(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 5.4.3.2).
The terminal performs a carriage-return/line-feed combination
(carriage return followed by a line feed), echoes CANCEL, and
performs another carriage-return/line-feed combination. If the
terminal has the ReGIS characteristic or if Ctrl/Y is pressed, the
cancel ReGIS escape sequence is sent.
Additional consequences of Ctrl/C are as follows:

The type-ahead buffer is emptied.

Ctrl/S and Ctrl/O are reset.

All queued and in-progress write operations and all inprogress read operations are successfully completed. The
status return is SS$_CONTROLC, or SS$_CONTROLY if
Ctrl/C is converted to Ctrl/Y.

The F6 key maps to Ctrl/C on the following terminal types:

LK201, LK46W, LK461, LK463, and other compatible LK-series
keyboards.
Note that Ctrl/C is generally translated to Ctrl/Y for
processing within DCL, unless you have a Ctrl/C handler. Use
LIB$ENABLE_CTRL and LIB$DISABLE_CTRL to get Ctrl/C
and Ctrl/Y handled within your application. Example 54 shows
a programming example that demonstrates Ctrl/Y and Ctrl/C
handling under OpenVMS.
Delete character
(DELETE)

Removes the last character entered from the input stream.

Delete line
(Ctrl/U)

Purges current input data. When Ctrl/U is entered before the

end of a read operation, the current input line is deleted. (In the
case of a line wrap, Ctrl/U deletes only a line at a time.) If line
editing is enabled (SET TERMINAL/LINE_EDIT is specified),
the data from the beginning of the line to the current cursor
position is deleted.

Delete word
(Ctrl/J or F13)
(Line feed)

Deletes the word before the cursor. Word terminators are all
control characters, space, comma, dash, period, and ! " # $ & (
) + @ [ \ ] ^ { | ~ / : ; <> = ? (see Appendix C).

Discard output
(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/O.
The terminal echoes OUTPUT OFF. 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.

DELETE (decimal 127 or hexadecimal 7F) is ignored if there

are currently no input characters. Hardcopy 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-DELETE character is entered).
Terminals that have the TT$M_SCOPE characteristic echo
DELETE by removing the character.

A second Ctrl/O, which reenables output, echoes OUTPUT ON.

Ctrl/C, Ctrl/Y, and Ctrl/T cancel Ctrl/O.
(continued on next page)

Terminal Driver 55

Terminal Driver
5.2 Terminal Driver Features
Table 52 (Cont.) Terminal Control Characters
Control Character

Meaning

End of line
(Ctrl/E)

Moves the cursor to the end of the line.

Exit
(Ctrl/Z or F10)

Echoes EXIT when Ctrl/Z is entered as a read terminator. By

convention, Ctrl/Z constitutes end-of-file.

Interrupt
(Ctrl/Y)

Ctrl/Y is a special interrupt or attention character that is used to

invoke 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 function code. The command
interpreters Ctrl/Y AST handler always takes precedence over a
user programs Ctrl/Y AST handler.
Entering Ctrl/Y results in an AST to an enabled process to
signify that the user entered Ctrl/Y from the terminal. The
terminal performs a carriage-return/line-feed combination,
echoes INTERRUPT, and performs another carriage-return/linefeed combination 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 as follows:

Move cursor left

(Ctrl/D )

The type-ahead buffer is flushed.

Ctrl/S and Ctrl/O are reset.

All queued and in-progress write operations and all inprogress read operations are successfully completed with a 0
transfer count. The status return is SS$_CONTROLY.

The cancel ReGIS escape sequence is sent.

Moves the cursor one position to the left.

Move cursor right

(Ctrl/F )

Moves the cursor one position to the right.

Move cursor to
beginning of line
(Ctrl/H or F12)
(Backspace)

Moves the cursor to the beginning of the line.

Purge type-ahead
(Ctrl/X)

Purges the type-ahead buffer and performs a Ctrl/U operation.

Action is immediate. If a read operation is in progress, the
operation is equivalent to Ctrl/U.

Recall
(Ctrl/B or
up arrow)

Recalls the last command entered. DCL extends recall to several

commands.

Redisplay input
(Ctrl/R)

Redisplays current input. When Ctrl/R is entered during a read

operation, a carriage-return/line-feed combination is echoed
on the terminal, and the current contents of the input buffer
are 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.
(continued on next page)

56 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Table 52 (Cont.) Terminal Control Characters
Control Character

Meaning

Restart output
(Ctrl/Q)

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_READSYNC, or is not
currently stopped by Ctrl/S.

RET
(Return)

If used during a read (input) operation, RET echoes a carriagereturn/line-feed combination. All carriage returns are filled on
terminals with TT$M_CRFILL specified.

Stop output
(Ctrl/S)

Controls data flow; used by both terminals and the terminal

driver. Ctrl/S stops all data flow; the action occurs immediately
with no echo. Ctrl/S is also used to stop read operations. Ctrl/S
is meaningful only if the terminal has either the TT$M_TTSYNC
characteristic or the TT$M_READSYNC characteristic.

TAB
(Ctrl/I)

Tabs horizontally. Advances to the next tab stop on terminals

with the characteristic TT$M_MECHTAB, but the terminal
driver assumes tab stops on MODULO 8 (multiples of 8) cursor
positions. On terminals without this characteristic, enough
spaces are output to move the cursor to the next MODULO 8
position.

Status
(Ctrl/T)

Displays the current time. Ctrl/T also displays the current node
and user name, the name of the image that is running, and
information about system resources that have been used during
the current terminal session.

Toggle
insert/overstrike
(Ctrl/A or F14)

Changes current edit mode from insert to overstrike, or from

overstrike to insert. The default mode (as set with SET
TERMINAL/LINE_EDIT) is reset at the beginning of each
line.

5.2.1.3 Read Verify

The read verify instructions provided by the terminal driver allow validation
of data as each character is entered. Invalid characters are not echoed and
terminate the operation. The terminal driver does not support full function field
processing. Large data entry applications should use one of the DECforms, FMS,
or TDMS layered products, which support the entire data entry environment.
Section 5.4.1.4 describes the supported primitives.
5.2.1.4 Escape and Control Sequences
Escape and control sequences provide additional terminal control not furnished by
the control characters and special keys (see Section 5.2.1.2). Escape sequences are
strings of two or more characters, beginning with the escape character (decimal
27 or hexadecimal 1B), which 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 Table 55) is used to specify
that terminal lines can generate valid escape sequences. Also, the read function
modifier IO$M_ESCAPE allows any read operation to terminate on an escape
sequence regardless of whether TT$M_ESCAPE is set. If either TT$M_ESCAPE
or IO$M_ESCAPE 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; a read buffer can contain other characters that are

Terminal Driver 57

Terminal Driver
5.2 Terminal Driver Features
not part of an escape sequence, but a complete escape sequence always terminates
a read operation. 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 5.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. If SS$_PARTESCAPE is returned, the application program must issue
enough single-character read requests, without timeout, to read the remaining
characters in the escape sequence, while parsing the syntax of the rest of the
escape sequence. Use of the TRM$_ESCTRMOVR item code prevents SS$_
PARTESCAPE errors. No syntax integrity is guaranteed across read operations.
Escape sequences are never echoed. Valid escape sequences take any of the
following forms (hexadecimal notation):
ESC <int>...<int> <fin>

(7-bit environment)

CSI <int>...<int> <fin>

(8-bit environment)

The keywords in the escape sequences indicate the following:

ESC

The ESC key, a byte (character) of 1B. This character introduces the escape
sequence in a 7-bit environment.

CSI

The control sequence introducer, a byte (character) of 9B. This character

introduces the escape sequence in a 8-bit environment.

<int>

An intermediate character in the range of 20 to 2F. This range includes the

space character and 15 punctuation marks. An escape sequence can contain
any number of intermediate characters, or none.

<fin>

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

Three additional escape sequence forms are as follows:

ESC <;> <20-2F>...<30-7E>
ESC <?> <20-2F>...<30-7E>
ESC <O> <20-2F>...<40-7E>
Control sequences, as defined by the ANSI standard, are escape sequences that
include control parameters. Control sequences have the following format:
ESC [ <par>...<par> <int>...<int> <fin> (7-bit environment)
CSI <par>...<par> <int>...<int> <fin>

(8-bit environment)

The keywords in the control sequences indicate the following:

ESC

The ESC key, a byte (character) of 1B.

A control sequence, a byte (character) of 5B.

CSI

The control sequence introducer, a byte (character) of 9B.

<par>

A parameter specifier in the range of 30 to 3F.

<int>

An intermediate character in the range of 20 to 2F.

<fin>

A final character in the range of 40 to 7E.

For example, the position cursor control sequence is ESC [ Pl ; Pc H where Pl is

the desired line position and Pc is the desired column position.
The user guides for the various terminals list valid escape and control sequences.
For example, the VT100 User Guide lists the escape and control sequences for
VT100 terminals.

58 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Section 5.2.1.2 describes control character functions during escape sequences.
Table C2 lists the valid ANSI and DIGITAL private escape sequences for
terminals that have the TT2$M_ANSICRT, TT2$M_DECCRT, TT2$M_DECCRT2,
TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK characteristics (see Table 56).
Table C2 also lists assumed and selectable ANSI modes and selectable DIGITAL
private modes. Only the names of the escape sequences and modes are listed
(for more information, refer to the specific user guide for the various terminals).
Unless otherwise noted, the operation of escape sequences and modes is identical
to the particular terminals that implement these features.
5.2.1.5 Type-Ahead Feature
Input (data received) from a terminal is always independent of concurrent output
(data sent) to a terminal. This feature 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 Table 55 and Section 5.4.3).
Data entered 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.
Deferring 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 Table 57).
If a read operation is already in progress when the data is typed at the terminal,
the data transfer and echo are immediate.
The action of the driver when the type-ahead buffer fills depends on the set mode
characteristic TT$M_HOSTSYNC (see Table 55 and Section 5.4.3). If TT$M_
HOSTSYNC is not set, Ctrl/G (bell) is returned to inform you that the type-ahead
buffer is full. The buffer must then be emptied, at which time a status of SS$_
DATAOVERUN is returned. 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 begin eight characters before the type-ahead buffer fills
unless the TT2$M_ALTYPEAHD characteristic is set. In that case, the system
generation parameter TTY_ALTALARM is used. The driver sends a Ctrl/Q to
restart transmission when the type-ahead buffer empties completely, and the user
has posted another READ QIO.
The type-ahead buffer length is variable, with possible values in the range of 0
through 32,767. The length can be set on a systemwide basis through use of the
system generation parameter TTY_TYPAHDSZ. Terminal lines that do a large
amount of bulk input should use the characteristic TT2$M_ALTYPEAHD, which
allows the use of a larger type-ahead buffer specified by the system generation
parameters TTY_ALTYPAHD and TTY_ALTALARM. (TTY_ALTYPAHD specifies
the total size of the alternate type-ahead buffer; TTY_ALTALARM specifies the
threshold at which a Ctrl/S is sent.)
Certain input-intensive applications, such as block mode input terminals,
can take advantage of an optimization in the driver. If a terminal has the
characteristic TT2$M_PASTHRU and the read function IO$M_NOECHO is
specified, data is placed directly into the read buffer and thereby eliminates the
overhead for moving the data from the type-ahead buffer.

Terminal Driver 59

Terminal Driver
5.2 Terminal Driver Features
5.2.1.6 Line Terminators
A line terminator is the control sequence that you type at the terminal to indicate
the end of an input line. Optionally, the application 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 (see Appendix C). If line editing is enabled, the only terminators are
CR, Ctrl/Z, or an escape sequence. Control keys that do not have an editing
function are nonfunctioning keys. If included in the request, the argument is a
user-selected group of characters (see Section 5.4.1.2).
All characters are 7-bit ASCII characters unless data is input on an 8-bit terminal
(see Section 5.4.1). The characteristic TT$M_EIGHTBIT determines whether a
terminal uses the 7-bit or 8-bit character set; see Table 55. All input characters
(except some special keys; see Section 5.2.1.2) are tested against the selected
terminators. The input is terminated when a match occurs or your input buffer
fills.
The terminal driver notifies the job controller to initiate login when it detects a
carriage-return terminator on a line with no current process (provided the line
is not a secure server or the type-ahead feature has not been disabled). A bell
character is sent when the notification occurs. A notification character other than
the bell character may be specified by setting the system generation parameter
TTY_AUTOCHAR.
5.2.1.7 Special Operating Modes
The terminal driver supports many special operating modes for terminal lines.
(Tables 55 and 56 in Section 5.3 list these modes.) All special modes are
enabled or disabled by the set mode and set characteristics functions (see
Section 5.4.3).

5.2.2 Output Processing

Output handling is designed to be very efficient in the terminal driver. For
example, on multiplexers that support both silo and direct memory access (DMA)
ouput, the driver considers record size to decide dynamically which mode will
result in the least overhead. The block size specified by the system generation
parameter TTY_DMASIZE is the minimum size block that can be used in a DMA
operation.
5.2.2.1 Duplex Modes
The terminal driver can execute in either half- or full-duplex mode. These modes
describe the terminal driver software, specifically the ordering algorithms used to
service read and write requests, not the terminal communication lines.
In half-duplex mode, all read and write requests are inserted onto one queue.
The terminal driver removes requests from the head of this queue and executes
them one at a time; all requests are executed sequentially in the order in which
they were issued.
In full-duplex mode, read requests (and all other requests except write 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, such as a
read request and a write request at the same time. However, the driver does not
execute the read request and the write request simultaneously. When it is ready
to service a request, the driver decides which requestthe read request or the
write requestto process next.

510 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
The following terms describe the state of a read request:

A read request is active when the terminal driver removes that request from
the head of the I/O queue.

A read request is started when the terminal driver moves the first character
into the read buffer.

In the terminal driver, write requests usually have priority. A write request can
interrupt an active, but not started, read request.
The terminal driver does not start a read request until all outstanding writes are
completed. This means that a read request could be removed from the head of
the read queue while write requests are outstanding, but the first character is not
moved into the read buffer until all outstanding writes are completed.
Once a read request is started, all write requests are queued until the read
completes. However, during a read operation many write requests can be
executed before the first input character is entered at the terminal. Terminal
lines that have the TT$M_NOECHO characteristic, or read functions that
include the IO$M_NOECHO function modifier, do not inhibit write operations
in full-duplex mode.
If a write function specifies the IO$M_BREAKTHRU modifier, the write operation
is not blocked, even by an active read operation. IO$M_BREAKTHRU does not
change the order in which write operations are queued.
When all I/O requests are entered using the Queue I/O Request and Wait
($QIOW) system service, there can be only one current I/O request at a time.
In this case, the order in which requests are serviced is the same for both halfand full-duplex modes.
The type-ahead buffer always buffers input data for which there is no current
read request, in both half- and full-duplex modes.
5.2.2.2 Formatting of Output
By default, output data is subject to formatting by the terminal driver. This
formatting includes actions such as wrapping, tab expansion, uppercase, and
fallback conversions. Applications that do not require formatting of data can
write with the IO$M_NOFORMAT modifier and thereby reduce overhead. IO$M_
NOFORMAT overrides all formatting except fallback translation. Setting the
PASTHRU mode (TT2$M_PASTHRU) is equivalent to writing with the noformat
modifier.
Fallback conversions occur regardless of formatting mode.
5.2.2.3 SET HOST Facility and Output Buffering
The SET HOST facility emulates the terminal driver in the way it writes data to
the terminal by stopping the display as soon as the abort character is entered.
However, the SET HOST facility behaves differently from the terminal driver in
that it buffers output data from the program that is executing. Occasionally, this
causes a perception problem for the user when the program is aborted with a
Ctrl/C, Ctrl/Y, or an out-of-band abort character. The user expects the program to
terminate and the display to stop immediately.

Terminal Driver 511

Terminal Driver
5.2 Terminal Driver Features
CTDRIVER and RTPAD
When used between two systems, the SET HOST facility consists of two
components: RTPAD on the local node and CTDRIVER on the remote node.
Both components buffer output data to enhance performance when using wide
area networks. CTDRIVER performs the initial buffering, queues the buffers for
network transfer, and returns a successful write status. The user should note
that the local terminal display reflects the output of the executing program after
the data has been buffered and transferred over the networknot as the output
buffers are filled on the remote node.
The delay between execution of an application and the display of its output can
lead to several anomalies in the effects of Ctrl/C, Ctrl/Y, and out-of-band abort
characters.
Output Line Not in Sequence Following an Abort Character
After you enter an abort character (Ctrl/C, Ctrl/Y, or an out-of-band abort
character) that causes the input or output to be aborted, it is possible to receive
an additional line of output. This occurs when the application program calls $QIO
(either directly or indirectly through RMS or language support routines) to output
data to a buffer at the same time the abort character is entered.
When CTDRIVER receives the abort character (Ctrl/C, Ctrl/Y, or an out-of-band
abort character) from the network, it flushes the current output buffers and
aborts any pending read operations. However, if the application program calls
$QIO with a write operation when the abort character is entered, the $QIO write
data is still buffered and then displayed. The data may not be the next output
in sequence from the users point of view, since all the previous output buffers in
CTDRIVER were flushed and the data in them was not displayed.
When using the terminal driver, the effect of an abort character on the display
screen is different. The terminal driver does not buffer output from the
application during program execution. If the application program has just called
$QIO with a write operation when the abort character is entered, then the $QIO
write data is displayed. Because all write operations are sequential and do not
complete until the output is actually displayed, the additional line displayed is in
sequence. There is no break in the data. Normally, the user will not notice that
there is an additional line.
Extra Input Prompt Following an Abort Character
For connections between systems, the CTERM protocol allows CTDRIVER to
synchronize with RTPAD before displaying any more data on the terminal.
Note
Prior to VAX VMS Version 5.2, a control character entered during program
execution to abort input and output could cause the system to display
more than one input prompt.
If the SET HOST facility is used between systems running VMS Version
5.2 and an earlier version, the extra input prompt is still displayed.

512 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Processing Abort Characters
The abort character AST is delivered after the message describing the aborted
read operation has been received. Therefore, the read status should be set very
shortly after the abort character AST is delivered to the application. Note,
however, these are still two asynchronous events, and the application must still
synchronize with the completing read operation.
Note
Prior to VAX VMS Version 5.2, if an application had a read operation
pending and had queued a Ctrl/C, Ctrl/Y, or out-of-band abort character
AST, it was possible to queue multiple read operations unknowingly when
the read operation was aborted.

Captive Command Procedures and Ctrl/Y

CTDRIVER and RTPAD emulate the terminal driver in that the current read
operation and all pending write operations abort when Ctrl/Y is entered.
However, the pending write operations also include all the buffered output that
occurred and that would have been output before the Ctrl/Y was entered but due
to the buffering was not.
The effect of the buffering can be confusing if a Ctrl/Y is entered when a
captive command procedure is executing. During execution of captive command
procedures, DCL has a Ctrl/Y pending. When this AST is delivered, DCL only
reenables it; no other action is performed. In that case, if the program being
executed only performs output, it appears that the program was aborted by the
Ctrl/Y. Actually, the program completed execution before the Ctrl/Y was entered,
and the Ctrl/Y merely discarded all the buffered output.

5.2.3 Dialup Support

The operating system supports modem control (for example, Bell 103A, Bell 113,
or equivalent) for all supported multiplexers 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/1 (connect data
set to line signal) in place of the data terminal ready (DTR) signal. Most U.S.
and European modems use the data terminal ready signal, which is the signal
supported by the operating system.
5.2.3.1 Modem Signal Control
Dialup lines with the characteristic TT$M_MODEM are monitored periodically
to detect a change in the modem carrier signals data set ready (DSR), calling
indicator (RING), or request to send (RTS). The system generation parameter
TTY_SCANDELTA establishes the dialup monitoring period for multiplexers that
do not support modem signal transition interrupts (see Table 51).
If a lines carrier signal is lost, the driver waits 2 seconds for the carrier signal
to return. If bit 0 of the system generation parameter TTY_DIALTYPE is set
to 1, the driver does not wait. Bit 0 is 0 by default for countries with Bell
System standards, but that bit should be set to 1 for countries with International
Telegraph and Telephone Consultative Committee (CCITT) standards. If the
carrier signal is not detected during this time, the line is hung up. The hangup
action can signal 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

Terminal Driver 513

Terminal Driver
5.2 Terminal Driver Features
a minimum of 2 seconds after the hangup sequence begins. The hangup sequence
is not reversible. If the line hangs up, all enabled Ctrl/Y and out-of-band ASTs
are delivered; the Ctrl/Y AST P2 argument is overwritten with SS$_HANGUP.
The I/O operation in progress is canceled, and the status value SS$_HANGUP
is returned in the I/O status block. DCL is responsible for process deletion after
Ctrl/Y is delivered. If the process is suspended, DCL cannot run, and therefore
deletion cannot occur, until the process is resumed.
Note
Some systems, such as the VAXstation 3100, provide built-in serial lines
using 6-pin modular jacks. These lines do not provide the minimum
required modem signals. Although the hardware may allow a dial-out
connection to be established, hangup cannot be detected and process
deletion will not occur on these lines.

For terminals with the TT$M_MODEM characteristic, TT$M_REMOTE reflects

the state of the carrier signal. TT$M_REMOTE is set when the carrier signal
changes from off to on, and cleared when the carrier signal is lost.
A line that does not have TT$M_MODEM set does not respond to modem signals
or set the DTR signal. Modem signals can be set and sensed manually through
use of the IO$M_MAINT function modifier (see Section 5.4.3.3).
The terminal driver default modem protocol meets the requirements of the
United States and of European countries. This protocol is capable of working
in automatic answer mode and can also perform manually dialed outgoing calls.
The protocol supports the requirements of most known international telephone
networks. Enhanced modem features are used on multiplexers that support them;
processor polling is not necessary. The protocol also functions in a subset mode
for the multiplexers that do not support full modem signals (see Table 51).
Table 53 lists the control and data signals used in a full modem control
mode configuration (in a two-way simultaneous, symmetrical transmit mode).
Figure 51 is a flowchart that shows a typical signal sequence for a terminal
operation in this mode. The flowchart shows the states that the modem transition
code goes through to detect different types of transitions in modem state. These
transitions allow the driver to detect loss of lines that have been idle for several
minutes. Modem states do not affect the ability of the system to transmit
characters.

514 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Figure 51 Modem Control: Two-Way Simultaneous Operation
DTR
RTS
TX

Idle

OFF
OFF
MARK
TTY_DIALTYPE=2

Delay 2 sec

DTR

ON

RTS

ON

DZ11

Init2

ON

OFF

ON

CARRIER

ON

ON

Transmit0
Start 30sec timer
PORT_RESUME

TTY_DIALTYPE=4

Reference Count>0
DSR

RING

DTR
ON
RTS
ON
Start 30sec timer

CARRIER + CTS + DSR

Reference
Count=0

ON

Delay 1 sec

Init1

Timeout

RING

DZ11 Wait

Wait
DSR

RING Wait

Transmit
Transmit and receive data
CARRIER
Transmit1

OFF
CARRIER

ON

Start 2sec timer

TTY_DIALTYPE=1

Timeout

Shutdown

DTR

DSR

OFF

OFF

Delay 1 sec

Timeout
DSR

OFF

Shut1
Start 2sec timer
ZK0687GE

Set mode function modifiers are provided to allow a process to activate or

deactivate modem control signals (see Section 5.4.3.3).

Terminal Driver 515

Terminal Driver
5.2 Terminal Driver Features
Bit 1 of the system generation parameter TTY_DIALTYPE enables alternate
modem protocol on a systemwide basis. If bit 1 is 0 (the default), the RING signal
is not used. If bit 1 is 1, the modem protocol delays setting the DTR signal until
the RING signal is detected.
Remote terminal connections have a timeout feature for the security of dialup
lines. If no channel is assigned to the port within 30 seconds, or a port
with an assigned channel is not allocated, the DTR signal is dropped. Such
action prevents an unused terminal from tying up a line. However, there are
configurations (such as a printer connected to a remote line) in which the line
should not be dropped even though it is not being used interactively. To bypass
the 30-second timeout, set the system generation parameter TTY_DIALTYPE
to 4. (Note that if TTY_DIALTYPE is equal to 4, all dialup lines will skip the
timeout waiting for a channel to be assigned.)
Table 53 Control and Data Signals (Full Modem Mode Configuration)
Signal

Source

MUX1

Meaning

Transmitted
data (TxD)

Computer

All

The data originated by the computer

and transmitted through the modem to
one or more remote terminals.

Received data
(RxD)

Modem

All

The data generated by the modem

in response to telephone line signals
received from a remote terminal and
transferred to the computer.

Request to
send (RTS)

Computer

Full

If present (ON condition), RTS directs

the modem to assume the transmit
mode. If not present (OFF condition),
RTS directs the modem to assume the
nontransmit mode after all transmit
data has been transmitted.

Clear to send
(CTS)

Modem

Full

Indicates whether the modem is ready

(ON condition) or not ready (OFF
condition) to transmit data on the
telephone line.

Data set ready

(DSR)

Modem

Full

If present (ON condition), DSR

indicates that the modem is ready
to transmit and receive; that is, the
modem is connected to the line and
is ready to exchange further control
signals with the computer to initiate
the exchange of data.
If DSR is not present (OFF condition),
the modem is not ready to transmit
and receive. If DSR is detected, the
operating system initiates a 30-second
timer. This ensures that the phone
line will be disconnected if CARRIER
is not detected.

1 Multiplexers (All = any supported controller; Full = DZ32, DMF32, DMB32, DMZ32, DHU11, DHV11,
and CXY08).

(continued on next page)

516 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Table 53 (Cont.) Control and Data Signals (Full Modem Mode Configuration)
Signal

Source

MUX1

Meaning

Data channel
received line
signal detector
(CARRIER)

Modem

All

If present (ON condition), CARRIER

indicates that the received data
channel line signal is within
appropriate limits, as specified by
the modem. If not present (OFF
condition), the received signal is not
within appropriate limits.

Data terminal
ready (DTR)

Computer

All

If present (ON condition), DTR

indicates that the computer is ready
to operate, prepares the modem to
connect to the telephone line, and
maintains the connection after it has
been made by other means. DTR can
be present whenever the computer is
ready to transmit or receive data. If
DTR is not present (OFF condition),
the modem disconnects the modem
from the line.

Calling
indicator
(RING)

Modem

All

Indicates whether a calling signal is

being received by the modem. Bit 1
of the system generation parameter
TTY_DIALTYPE must be set (=1).
If RING is detected, the operating
system initiates a 30-second timer.
This ensures that the phone line will
be disconnected if CARRIER is not
detected.

1 Multiplexers (All = any supported controller; Full = DZ32, DMF32, DMB32, DMZ32, DHU11, DHV11,
and CXY08).

5.2.3.2 Hangup on Logging Out

By default, logging out on a line with modem signals will not break the
connection. If TT2$M_HANGUP is set, modem signals are dropped when the
process logs out. If TT2$M_MODHANGUP is set, no privilege is required to
change the state of TT2$M_HANGUP. By setting TT2M_HANGUP, system
managers can prevent nonprivileged users who are not logged in from tying up a
dial-in line.
5.2.3.3 Preservation of a Process Across Hangups
Disconnectable terminals allow a connection to a physical terminal line to be
broken without losing the job.
On VAX systems, the following SYSGEN command allows terminals to be
disconnectable terminals:
SYSGEN> CONNECT VTA0/NOADAPTER/DRIVER=TTDRIVER
On Alpha systems, the following SYSMAN command allows terminals to be
disconnectable terminals:
SYSMAN> IO CONNECT VTA0/NOADAPTER/DRIVER=SYS$TTDRIVER

Terminal Driver 517

Terminal Driver
5.2 Terminal Driver Features
On VAX and Alpha systems, after this command is entered, a terminal with the
TT2$M_DISCONNECT characteristic logs in as VTAn:, rather than with the
physical terminal name. When a terminal is set up in this manner, no input
or output operations are allowed to the physical device; I/O is automatically
redirected to the appropriate virtual terminal.
Following are four ways in which a terminal can become disconnected:

Modem signals between the host and the terminal are lost.

A user presses the BREAK key on a terminal that has the TT2$M_SECURE
characteristic.

A user enters the DCL command DISCONNECT.

A user enters the DCL command CONNECT/CONTINUE.

After validated as a user, you can connect to a disconnected process in either of

the following ways:

Allow the login process to make the connection.

Enter the DCL command CONNECT.

5.2.4 Terminal/Mailbox Interaction

Mailboxes are virtual I/O devices used to communicate between processes. The
terminal I/O driver can use a mailbox to communicate with a user process.
Chapter 4 describes the mailbox driver.
A user program can use the Assign I/O Channel ($ASSIGN) system service to
associate a mailbox with one or more terminals. The terminal driver sends
messages to this mailbox when terminal-related events that require the attention
of the user image occur.
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 receiving this message,
the user program reads 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 5.4.1 and 5.4.2). (Initially, mailbox messages are enabled on all
terminals. This is the default state.) Therefore, 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. Only one message is sent
between read operations.

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

Broadcast messages. If the characteristic TT2$M_BRDCSTMBX is set,

broadcasts sent to a terminal are placed in the mailbox (this is independent
of the state of TT$M_NOBRDCST).

518 Terminal Driver

Terminal Driver
5.2 Terminal Driver Features
Messages placed in the mailbox have the following content and format (see
Figure 52):

Message type. The codes MSG$_TRMUNSOLIC (unsolicited data), MSG$_

TRMHANGUP (hangup), and MSG$_TRMBRDCST (terminal broadcast)
identify the type of message. Message types are identified by the $MSGDEF
macro.

Device unit number to identify the terminal that sent the message.

Counted string to specify the device name.

Controller name.

Message (for broadcasts).

Figure 52 Terminal Mailbox Message Format

31

16 15
Unit Number
Controller Name *

87

Message Type

Counted String

4
8
12
16

Broadcast Message Length

20
Broadcast
Message

* Does not include the colon (:) character.

ZK0686GE

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

5.2.5 Autobaud Detection

If you specify the /AUTOBAUD qualifier with the SET TERMINAL command,
automatic baud rate detection is enabled, allowing the terminal baud rate to be
set when you log in. The baud rate is set at login by pressing the Return key
two or more times separated by an interval of at least one second. (Pressing a
key other than Return might detect the wrong baud rate; if this occurs, wait for
the login procedure to time out before continuing.) The supported baud rates are
110, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 9600, and 19,200. Newer Alpha
systems can autobaud up to 57600. Parity is allowed on these lines.
The autobaud function works with either even parity or no parity, but not
with odd parity. If a line is set to even parity and has 7 bits of data, the line
automatically switches to no parity if a terminal not generating parity attempts
to log in.
Terminal Driver 519

Terminal Driver
5.2 Terminal Driver Features
The SET TERMINAL qualifier /EIGHT_BIT specifies that the terminal uses
8-bit ASCII code. /NOEIGHT_BIT, which is the default, specifies 7-bit ASCII
code. (If parity is specified, the parity bit is separate from the data bits.) The
optimal settings for automatic baud rate detection on Compaq terminals are
/NOEIGHT_BIT/PARITY=EVEN or /EIGHT_BIT/NOPARITY, although automatic
baud rate detection also works with other combinations, such as /NOEIGHT_
BIT/NOPARITY.
Table 56 describes the terminal characteristic TT2$M_AUTOBAUD, which
allows the baud rate to be set automatically at login.
Compaq does not usually recommend specifying the /FRAME qualifier with the
SET TERMINAL command. The terminal driver selects the frame size (the
number of data bits that the device can transmit) based on how the /PARITY and
/EIGHT_BIT qualifiers are set. It might be necessary to change these values if
the terminal is not made by Compaq.

5.2.6 Out-of-Band Control Character Handling

All control characters (0 through 1F hexadecimal) can be enabled as out-of-band
characters. Typing one of these characters immediately delivers an AST to the
requesting process. DCL uses this mechanism to sense whether Ctrl/T has been
entered. Out-of-band character options allow using the IO$M_INCLUDE function
modifier to include the character in the data stream and the IO$M_TT_ABORT
function modifier to abort the current input or output operation.

5.3 Terminal Driver Device Information

You can obtain information on terminal characteristics by using the Get
Device/Volume Information ($GETDVI) system service. (Refer to the OpenVMS
System Services Reference Manual.) The sense mode function provides an
alternative means to obtain terminal characteristics; see Section 5.4.5.
$GETDVI returns terminal characteristics when you specify the item codes
DVI$_DEVCHAR, DVI$_DEVDEPEND, and DVI$_DEVDEPEND2. Tables 54,
55 and 56 list these characteristics. Terminal characteristics are normally set
during system generation to any one of, or a combination of, the values listed in
Table 55. DVI$_DEVDEPEND returns a longword field in which the three loworder bytes contain the device-dependent characteristics and the high-order byte
contains the page length. Page length can have a value in the range of 0 through
255. The $DEVDEF macro defines the device-independent characteristics, the
$TTDEF macro defines the device-dependent characteristics, and the $TT2DEF
macro defines the extended device-dependent characteristics.
DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device type
names, which are defined by the $DCDEF and $TTDEF macros, respectively. The
device class for terminals is DC$_TERM. The terminal model determines the
device type. For example, the device type for the VT240 is TT$_VT200_SERIES.
DVI$_DEVBUFSIZ returns the page width, which can be a value in the range of
1 through 511. The driver does not accept a value of 0.

520 Terminal Driver

Terminal Driver
5.3 Terminal Driver Device Information
Table 54 Terminal Device-Independent Characteristics
Characteristic

Meaning

DEV$M_AVL

Terminal is on line and available.

DEV$M_CCL

Carriage control is enabled.

DEV$M_DET

Terminal is detached.

DEV$M_IDV

Terminal is capable of input.

DEV$M_ODV

Terminal is capable of output.

DEV$M_OPR

Terminal is enabled as an operator console.

DEV$M_REC

Device is record-oriented.

DEV$M_RTT

Terminal has remote terminal UCB extension.

DEV$M_SPL

Device is spooled.

DEV$M_TRM

Device is a terminal.

DEV$M_NET

Terminal line is allocated for DECnet use.

Table 55 Terminal Characteristics

Value1

Meaning

TT$M_CRFILL

Terminal requires fill after the Return key is pressed (the fill
type can be specified by the set mode function P4 argument).

TT$M_EIGHTBIT

Terminal uses the 8-bit ASCII character set (see Appendix C).
Terminals without this characteristic use the 7-bit ASCII
code. In this case, the eighth bit is masked out on received
characters and is 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 5.2.1.4).

Escape sequences are validated for syntax.

TT$M_HALFDUP

Terminal is in half-duplex mode (see Section 5.2.2.1). All read

and write requests are executed sequentially.

TT$M_HOSTSYNC

The host system is synchronized to the terminal. Ctrl/Q and

Ctrl/S are used to control data flow and thus keep the typeahead buffer from filling. TT$M_HOSTSYNC should always be
set on LAT terminals.

TT$M_LFFILL

Terminal requires fill after the line-feed character is processed.

(The fill can be specified by the set mode P4 argument.)

TT$M_LOWER

Terminal has the lowercase character set. Unless the terminal

is in the PASTHRU mode or IO$M_NOFORMAT is specified,
all input and echoed lowercase characters (hexadecimal 61
to 7A) are converted to uppercase if TT$M_LOWER is not
set. (The character ALTMODE (decimal 125 and 126, or
hexadecimal 7D and 7E) converts to ESCAPE on terminals
that do not have the lowercase characteristic TT$M_LOWER
set.)

1 Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose bit
corresponds to the specific field; TT$V_ is a bit number.

(continued on next page)

Terminal Driver 521

Terminal Driver
5.3 Terminal Driver Device Information
Table 55 (Cont.) Terminal Characteristics
Value1

Meaning

TT$M_MBXDSABL

Mailboxes associated with the terminal do not receive

notification of unsolicited input or hangup (see Section 5.2.3).
This bit can be set by the IO$M_DSABLMBX function modifier
for read requests and cleared by the IO$M_ENABLMBX
function modifier for write requests.

TT$M_MECHFORM

Terminal has mechanical form feed. The terminal driver

passes form feeds directly to the terminal instead of expanding
to line feeds.

TT$M_MECHTAB

Terminal has mechanical tabs and is capable of tab expansion.

To accomplish correct line wrapping, the terminal driver
assumes there are eight spaces between tab stops.

TT$M_MODEM

Terminal line is connected to a modem. If TT$M_MODEM

is set, the terminal driver automatically handles modem
control. If TT$M_MODEM is not set, all modem signals are
ignored. If TT$M_MODEM is set and then cleared, a hangup
is declared on the terminal line if that line is in the remote
state (TT$M_REMOTE is set). If DTR and RTS are set with
IO$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT on a
nonmodem port, DTR and RTS goes off and then back on when
the port is set for modem.
TT$M_MODEM is not supported for LAT devices.

TT$M_NOBRDCST

Terminal does not receive any broadcast messages.

TT$M_NOECHO

Input characters are not echoed on this terminal line (see

Section 5.2.1.5).

TT$M_NOTYPEAHD

Data must be solicited by a read operation. Data is lost if

received in the absence of an outstanding read request (if
it is unsolicited data). Disables type-ahead feature (see
Section 5.2.1.5). If this characteristic is set, login attempts
on this line are disabled. See Section 5.2.3.1 for information on
modem signal control.

TT$M_READSYNC

Read synchronization is enabled. The host explicitly solicits

all read operations by entering a Ctrl/Q and terminates the
operation by entering a Ctrl/S. TT$M_READSYNC is not
applicable to LAT terminals.

TT$M_REMOTE

Dialup characteristic is enabled. The terminal returns to

local mode when a hangup occurs on the terminal line (see
Section 5.2.3). This characteristic cannot be changed; it is only
informational.

TT$M_SCOPE

Terminal is a video screen display (CRT terminal), for example,

the VT100 or VT240 terminals.

TT$M_TTSYNC

The terminal is synchronized to the host system. Output to the

terminal is controlled by terminal-generated Ctrl/Q or Ctrl/S.
TT$M_TTSYNC is not applicable to LAT terminals unless
TT$M_PASTHRU is set and TT$M_TTSYNC is disabled, in
which case the LAT session is placed in PASSALL mode.

1 Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose bit
corresponds to the specific field; TT$V_ is a bit number.

(continued on next page)

522 Terminal Driver

Terminal Driver
5.3 Terminal Driver Device Information
Table 55 (Cont.) Terminal Characteristics
Value1

Meaning

TT$M_WRAP

A carriage-return/line-feed combination should be inserted if

the cursor moves beyond the right margin. If TT$M_WRAP
is not set, no carriage-return/line-feed combination is sent.
The operating system does not support hardware-provided
wrapping functions.

1 Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose bit
corresponds to the specific field; TT$V_ is a bit number.

Table 56 Extended Terminal Characteristics

Value1

Meaning

TT2$M_ALTYPEAHD

Alternate type-ahead buffer size is enabled. Use the

alternate type-ahead buffer size specified during system
generation (see Section 5.2.1.5). If a type-ahead buffer
already exists for a terminal line, there is no effect
when this characteristic is set for that line. TT2$M_
ALTYPEAHD should be set prior to using the terminal,
such as in the startup command procedure. You can only
set TT2$M_ALTYPEAHD; this characteristic cannot be
cleared until the system is rebooted.

TT2$M_ANSICRT

ANSI CRT terminal is enabled. This characteristic is set

by the SET TERMINAL command. TT2$M_ANSICRT
is a subset of the ANSI standard with no DIGITAL
private escape sequences (see Appendix C). It is also a
subset of the VT100 family terminals (because TT2$M_
ANSICRT is a subset of TT2$M_DECCRT) and the
VT100. Terminals with this characteristic must provide
a display of at least 24 lines, each with 80 columns.

TT2$M_APP_KEYPAD

Notifies application programs of state to set the keypad

to when exiting.

TT2$M_AUTOBAUD

Automatic baud rate detection is enabled. This

characteristic allows the baud rate to be set
automatically when you log in. (The baud rate is set
when one or more carriage returns are entered during
the login procedure.) Terminals are set to a permanent
speed of 9600 baud. If TT2$M_AUTOBAUD is specified,
the permanent speed must not be changed while this
characteristic is in use on a given terminal line. See
Section 5.2.5 for additional information on automatic
baud rate detection.

TT2$M_AVO

Advanced video is enabled. This characteristic provides

the terminal with blink, bold, and flashing fields as well
as a full screen of 132 character lines. TT2$M_AVO
is set by the SET TERMINAL command. Appendix C
lists the valid escape sequences for terminals with the
TT2$M_AVO characteristic.

1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in
which the bit set corresponds to the specific field; TT2$V_ is a bit number.

(continued on next page)

Terminal Driver 523

Terminal Driver
5.3 Terminal Driver Device Information
Table 56 (Cont.) Extended Terminal Characteristics
Value1

Meaning

TT2$M_BLOCK

Block mode is enabled. This characteristic is set by

the SET TERMINAL command. TT2$M_BLOCK
defines additional ANSI-defined and DIGITAL private
escape sequences (see Appendix C). Terminals with this
characteristic are capable of local editing and block
mode transmission (XON/XOFF flow control must be
honored), and have protected fields. If the terminal
is used for large amounts of block input, TT2$M_
ALTYPEAHD should also be specified.

TT2$M_BRDCSTMBX

Mailbox broadcasts messages. Broadcast messages are

sent to an associated mailbox, if one exists.

TT2$M_COMMSYNC

Enables devices such as asynchronous printers to be

connected to terminal ports. Flow control is handled
by EIA modem signals instead of XON/XOFF. Setting
TT2$M_COMMSYNC activates the DTR and RTS
signals; data is sent once the DSR and CTS signals are
also present. If either of these signals is not present,
printing stops. When both signals are present again,
printing resumes.
Do not set TT2$M_COMMSYNC on a line connected
to a modem that is intended for interactive use.
TT2$M_COMMSYNC disables the modem terminal
characteristic that disconnects a user process from the
terminal line in case of a modem phone line failure.
With TT2$M_COMMSYNC set, the next call on the
terminal line could be attached to the previous users
process. TT2$M_COMMSYNC should also not be used
in combination with XON/XOFF, TT$M_TTSYNC, or
TT$M_HOSTSYNC. TT2$M_COMMSYNC and TT$M_
MODEM are mutually exclusive.

TT2$M_DECCRT

DIGITAL CRT terminal. This characteristic is set by

the SET TERMINAL command for all terminals that
are upward-compatible with VT100 family terminals.
TT2$M_DECCRT is a superset of TT2$M_ANSICRT.
Additional ANSI-defined as well as most DIGITAL
private escape sequences are allowed for terminals
with this characteristic (see Appendix C); maintenance
modes, VT52 mode, and the use of the LED displays are
not defined by TT2$M_DECCRT. Not all VT100 family
terminals implement these features. The presence of
the advanced video feature cannot be assumed because
it is a VT100 option. This restricts the use of graphics
attributes. However, the TT2$M_AVO characteristic
can be used to determine whether additional graphic
attributes are available.

TT2$M_DECCRT2

DIGITAL CRT terminal. This characteristic is set by

the SET TERMINAL command for all terminals that
are upward-compatible with VT200 family terminals.
TT2$M_DECCRT2 is a superset of TT2$M_DECCRT.

1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in
which the bit set corresponds to the specific field; TT2$V_ is a bit number.

(continued on next page)

524 Terminal Driver

Terminal Driver
5.3 Terminal Driver Device Information
Table 56 (Cont.) Extended Terminal Characteristics
Value1

Meaning

TT2$M_DECCRT3

DIGITAL CRT terminal. This characteristic is set by

the SET TERMINAL command for all terminals that
are upward-compatible with VT300 family terminals.
TT2$M_DECCRT3 is a superset of TT2$M_DECCRT2.

TT2$M_DECCRT4

DIGITAL CRT terminal. This characteristic is set by

the SET TERMINAL command for all terminals that
are upward-compatible with VT400 family terminals.
TT2$M_DECCRT4 is a superset of TT2$M_DECCRT3.

TT2$M_DIALUP

Terminal is a dialup line. Used by LOGINOUT for the

disable dialup control.

TT2$M_DISCONNECT

Allows terminal disconnect when a hangup occurs

(that is, when modem signals are lost, when the DCL
commands DISCONNECT or CONNECT/CONTINUE
are entered, or when the BREAK key is pressed
on a terminal that has the TT2$M_SECURE
characteristic). These terminals are created as VTAn:.
(Refer to the description for the DCL command
CONNECT/DISCONNECT in the OpenVMS DCL
Dictionary.)

TT2$M_DMA

Direct memory access (DMA) mode. This characteristic

enables the use of DMA mode for asynchronous DMA
multiplexers. It is ignored by non-DMA controllers.

TT2$M_DRCS

Terminal supports loadable character fonts. This

characteristic is set with the DCL command SET
TERMINAL/SOFT_CHARACTERS.

TT2$M_EDIT

Terminal edit. This characteristic is set by the SET

TERMINAL command for all terminals that support
ANSI-defined advanced editing functions. These
functions include the ability to insert or delete a line
and the ability to insert or delete characters in an
existing line. Terminals with this characteristic are a
superset of TT2$M_DECCRT. Appendix C lists the valid
escape sequences for terminals with the TT2$M_EDIT
characteristic.

TT2$M_EDITING
TT2$M_FALLBACK

Line editing is allowed.

2

Output is transformed from the 8-bit multinational

character set to a 7-bit ASCII character set on
terminals that do not support the 8-bit character set
(see Appendix C).

TT2$M_HANGUP

Terminal hangup. Terminal lines connected through

modems are hung up when a process logs out or is
deleted. The state of this characteristic cannot be
changed unless TT2$M_MODHANGUP is enabled or
the process has either LOG_IO or PHY_IO privilege.

TT2$M_INSERT

Sets default mode for insert or overstrike at the

beginning of each read operation.

1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in
which the bit set corresponds to the specific field; TT2$V_ is a bit number.
2 If an attempt is made to turn on TT2$V_FALLBACK for a disconnected virtual terminal (_VTAx:)
or if the Terminal Fallback Facility (TFF) has not been activated, the status code SS$_BADPARAM
is returned. For more information on TFF, refer to the OpenVMS Terminal Fallback Utility Manual
(available on the Documentation CD-ROM).

(continued on next page)

Terminal Driver 525

Terminal Driver
5.3 Terminal Driver Device Information
Table 56 (Cont.) Extended Terminal Characteristics
Value1

Meaning

TT2$M_LOCALECHO

Local echo. This characteristic is used with TT$M_

NOECHO. If both characteristics are set, only
terminators and special control characters are echoed.
Use of this mode is restricted to command-line read
operations. Application programs that use the IO$M_
NOECHO function modifier will not necessarily work
if TT2$M_LOCALECHO is set. Local echo is also not
compatible with line editing (TT2$M_EDITING).

TT2$M_MODHANGUP

Modify hangup. If specified, TT2$M_HANGUP can

be modified without privilege. Otherwise, logical or
physical I/O privilege is required.

TT2$M_PASTHRU

Terminal is in PASTHRU mode; all input and

output data is in 7- or 8-bit binary format (no data
interpretation occurs). Data is terminated when the
buffer is full or when the data that is read matches
the specified terminator. If the characteristic TT$M_
TTSYNC is set, Ctrl/S and Ctrl/Q interpretation does
occur.

TT2$M_PRINTER

DIGITAL CRT terminal with a local printer port.

TT2$M_REGIS

ReGIS graphics. The terminal supports the ReGIS

graphics instruction set.

TT2$M_SIXEL

SIXEL graphics. The terminal supports the SIXEL

graphics instruction set.

TT2$M_SECURE

For use with nonmodem, nonautobaud lines. This

characteristic guarantees that no process is connected
to the terminal after the BREAK key is pressed. If
TT2$M_SECURE is not set, BREAK is a null key.

TT2$M_SETSPEED

Set speed. If specified, either LOG_IO or PHY_IO

privilege is required to change terminal speed. TT2$M_
SETSPEED is not supported for LAT devices.

TT2$M_SYSPWD

System password. This characteristic specifies that the

login procedure should require the system password
before the user name prompt is displayed.

TT2$M_XON

XON/XOFF control. If a set mode function is performed

on a terminal in the Ctrl/S state, and if TT2$M_XON
is set, output is resumed. Users should note that the
driver will attempt to resume stopped (XOFF) output
on the line. However, restarting the output may not be
successful in all cases. The XON/XOFF feature does not
work on all terminals, for example, the VT220.

1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a bit mask in
which the bit set corresponds to the specific field; TT2$V_ is a bit number.

5.3.1 Terminal Characteristics Categories

The set mode and set characteristics functions (see Section 5.4.3) and the DCL
command SET TERMINAL are used to change terminal characteristics. The
OpenVMS DCL Dictionary describes the SET TERMINAL command.

526 Terminal Driver

Terminal Driver
5.3 Terminal Driver Device Information
To customize terminal behavior and usage, the operating system divides terminal
characteristics into the following categories:

Format effectorsThe following characteristics allow you to specify terminaldependent formatting requirements:
TT$M_CRFILL

TT$M_EIGHTBIT

TT$M_LFFILL

TT$M_LOWER

TT2$M_LOCALECHO

TT$M_MECHFORM

TT$M_MECHTAB

TT$M_NOECHO

TT$M_SCOPE

TT$M_WRAP

Generic terminal capabilitiesThe following characteristics specify generic

terminal features available to applications programs:
TT2$M_ANSICRT

TT2$M_AVO

TT2$M_BLOCK

TT2$M_DECCRT

TT2$M_DECCRT2

TT2$M_DECCRT3

TT2$M_DECCRT4

TT2$M_DRCS

TT2$M_EDIT

TT2$M_PRINTER

TT2$M_REGIS

TT2$M_SIXEL

Their use allows execution of these programs without knowledge of the actual
terminal type. For example, a program should check for TT2$M_DECCRT
rather than for VT100 or VT101.

ProtocolThe following characteristics control protocols used by the terminal:

TT$M_ESCAPE

TT$M_HALFDUP

TT2$M_PASTHRU

TT$M_TTSYNC

TT$M_HOSTSYNC

System managementThe following characteristics, normally set only at

system startup, allow the system manager to regulate terminal usage:
TT2$M_ALTYPEAHD

TT2$M_AUTOBAUD

TT2$M_DIALUP

TT2$M_DISCONNECT

TT2$M_DMA

TT2$M_HANGUP

TT$M_MODEM

TT$M_NOTYPEAHD

TT2$M_MODHANGUP

TT2$M_SECURE

TT2$M_SETSPEED

TT2$M_SYSPWD

TT2$M_COMMSYNC

User preferenceThe following characteristics allow you to customize the

terminal operating mode:
TT2$M_APP_KEYPAD

TT2$M_FALLBACK

TT2$M_INSERT

TT$M_NOBRDCST

TT2$M_EDITING

MiscellaneousThe following characteristics provide greater program control

of terminal operations:
TT2$M_BRDCSTMBX

TT$M_MBXDSABL

TT2$M_XON

5.4 Terminal Function Codes

The basic terminal I/O functions are read, write, set mode, set characteristics,
sense mode, and sense characteristics. All I/O functions can take function
modifiers.

Terminal Driver 527

Terminal Driver
5.4 Terminal Function Codes
5.4.1 Read
When a read function code is issued, the user-specified buffer is filled with
characters from the associated terminal. The operating system provides the
following read function codes:

IO$_READVBLKRead virtual block

IO$_READLBLKRead logical block

IO$_READPROMPTRead with prompt

Read operations are terminated if either of the following two conditions occurs:

The user buffer is full.

The received character is included in a specified terminator mask (see

Section 5.4.1.2).

The following device- or function-dependent arguments are used with the

read function codes. The codes can take all six arguments (P1 through P6)
on QIO requests. The descriptions for these arguments differ when itemlist read
operations are performed (see Section 5.4.1.3).

P1The starting virtual address of the buffer that is to receive the data read.

P2The size of the buffer that is to receive the data read in bytes. (The
system generation parameter, MAXBUF, and the terminal driver limit the
maximum size of the buffer. The terminal driver will only function with
buffer sizes less than 32718 bytes.)

P3Read with timeout, timeout count (see Table 57, IO$M_TIMED).

P4The read terminator descriptor block address (see Section 5.4.1.2).

P5The starting virtual address of the prompt buffer that is to be written to

the terminal; for read with prompt operations using the IO$_READPROMPT
function code. (This argument is specified as a value rather than an address
as in the P1 argument.)

P6The size of the prompt buffer that is to be written to the terminal; for
read with prompt operations using the IO$_READPROMPT function code.

In a read with prompt operation, the P5 and P6 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, both read and
write operations are performed on the specified terminal. The prompt string
buffer is formatted like any other write buffer. If cursor position specifiers are
supplied, they are not interpreted by the driver but passed to the terminal.
During a read with prompt operation, pressing Ctrl/O (which is turned off at the
start of any read operation) stops the prompt string. If you press either Ctrl/U
or Ctrl/X, the entire prompt string is written out again, and the current input is
ignored. If you press Ctrl/R, the current prompt string and input are written to
the terminal.
Depending on the terminal type and your input, the prompt string can be very
simple or quite complexfrom single command prompts to screen fills followed
by input data. Compaq recommends that prompt strings contain only one leading
line feed.

528 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
In PASTHRU mode, data received from the associated terminal is placed in
the user buffer as binary information without interpretation. (Prompts are not
refreshed after a broadcast in PASTHRU mode.)
5.4.1.1 Function Modifier Codes for Read QIO Functions
Eight function modifiers can be specified with IO$_READVBLK, IO$_
READLBLK, and IO$_READPROMPT. Table 57 lists these function modifiers
and IO$_EXTEND, which is described in Section 5.4.1.3. All read function
modifiers are supported for LAT devices.
Table 57 Read QIO Function Modifiers for the Terminal Driver
Code

Consequence

IO$M_CVTLOW

Lowercase alphabetic characters (hexadecimal 61 to 7A) are

converted to uppercase when transferred to the user buffer or
echoed. This characteristic is used only for IO$_READLBLK,
IO$_READVBLK, and IO$_READPROMPT.

IO$M_DSABLMBX

The mailbox is disabled for unsolicited data.

IO$M_ESCAPE

A valid ANSI escape sequence is recognized as a valid delimiter

for the read operation. The TT$M_ESCAPE characteristic is
overridden by this modifier for the current read operation.

IO$M_EXTEND

This characteristic provides additional functionality for read

operations (see Section 5.4.1.3). Do not specify IO$M_EXTEND
with other function modifiers.

IO$M_NOECHO

Characters are not echoed 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. Setting IO$M_NOECHO also disables line
editing.

IO$M_NOFILTR

The terminal does not interpret Ctrl/U, Ctrl/R, or DEL. They

are passed to the user. IO$M_NOFILTR explicitly disables line
editing.

IO$M_PURGE

The type-ahead buffer is purged before the read operation

begins.
(continued on next page)

Terminal Driver 529

Terminal Driver
5.4 Terminal Function Codes
Table 57 (Cont.) Read QIO Function Modifiers for the Terminal Driver
Code

Consequence

IO$M_TIMED

The P3 argument specifies the maximum time (seconds) that

can elapse between characters received from the terminal
(the timeout value for the operation), only if IO$M_TIMED is
specified as a modifier on the read function code.
Note that if you are using a timeout in an item list of a $QIO
read to a terminal driver, the timeout on an extend read must
go into the item list.
Because driver timing operates on a 1-second timer, a 2-second
timeout must be specified to guarantee a 1-second wait. The
timer starts when the prompt echo is started. If the read
time exceeds the time specified in P3, a timeout error (SS$_
TIMEOUT) is returned in the read IOSB. All input characters
received before the read operation timed out are returned in
the users buffer.
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, SS$_NORMAL; SS$_TIMEOUT
is returned if no terminator is read. In either case the offset
to terminator in the IOSB always indicates the number of
characters read.
If a write request is active and there is no prompt string, the
read request generally times out with zero bytes of data being
returned.
If a read operation is interrupted by either a broadcast write or
a synchronous write request, the timer operation is restarted.

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.

5.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 0, all ASCII characters with a code in the range 0 through 31 (hexadecimal 0
through 1F) except LF, VT, FF, TAB, and BS, are terminators (see Appendix C).
This is the RMS standard terminator set. The delete character (hexadecimal 7F)
and 8-bit controls in the range 128 through 159, and 255 (hexadecimal 80 through
9F, and FF) are also terminators. If line editing is enabled, only Return, Ctrl/Z,
or an escape sequence terminates a read operation.
If P4 does not equal 0, it contains the address of a quadword that either specifies
a terminator character bit mask or points to a location containing that mask.
(Note that if P4 references an address in a MACRO program, a number sign
( # ) must precede the address; for example, P4=#TMASK.) The quadword has
a short form and a long form, as shown in Figure 53. 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 0 through
31, the short form can be used in most cases.

530 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
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 zeros, there are no specified terminators. The
read operation ends when the specified number of bytes (characters) have been
transferred to the input buffer.
Certain control keys will not act as terminators unless IO$M_NOFILTR
is specified or the line has the TT2$M_PASTHRU characteristic (see
Section 5.2.1.2).
Figure 53 Short and Long Forms of Terminator Mask Quadwords
31

SHORT:

0
Terminator Character Bit Mask

31
LONG:

16 15
(Not Used)

0
Mask Size in Bytes

Address of Mask
ZK0689GE

5.4.1.3 Itemlist Read Operations

Itemlist read operations provide expanded software features to read QIO requests.
The operating system provides the following combination of function code and
modifier:
IO$_READVBLK!IO$M_EXTENDItemlist read virtual block
No other function modifiers can be specified in an itemlist read request.
Note
Itemlist read features supported by the terminal driver are not supported
by all DECnet terminal emulators.

The itemlist read function code and modifier combination takes the following
device- or function-dependent arguments:

P1The starting virtual address of the buffer that is to receive the data read.

Terminal Driver 531

Terminal Driver
5.4 Terminal Function Codes

P2The size of the buffer that is to receive the data read in bytes. If
required, the P2 size includes additional space for an overflow buffer to
hold an escape sequence terminator (see item code TRM$_ESCTRMOVR in
Table 58).
Note
The IO$_READxBLK and IO$_WRITExBLK are limited by the system
parameter MAXBUF as well as the terminal driver. The terminal driver
will only function with buffer sizes less than 32718 bytes.

P3The access mode at which the itemlist is to be probed (optional).

P5The address of the itemlist buffer.

P6The length in bytes of the itemlist buffer.

P4 is not meaningful for itemlist read operations. P5 points to a series of item

descriptors. Figure 54 shows the format for these descriptors. You cannot repeat
the same item code in the same item list.
Figure 54 Itemlist Read Descriptor
31

16 15
Item Code

0
Buffer Length

Buffer Address or Immediate Data

Return Address *
* Must be zero.
Itemlist Read P5 Buffer
ZK1305GE

Table 58 lists the item codes that can be specified in the first longword of the
item descriptors.
Table 58 Item Codes for Itemlist Read Operations for the Terminal Driver
Item Code

Meaning

TRM$_ALTECHSTR

Alternate echo string. The buffer length word contains the

length of the string. The data address word contains the
address of the string. The alternate echo string is written to
the terminal after the first character is entered.
This item code for character validating read mode (TRM$K_
EM_RDVERIFY) editing only.
(continued on next page)

532 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 58 (Cont.) Item Codes for Itemlist Read Operations for the Terminal
Driver
Item Code

Meaning

TRM$_EDITMODE

Extended editing modes. The immediate data longword

specifies extended editing mode values. The buffer length
word must be zero. The following editing modes are supported:

TRM$_ESCTRMOVR

TRM$K_EM_DEFAULT

Normal read mode. This

is the default if TRM$_
EDITMODE is not present
in the itemlist.

TRM$K_EM_RDVERIFY

Character validating read

mode. See Section 5.4.1.4.

Escape terminator overflow size. Specifies the number of bytes

that may be used to hold an escape sequence terminator. This
number should be included in P2, the buffer size argument, in
addition to the space required for the data to be read. Note
that this overflow area is for the terminator only; it is not
available for user data.
TRM$_ESCTRMOVR is useful in preventing partial escape
errors, which return SS$_PARTESCAPE. This overflow
buffer ensures that all the characters in an escape sequence
terminator will fit in the user buffer, thus eliminating the need
for additional single-character read operations.

TRM$_FILLCHR

A 2-byte value that indicates the fill and clear character for
TRM$K_EM_RDVERIFY. The first byte of the immediate data
longword specifies the clear character; the second byte specifies
the fill character.
This item code is for character validating read mode (TRM$K_
EM_RDVERIFY) editing only.

TRM$_INIOFFSET

Indicates the character in the initial string where echoing

starts. The immediate data longword specifies the character.

TRM$_INISTRNG

Specifies a string to preload into the read buffer (P1). The

buffer length word contains the length of the string. The
data longword contains the address of the string. TRM$_
INISTRNG must be specified if the edit mode is TRM$K_
EM_RDVERIFY, and must be the same length as specified by
TRM$_PICSTRNG.
(continued on next page)

Terminal Driver 533

Terminal Driver
5.4 Terminal Function Codes
Table 58 (Cont.) Item Codes for Itemlist Read Operations for the Terminal
Driver
Item Code

Meaning

TRM$_MODIFIERS

Read modifiers. The immediate data longword contains a 32bit value that specifies modifiers to read operations. The read
operations are defined in $TRMDEF. The buffer length word
must be zero. The following bits are defined:
TRM$M_TM_ARROWS

The terminal interprets the left

and right arrow keys (TRM$K_
EM_RDVERIFY mode only).
The arrow keys are not put in
the buffer and do not terminate
the read. TRM$_ESCTRMOVR
must be greater than or equal
to 5.

TRM$M_TM_AUTO_TAB

This bit creates an auto-tab

mode field (TRM$K_EM_
RDVERIFY mode only).

TRM$M_TM_CVTLOW

Lowercase alphabetic
characters (hexadecimal 61 to
7A) are converted to uppercase
when transferred to the user
buffer or echoed.

TRM$M_TM_DSABLMBX

The mailbox is disabled for

unsolicited data and for
receiving hangup messages.

TRM$M_TM_ESCAPE

A valid ANSI escape sequence is

recognized as a valid delimiter
for the read operation.
(continued on next page)

534 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 58 (Cont.) Item Codes for Itemlist Read Operations for the Terminal
Driver
Item Code

Meaning
TRM$M_TM_NOCLEAR

Fill characters are not replaced

with clear characters after
a nonfill character occurs
(TRM$K_EM_RDVERIFY mode
only).

TRM$M_TM_NOECHO

Characters are not displayed

as they are entered at the
keyboard.

TRM$M_TM_NOEDIT

This bit inhibits advanced

editing for this read operation.

TRM$M_TM_NOFILTR

The terminal does not interpret

DEL, Ctrl/U, or Ctrl/R, but
passes them to you. This
characteristic explicitly disables
line editing.

TRM$M_TM_NORECALL

This bit inhibits command

recall (Ctrl/B) by the terminal
driver.

TRM$M_TM_OTHERWAY

This bit sets left-justify fields to

insert mode and right-justify
fields to overstrike mode
(TRM$K_EM_RDVERIFY mode
only). TRM$M_TM_TOGGLE
must equal 1.

TRM$M_TM_PURGE

The type-ahead buffer is purged

before the read operation
begins.

TRM$M_TM_R_JUST

This bit creates a right-justified

field (TRM$K_EM_RDVERIFY
mode only).

TRM$M_TM_TERM_
ARROW

The read operation is

terminated when the left arrow
key is pressed at the left margin
or when the right arrow key is
pressed at the right margin
(TRM$K_EM_RDVERIFY mode
only). TRM$M_TM_ARROWS
must be enabled.

TRM$M_TM_TERM_DEL

The read operation is

terminated when the DELETE
key is pressed at the left margin
(TRM$K_EM_RDVERIFY mode
only).
(continued on next page)

Terminal Driver 535

Terminal Driver
5.4 Terminal Function Codes
Table 58 (Cont.) Item Codes for Itemlist Read Operations for the Terminal
Driver
Item Code

Meaning
TRM$M_TM_TOGGLE

Enables Ctrl/A to function as

a toggle key between insert
mode and overstrike mode
(TRM$K_EM_RDVERIFY mode
only). Left-justify insert mode
shifts characters to the right;
right-justify insert mode shifts
characters to the left. Shifted
characters are not checked for
validity in their new positions.

TRM$M_TM_TIMED

TRM$_TIMEOUT specifies the

maximum time (seconds) that
can elapse between characters
received from the terminal;
that is, the timeout value
for the operation. TRM$M_
TM_TIMED is assumed set if
TRM$_TIMEOUT is included in
the itemlist. See the description
of IO$M_TIMED in Table 57.

TRM$M_TM_
TRMNOECHO

The termination character (if

any) is not displayed. There
is no formal terminator if
the buffer is filled before the
terminator is typed.
All other bits must be zero.

TRM$_PICSTRNG

Character validation string. The buffer length word contains

the length of the string, which must be the same as the
length specified by TRM$_INISTRNG. The data address word
contains the address of the string. TRM$_PICSTRNG must be
specified if the edit mode is TRM$K_EM_RDVERIFY.
Note that this item code is for character validating read mode
(TRM$K_EM_RDVERIFY) editing only.
The format of the character validation string is 1 byte per
input character. Each byte is a bit mask. The following values
are provided:
Value

Meaning

TRM$M_CV_UPPER

Uppercase alphabetic

TRM$M_CV_LOWER

Lowercase alphabetic

TRM$M_CV_NUMERIC

Numeric (09)

TRM$M_CV_NUMPUNC

Numeric punctuation (+ - .)

TRM$M_CV_PRINTABLE

Printable ASCII character

TRM$M_CV_ANY

Any character

If no values are set, the corresponding character specified by

TRM$_INISTRNG is used. Appendix C lists the multinational
character set.
(continued on next page)

536 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 58 (Cont.) Item Codes for Itemlist Read Operations for the Terminal
Driver
Item Code

Meaning

TRM$_PROMPT

Specifies a prompt string. The buffer length word contains

the length of the prompt. The data address word contains the
address of the prompt string. See Section 5.4.1 for information
on how carriage control specifiers in a prompt string are
handled.

TRM$_TERM

The buffer length word determines the format of the

nondefault terminator mask. If the buffer length word is
zero, then the data longword is used as a short form mask. If
the buffer length word is nonzero, then a mask n bytes long is
available at the specified address.

TRM$_TIMEOUT

Read timeout. See the description of IO$M_TIMED in

Table 57.

5.4.1.4 Read Verify Function

When using the read verify function, the terminal driver performs input
validation based on character attributes. (Read verification bypasses the
optionally specified termination mask (TRM$_TERM).) Validation is performed
one character at a time as data is entered. Invalid characters are not echoed, and
cause the read operation to complete. It is then up to the application program to
handle the error appropriately.
The initial string describes the initial contents of the input field. This string may
consist of data and marker characters. The clear character is displayed on the
screen for each occurrence of the fill character in the initial string buffer.
The picture string is a string of bytes where each byte corresponds to one
character of the field being entered. Each byte specifies a mask of legal character
types for that character position. If the byte is left as zero, then that position is
a marker character, and the character from the initial string is echoed for that
position.
For left-justified fields, the prompt data is output to the terminal, followed by
an optional number (TRM$_INIOFFSET) of initial string characters. Leading
marker characters are always output following the prompt, leaving the cursor
at the leftmost data position. As each character is entered, it is validated and
then echoed, advancing the cursor position. Additional marker characters are
skipped as they are encountered. If an input character fails the validation, the
read operation is completed with the invalid character as the terminator.
For right-justified fields, the prompt is output and is followed by the initial string.
(In general, TRM$_INIOFFSET is set to the length of TRM$_INISTRNG for
right-justified fields.) The cursor position remains one position to the right of
the initial string. For proper operation, right-justified fields cannot have mixed
picture definitions. After each character is input, the entire prompt and input
fields are output. Therefore, the prompt should include a cursor positioning
escape sequence.
The definition of full field is different for left- and right-justified read operations.
For left-justified fields, full field is detected when the character corresponding to
the last nonmarker position in the picture string has been entered. For rightjustified fields, full field is detected when a character other than the fill character
is shifted into the leftmost, nonmarker position in the field.

Terminal Driver 537

Terminal Driver
5.4 Terminal Function Codes
If the modifier TRM$M_TM_AUTO_TAB is set in TRM$_MODIFIERS, then
detection of a full field terminates the read operation. In the event of autotab
termination, the terminator character in the IOSB is null. If the autotab option
is not selected, then termination occurs when one more character is typed to a
full field. Applications can detect this condition when the terminating character
index is one character beyond the end of the field. The extra character is reported
as the terminator. In a left-justified field, the IOSB index to the terminator is
zero-based; in a right-justified field, this index is one-based.
If a read verify function is interrupted by an asynchronous write operation, the
read verify is completed with status SS$_OPINCOMPL.
No line editing functions other than the delete character function are supported
for read verify.

5.4.2 Write
Write operations display the contents of a user-specified buffer on the associated
terminal. The operating system provides the following write I/O functions, which
are listed with their function codes:

IO$_WRITEVBLKWrite virtual block

IO$_WRITELBLKWrite logical block

IO$_WRITEPBLKWrite physical block

The write function codes can take the following device- or function-dependent
arguments:

P1The starting virtual address of the buffer that is to be written to the

terminal.

P2The number of bytes that are to be written to the terminal. (The system
generation parameter, MAXBUF, and the terminal driver limit the maximum
size of the buffer. The terminal driver will only function with buffer sizes less
than 32718 bytes.)

P4Carriage control specifier except for write physical block operations.

(Write function carriage control is described in Section 5.4.2.2.)

P3, P5, and P6 are not meaningful for terminal write operations.
In write virtual block and write logical block operations, the buffer (P1 and P2) is
formatted for the selected terminal and includes the carriage control information
specified by P4.
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 occur every eight characters or positions.
CTDRIVER and Buffered Output
CTDRIVER, a component of the SET HOST facility, buffers output from remote
terminals in order to package multiple output requests into a single network
transfer. As a result, control is returned early to the user with a status of SS$_
NORMAL when the output buffer has been filled and successfully queued.

538 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Note that this output might not be displayed if the user enters an abort character
or a Ctrl/O.
5.4.2.1 Function Modifier Codes for Write QIO Functions
Five function modifiers can be specified with IO$_WRITEVBLK, IO$_
WRITELBLK, and IO$_WRITEPBLK. Table 59 lists these function modifiers.
All write function modifiers are supported for LAT devices.
Table 59 Write QIO Function Modifiers for the Terminal Driver
Code

Consequence

IO$M_BREAKTHRU

Allows breakthrough read regardless of the current active

state.

IO$M_CANCTRLO

Turns off Ctrl/O (if it is in effect) before the write operation.

Otherwise, the data cannot 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 you to specify write functions without interpretation or

format; in effect, the terminal line is in a temporary PASTHRU
mode.

IO$M_REFRESH

If a read operation is interrupted by a write operation (by

either a write breakthrough1 or any other type of write), the
terminal displays the current read data when the read function
is restarted.

1 Any interruption caused by the execution of the $BRDCST or the $BRKTHRU system service
broadcasting messages to terminals is referred to as a write breakthrough.

5.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 55 shows the P4 longword format.
Figure 55 P4 Carriage Control Specifier

P4:

POSTFIX

PREFIX

(Not Used)

FORTRAN
ZK0690GE

Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If the loworder byte (byte 0) is not 0, the contents of the longword are interpreted as a
Fortran carriage control specifier. Table 510 lists the possible byte 0 values (in
hexadecimal) and their meanings.

Terminal Driver 539

Terminal Driver
5.4 Terminal Function Codes
Table 510 Write Function Carriage Control (FORTRAN: Byte 0 Not Equal to 0)
Byte 0 Value
(hexadecimal)

ASCII
Character

20

(space)

Single-space carriage control (sequence:

carriage-return/line-feed combination, print
buffer contents, return1 ).

30

Double-space carriage control (sequence:

carriage-return/line-feed combination, carriagereturn/line-feed combination, print buffer
contents, return1 ).

31

Page eject carriage control (sequence: form feed,

print buffer contents, return).

2B

Overprint carriage control; allows double

printing for emphasis or special effects
(sequence: print buffer contents, return).

24

Prompt carriage control (sequence: carriagereturn/line-feed combination, print buffer

contents).

All other
values
1A

Meaning

Same as ASCII space character:

single-space carriage control.

carriage-return/line-feed combination is a carriage return followed by a line feed.

If the low-order byte (byte 0) is 0, 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 as follows:
1. Prefix carriage control
2. Print
3. Postfix carriage control
The prefix and postfix bytes, although interpreted separately, use the same
encoding scheme. Table 511 shows this encoding scheme in hexadecimal.
With several exceptions, Figure 56 shows the prefix and postfix hexadecimal
coding that produces the carriage control functions listed in Table 510. Prefix
and postfix coding provides an alternative way to achieve these controls.
In the first example in Figure 56, the prefix/postfix hexadecimal coding for a
single-space carriage control (carriage-return/line-feed combination, 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.
80 (bit 7 = 1)
+ D (return)
---8D (postfix = return)

540 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 511 Write Function Carriage Control (P4 byte 0 = 0)
Prefix/Postfix Bytes (Hexadecimal)
Bit 7

Bits 06

Meaning

No carriage control is specified (NULL).

17F

Bits 0 through 6 are a count of carriagereturn/line-feed combinations.

Bit 7

Bit 6

Bit 5

Bits 04

Meaning

01F

Output the single ASCII control

character specified by the configuration
of bits 0 through 4 (7-bit character set).

01F

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; see Appendix C).

01F

Reserved.

5.4.3 Set Mode

Set mode operations affect the operation and characteristics of the associated
terminal line. The operating system provides two types of set mode functions: set
mode and 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. (If you do not have LOG_IO or PHY_IO privilege, the terminal driver
does not accept a set mode request to a terminal that does not have the extended
terminal characteristic TT2$M_SETSPEEDeven if no request for a change
of speed is made. Privilege is not required if TT2$M_SETSPEED is set but no
attempt to change the speed is made.) The following function code is provided:
IO$_SETMODE
The set characteristics function 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. The following function
code is provided:
IO$_SETCHAR
The set mode and set characteristics functions take the following device- or
function-dependent arguments if no function modifiers are specified:

P1Address of characteristics buffer

P2Length of characteristics buffer (default length is 8 bytes)

P3Speed specifier (bits 0 through 7 = transmit; 8 through 15 = receive)

P4Fill specifier (bits 0 through 7 = CR fill count; bits 8 through 15 = LF fill

count)

Terminal Driver 541

Terminal Driver
5.4 Terminal Function Codes
Figure 56 Write Function Carriage Control (Prefix and Postfix Coding)
(Space)
P4:

8D

Sequence:
1

Sequence:

"0"
P4:

8D

8D

8C

8D

8D

18

Prefix = NL
Print
Postfix = NULL
Sequence:

Example: Skip 24 lines before printing.

P4:

Prefix = NULL
Print
Postfix = CR
Sequence:

"$"
P4:

Prefix = FF
Print
Postfix = CR
Sequence:

"+"
P4:

Prefix = NL, NL
Print
Postfix = CR
Sequence:

"1"
P4:

Prefix = NL
Print
Postfix = CR

Prefix = 24NL
Print
Postfix = CR
ZK0665GE

P5Parity flags

The P1 argument points to a variable-length block, as shown in Figure 57. With

the exception of terminal characteristics, the contents of the block are the same
for both the set mode and set characteristics functions.
In the buffer, the device class is DC$_TERM, which is defined by the $DCDEF
macro. The terminal type is defined by the $TTDEF macro; for example, TT$_
LA36. The page width is a value in the range of 1 through 511. The page
length is a value in the range of 0 through 255. Table 55 lists the values for
terminal characteristics. Table 56 lists the extended terminal characteristics.
Characteristics values are defined by the $TTDEF and $TT2DEF macros.

542 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Figure 57 Set Mode and Set Characteristics Buffers
31

24 23

16 15

Page Width
Page Length

8 7
Type

0
Class

Basic Terminal Characteristics

P2 = 8 (Default)
31

24 23

16 15
Type

Page Width
Page Length

8 7

0
Class

Basic Terminal Characteristics

Extended Terminal Characteristics

P2 = 12
ZK0691GE

Note
Make sure that the selected device is a terminal before performing any set
mode function, particularly when using SYS$INPUT or SYS$OUTPUT.

The P3 argument defines the device speed, such as TT$C_BAUD_300. The low
eight bits specify the transmit speed, and the high eight bits specify the receive
speed. If no receive speed is specified, the indicated transmit speed is used for
both transmitting and receiving. If neither the transmit nor the receive speed is
specified (P3 = 0), the baud rate is not changed. The terminal driver ignores the
receive speed bits for interfaces that do not support split-speed operation. While
speeds up to 19.2 K baud can be specified, not all controllers support all speed
combinations. Refer to the associated hardware documentation to determine
which speeds are supported by your controller.
P4 contains fill counts for the carriage-return and line-feed characters. Bits 0
through 7 specify the number of fill characters used after a carriage return. Bits
8 through 15 specify the number of fill characters used after a line feed.
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 55.
Several parity flags can be specified in the P5 argument:

TT$M_ALTRPARAlter parity. If set, check the state of TT$M_PARITY and

TT$M_ODD and, if indicated, change the parity. Otherwise, ignore these bits.

TT$M_PARITYEnable parity on terminal line if set, disable if clear.

TT$M_ODDParity is odd if set.

TT$M_ALTDISPARAlter dismiss parity errors. If set, check the state of

TT$M_DISPARERR.

Terminal Driver 543

Terminal Driver
5.4 Terminal Function Codes

TT$M_DISPARERRDismiss parity errors. If this mode is set, a character

with a parity error is passed to the reader. An error message is not reported.
Note
If parity is enabled, the DZ11 generates a parity check bit to detect parity
mismatch. Unless TT$M_DISPARERR is enabled, parity errors that occur
during an I/O read operation are fatal to the operation. Parity errors that
occur on input characters (that is, keys pressed on the keyboard) when no
I/O operation is in progress might result in a character loss.

TT$M_BREAKGenerate a break if set. The break is in effect until this bit

is turned off. TT$M_BREAK is supported by the LTDRIVER for terminal
servers that support the break capability, such as the DECserver 200 and
DECserver 500. However, in the case of LAT terminals, the terminal server
controls the duration of the break.

TT$M_ALTFRAMEIf set, the four low-order bits of P5 become the frame

size. Note that the frame size is for data bits only and is exclusive of parity.
TT$M_ALTFRAME is supported for frame sizes of 7 and 8 for LAT devices.

To take the existing parity settings, modify them, and use them in the set mode
or set characteristic function, move the byte starting at the second nibble of the
buffer that is going to be used in the P5 argument. For example, the following
instructions change the parity from even to odd:
insv
bisl

iosb+6, #4, #8, flags

#tt$m_altrpar!tt$m_odd!tt$m_parity, flags

The following instruction then resets the parity to its original state:
bicl

#tt$m_odd!tt$m_parity, flags

See Section 5.2.5 for information about the SET TERMINAL/FRAME command.
Application programs that change terminal characteristics should perform the
following steps:
1. Use the IO$_SENSEMODE function to read the current characteristics.
2. Modify the characteristics.
3. Use the set mode function to write back the results.
4. If the characteristic is intended to be reset when the image exits, the
application must perform this operation.
Failure to follow this sequence will result in clearing any previously set
characteristic.
Two stop bits are used only for data rates less than or equal to 150 baud; higher
data rates default to one stop bit.
The set mode and set characteristics functions can take the enable Ctrl/C AST,
enable Ctrl/Y AST, enable out-of-band AST, hangup, set modem, broadcast, and
loopback function modifiers that are described in the following sections.

544 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Note
If an attempt is made to turn on TT2$V_FALLBACK for a disconnected
virtual terminal (_VTAx:) or if the Terminal Fallback facility has not been
activated, the status code SS$_BADPARAM will be returned. For more
information on TFF, refer to the OpenVMS Terminal Fallback Utility
Manual (available on the Documentation CD-ROM).

5.4.3.1 Hangup Function Modifier

The hangup function disconnects a terminal that is on a dialup line. (Dialup lines
are described in Section 5.2.3.) The following combinations of function code and
modifier are provided:

IO$_SETMODE!IO$M_HANGUP

IO$_SETCHAR!IO$M_HANGUP

The hangup function modifier takes no arguments. SS$_NORMAL is returned in

the I/O status block.
Note
For remote terminals, the hangup function breaks the network connection
to the local system, ending the remote terminal session.

5.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 you press Ctrl/C or Ctrl/Y. The following
combinations of function code and modifier are provided:

IO$_SETMODE!IO$M_CTRLCASTEnable Ctrl/C AST

IO$_SETMODE!IO$M_CTRLYASTEnable Ctrl/Y AST

These function code modifier pairs take the following device- or functiondependent arguments:
P1Address of the AST service or 0 if the corresponding AST is disabled
P2AST parameter
P3Access mode to deliver AST (maximized with callers access mode)
If the respective enabling is in effect, pressing Ctrl/C or Ctrl/Y gains the attention
of the enabling process (see Table 52).
Enable Ctrl/C and Ctrl/Y AST are one-time enabling function modifiers. After
the AST occurs, it must be explicitly reenabled by one of the two function code
combinations before an AST can occur again. This function code is also used to
disable the AST. The function is subject to AST quotas.
You can have more than one Ctrl/C or Ctrl/Y enabled; pressing Ctrl/C, for
example, results in the delivery of all Ctrl/C ASTs. ASTs are queued and
delivered to the user process on a first-in/first-out basis for each access mode.
However, ASTs are processed in the reverse order of the Ctrl/C AST or Ctrl/Y
AST requests that have been issued to the terminal driver (on a last-in/first-out
basis).

Terminal Driver 545

Terminal Driver
5.4 Terminal Function Codes
If no enable Ctrl/C AST is present, the holder of an enable Ctrl/Y AST receives
an AST when Ctrl/C is pressed; carriage-return/line-feed combination, ^Y, and
Return are echoed.
Figure 58 shows the relationship of Ctrl/C and Ctrl/Y with the out-of-band
function. If Ctrl/C or Ctrl/Y is an enabled out-of-band character, any out-of-band
ASTs specified for this character are delivered. If IO$M_INCLUDE function
modifier is included in the out-of-band AST request for this character, an enabled
Ctrl/C or Ctrl/Y AST is also delivered.
Enable Ctrl/C AST requests are flushed by the Cancel I/O on the Channel
($CANCEL) system service. Enable Ctrl/Y AST requests are flushed by the
Deassign I/O Channel ($DASSGN) system service.
Ctrl/Y is normally used to gain the attention of the command interpreter and
to input special commands such as DEBUG, STOP, and CONTINUE. Programs
that are run from a command interpreter should not enable Ctrl/Y. Because ASTs
are delivered on a first-in/first-out basis, the command interpreters AST routine
gets control first, and might not allow the programs AST to be delivered at all.
Programs that require the use of Ctrl/Y should use the LIB$DISABLE_CTRL
RTL routine to disable DCL recognition of Ctrl/Y.
See Example 54 for a programming example that demonstrates Ctrl/Y and
Ctrl/C handling under OpenVMS.
Section 5.2.1.2 describes other effects of Ctrl/C and Ctrl/Y.
5.4.3.3 Set Modem Function Modifier
The set modem function modifier is used in maintenance operations to allow a
process to activate and deactivate modem control signals. Both set mode and set
characteristics functions can take the set modem function modifier. The following
combinations of function code and modifier are provided:

IO$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT

IO$_SETCHAR!IO$M_SET_MODEM!IO$M_MAINT
Note
For LAT devices, the set modem field for maintenance operations of the
IO$M_SET_MODEM!IO$M_MAINT function modifier is unsupported and
may return unpredictable results.

These function code modifier pairs take the following device- or functiondependent argument:
P1The address of a quadword block that specifies which modem control
signals to activate or deactivate
Figure 59 shows the format of this block.

546 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Figure 58 Relationship of Out-of-Band Function with Control Characters
Character Typed
on Keyboard

Deliver
outofband
AST.

If TT$M_EIGHTBIT
not set, strip bit 7
of character.

Yes

CTRL/S
or
CTRL/Q
?

No

Automatically
reenable
AST.

Is
TT2$M_PASTHRU
set?
IO$M_INCLUDE
set for this
character in any
outofband
AST?

No
Is this
an enabled
outofband
character
?

Yes

Yes

No

Yes

Done

No
CTRL/C

CTRL/Y

Control/C
enabled
?

CTRL/O

No

CTRL/S

CTRL/Q

CTRL/X

Other

Discard output/
continue
output.

Flush
typeahead
buffer.

Done

Done

Yes

Control/Y
enabled
?
Is
TT$M_TTSYNC
set
?

No

Deliver
Control/C
AST.

Deliver
Control/Y
AST.

OneShot

OneShot

Done

Done

Yes

Yes

No

Is
TT$M_TTSYNC
set
?
No

Stop output
stream.

Resume
output
stream.

Done

Done

Put character
in typeahead
buffer.
ZK1202GE

The modem on and modem off fields, in combination or separately, can specify one
or more of the following values:

TT$M_DS_RTSRequest to send (RTS)

TT$M_DS_DTRData terminal ready (DTR)

Terminal Driver 547

Terminal Driver
5.4 Terminal Function Codes
Figure 59 Set Mode P1 Block
31

24 23
Modem Off

16 15

8 7

Modem On

ZK0692GE

TT$M_DS_SECTXTransmitted backward channel data (Sec Txd)

The $TTDEF macro defines the values for these values. These values can only be
specified if the terminal characteristic TT$M_MODEM is not set. Otherwise, an
error (SS$_ABORT) will result.
Notes
The set modem function is not supported for remote terminals. The status
SS$_DEVREQERR is returned in the I/O status block.
Because the DMF32 does not provide the secondary transmitted data
signal (Sec Txd), the driver sets the secondary request to send the signal.
Users should connect a jumper cable between pins 14 and 19 on the
DMF32.

5.4.3.4 Loopback Function Modifier

The loopback function modifier is used in maintenance operations to place the
terminal line in a hardware loopback mode. Data transmitted to a line in this
mode is returned as receive data. If the controller does not support loopback
mode or the terminal line has the TT$M_MODEM characteristic set, an error
status (SS$_ABORT) is returned. Both set mode functions can take the loopback
function modifier.
Note
The loopback function is not supported for remote terminals. The status
SS$_DEVREQERR is returned in the I/O status block.

The following combinations of function code and modifier are provided:

IO$_SETMODE!IO$M_LOOP!IO$M_MAINT

IO$_SETCHAR!IO$M_LOOP!IO$M_MAINT

Data transmitted in the loopback mode should only be written in records less
than or equal to the size of the type-ahead buffer (see Section 5.2.1.5). Programs
that use the loopback function modifier should incorporate a 1-second delay to
allow the controller to enable the loopback mode after the request is posted. Write
requests should also include the IO$M_NOFORMAT function modifier to prevent
terminal driver from formatting input or output data.
Note
The serial line interfaces for the VAX 8200 processor implement an
internal loopback bus that is common to all four serial lines. The

548 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
hardware allows all serial lines operating in loopback mode to transmit
data to the bus at the same time. If more than one serial line writes data
to the bus, all of the transmitted data is combined and made available
to the receiving end of those same serial lines. Therefore, the received
data may be different from the transmitted data if more than one serial
line is operating in loopback mode at the same time. To prevent receiving
such spurious data, you must not operate multiple serial lines in loopback
mode.

The operating system provides another function modifier to reset a terminal line
previously placed in loopback mode. The following combinations of function code
and modifier are provided:

IO$_SETMODE!IO$M_UNLOOP!IO$M_MAINT

IO$_SETCHAR!IO$M_UNLOOP!IO$M_MAINT

Programs that use the unloop function modifier should incorporate a 1-second
delay to allow the controller to reset the loopback mode after the request is
posted.
Note
IO$M_LOOP and IO$M_UNLOOP are not supported for LAT devices.

5.4.3.5 Enable Out-of-Band AST Function Modifier

The enable out-of-band AST function modifier requests that the terminal
driver queue an AST for the requesting process when you enter any one of 32
control characters. The following combinations of function code and modifier are
provided:

IO$_SETMODE!IO$M_OUTBANDEnable out-of-band AST

IO$_SETCHAR!IO$M_OUTBANDEnable out-of-band AST

These function code modifier pairs take the following device- or functiondependent arguments:

P1Address of the AST service or 0 if the AST entered on this channel is to

be canceled. (The AST parameter will be the out-of-band character.)

P2Address of a character mask with the same format as the short form
terminator mask (see Section 5.4.1.2).

P3Access mode to deliver AST (maximized with the callers access mode).

The IO$_SETMODE!IO$M_OUTBAND function can optionally take the following

function modifiers:

IO$M_INCLUDEInclude the character typed in the data stream.

IO$M_TT_ABORTAllow current read and write operations to be aborted.

(The IOSB for aborted operations returns the status SS$_CONTROLC.)

If an out-of-band AST is in effect, pressing any control character specified in

the P2 mask gains the attention of the enabling process. Figure 58 shows the
relationship of the out-of-band function with some of the control characters.
You can have only one out-of-band AST enabled per channel.

Terminal Driver 549

Terminal Driver
5.4 Terminal Function Codes
Out-of-band ASTs are repeating ASTs; they continue to be delivered until
specifically disabled. Out-of-band AST enables are flushed by the Cancel I/O
on Channel ($CANCEL) system service.
5.4.3.6 Broadcast Function Modifier
The broadcast function modifier allows you to turn on or turn off selected
broadcast requester identifiers (IDs). The following combination of function
code and modifier is provided:
IO$_SETMODE!IO$M_BRDCST
This function code modifier pair takes the following device- or function-dependent
arguments:

P1A buffer that contains the bits that specify the requester IDs to be
broadcast

P2The length of the P1 buffer (default is 8 bytes)

The first longword of P1 is reserved for use by Compaq facilities, as shown in

Table 512. The symbols are defined in the system macro library ($BRKDEF).
The second longword is for customer use to specify selected bits. If any bit is set
in the P1 buffer, that particular requester ID is turned off for broadcast.
Table 512 Broadcast Requester IDs
Bit

Meaning

BRK$C_DCL

Disables broadcasts by Ctrl/T

BRK$C_GENERAL

Disables broadcasts by the DCL command REPLY and the

SYS$BRDCST system service

BRK$C_MAIL

Disables broadcasts by the Mail utility

BRK$C_PHONE

Disables broadcasts by the Phone utility

BRC$C_QUEUE

Disables broadcasts about batch and print queues

BRK$C_SHUTDOWN

Disables broadcasts about system shutdown

BRK$C_URGENT

Disables broadcasts labeled URGENT by the REPLY command

BRK$C_USERn

Disables broadcasts by images associated with the specified

value; n can be any decimal integer between 1 and 16

5.4.4 LAT Port Driver QIO Interface

The LAT port driver (LTDRIVER) accommodates I/O requests from application
programs for connections to remote devices on one or more terminal servers; for
connections to remote services; and for configuring LTDRIVER and retrieving
configuration information about LTDRIVER. A remote device, such as a printer,
can be shared in a LAT configuration. Before an application program can access
a remote device, the system manager must create logical devices and map them
to physical devices connected to terminal servers. Creating and mapping these
logical devices can be done either with the LAT Control Program (LATCP) utility
or with a $QIO request from a program that has OPER privilege. Once mapped,
application programs can establish and terminate connections to these remote
devices.

550 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
This section describes the capabilities of the QIO interface to the LAT port driver
(LTDRIVER). The QIO interface allows application programs to access and modify
information contained in the LTDRIVER data structures and to initiate events
and obtain status information. You must use these QIO functions to establish a
connection to a remote device or service from an application program. Compaq
does not support any other methods of connection.
The LTDRIVER responds to TEST SERVICE commands issued at terminal
servers that support the TEST SERVICE command, such as the DECserver 200
and DECserver 500 servers.
LAT devices can use all read and write function modifiers listed for the terminal
driver function codes except those modifiers that apply to modems (see Sections
5.4.1 and 5.4.2).
The operating system does not support the following set mode or set
characteristics function code modifiers for LAT devices:

IO$M_LOOP

IO$M_UNLOOP

TT$M_ALTRPAR

TT$M_ALTFRAME

TT$M_MODEM

TT$M_READSYNC

TT2$M_SETSPEED

With LAT devices, the terminal server, rather than the host, handles flow control
to the physical device. A separate flow control mechanism exists between the
server and the host.
5.4.4.1 LAT Port Types
QIO functions can be used to create the following LAT port types:

Application Port. This type of port can be used to connect to a remote device
(typically a printer) on a terminal server or to a dedicated port on another
LAT service node. This is the default port type. See Section 5.4.4.5 for a
description of programming an application port.

Dedicated Port. This type of port specifies that the logical port on your node
is dedicated to an application service. When users on a terminal server (or on
another node that supports outgoing connections) request a connection to this
service name, they are connected to a dedicated port. See Section 5.4.4.6 for a
description of programming a dedicated port and application service.

Forward Port. This type of port is used for outgoing LAT connections (to
remote services) and is created by assigning a channel to the LAT template
device _LTA0: with the $ASSIGN system service.
QIO functions can also be used to configure and read information about these
ports; for more information:

See Section 5.4.4.3 for a description of configuring a LAT port

See Section 5.4.4.4 for a description of reading configuration information

about a LAT port

Terminal Driver 551

Terminal Driver
5.4 Terminal Function Codes

See Section 5.4.4.7 for a description of programming a forward port in

order to make a connection to a LAT service

5.4.4.2 LAT Port Driver Functions

The operating system provides the following combinations of function code and
modifier:

IO$_TTY_PORT!IO$M_LT_CONNECT. Requests that the LAT port driver

make a connection to a remote device on a server (or dedicated port on
another LAT service node) or to a remote service, depending on whether the
port is an application port or a forward port respectively. For dedicated ports,
this QIO completes when an incoming connection to the port is established.
See Section 5.4.4.5 for a description of programming an application port,
Section 5.4.4.6 for a description of programming a dedicated port, and
Section 5.4.4.7 for a description of programming a forward port.

IO$_TTY_PORT!IO$M_LT_DISCON. Depending on the port type, requests

that the LAT port driver terminate the LAT connection to the remote device,
service, or local application service. IO$M_FLUSH_DATA can be specified
in the P2 argument to IO$M_LT_DISCON. The flush flag indicates that any
data not delivered to the remote device is to be flushed when the disconnect is
issued.

IO$_TTY_PORT!IO$M_LT_SETMODE. Requests that the LAT port driver

create or configure a LAT entity. See Section 5.4.4.3 for more information.

IO$_TTY_PORT!IO$M_LT_SENSEMODE. Requests that the LAT port driver

return configuration information about a LAT entity. See Section 5.4.4.4 for
more information.

5.4.4.3 Creating and Configuring LAT Entities

The LAT SETMODE $QIO function (IO$_TTY_PORT!IO$M_LT_SETMODE) is
used to create, delete, and modify LAT nodes, services, ports, and links.
Creation, deletion, or modification of any entity requires the OPER privilege.
The LAT SETMODE $QIO function accepts four arguments: P1, P2, P3, and P4.
P1 is the address of an item list; P2 is the length of this item list.
P3 specifies the type of entity to which the SETMODE operation applies. The
entity type can be one of five types:

Node (LAT$C_ENT_NODE). Only the local node name may be specified, with
the exception of a SETMODE itemlist containing no item codes other than
LAT$_ITM_COUNTERS.

Service (LAT$C_ENT_SERVICE). Only local service names may be specified,

with the exception of a SETMODE itemlist containing no item codes other
than LAT$_ITM_COUNTERS.

Link (LAT$C_ENT_LINK). The data link associated with the LAN.

Port (LAT$C_ENT_PORT).

Queue Entry (LAT$C_ENT_QUEUE_ENTRY). Indicates queue entry entities.

When this entity is used, the only valid SETMODE operation is delete.

552 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
The value for the entity type occupies the low-order 16 bits (bits 015) of the
P3 parameter. For all four entity types, bits 1619 are used as a status field to
indicate the expected current status of the entity. These bits are used to decide
whether the entity needs to be created before its characteristics are set. The
possible values for this field are:

LAT$C_ENTS_OLDThe entity must already exist. An SS$_NOSUCHDEV

error is returned if the entity does not exist.

LAT$C_ENTS_NEWThe entity must be created. An SS$_DUPLNAM error

is returned if the entity already exists.

LAT$C_ENTS_UNKIf the entity does not exist, it is created. If it does exist,

its characteristics are modified.

LAT$C_ENTS_DELIf the entity exists, delete it. Otherwise, an SS$_

NOSUCHDEV error is returned and the item list is not used.

P4 may contain the address of an entity name string descriptor. If this parameter
is omitted (contains a 0 or the address of a descriptor that points to an empty
buffer), a default may be used in some cases. The defaults for each entity type
are as follows:

LAT$C_ENT_NODEThe local node.

LAT$C_ENT_SERVICENo default; you must specify the service name.

LAT$C_ENT_LINKThe string LAT$LINK.

LAT$C_ENT_PORTThe device name associated with the currently assigned

channel (the CHAN parameter of the $QIO function).

SETMODE can return the following status codes:

SS$_NOPRIVNo privilege to complete the desired operation.

SS$_ACCVIOPart of the argument list or itemlist is not addressable.

SS$_BADPARAMOne of the parameters in the itemlist is in error. If this

value is returned, the second longword of the IOSB contains the item code of
the parameter in error.

SETMODE Item Codes

Each item in the itemlist consists of a one-word (16-bit) item code, followed by a
value associated with the item.
Item codes in which the bit named LAT$V_STRING is zero take a longword
value. The associated value is contained in the longword immediately following
the item code in the itemlist. Item codes in which this bit is 1 take a counted
string for their value. The byte immediately following the item code contains a
byte count, which describes the length of the string that immediately follows it.
If you set bit LAT$V_CLEAR in the item code to 1, the current value associated
with the item code is cleared or set to its default value. In this case, the actual
value specified in the itemlist is ignored, although the byte count field skips to
the next item in the itemlist.
Figure 510 shows an example of a SETMODE itemlist.

Terminal Driver 553

Terminal Driver
5.4 Terminal Function Codes
Figure 510 Example SETMODE Itemlist
31

16 15

LAT$C_ON

LAT$_ITM_STATE

LAT$_ITM_KEEPALIVE_TIMER
40
L

LAT$_ITM_IDENTIFICATION

11

T
S
LAT$_ITM_CIRCUIT_TIMER

160
LAT$C_ENABLED

LAT$_ITM_SERVER_MODE

LAT$_ITM_USER_GROUPS
13

LAT$_OUTGOING_SES_LIMIT

5
ZK3798A

This SETMODE itemlist is the P1 parameter for a $QIO SETMODE function on

the local node. P4 is omitted, and P3 is #LAT$C_ENT_NODE!<LAT$C_ENTS_
OLD@16>. P2 is the length of the itemlist (52). A $QIO SETMODE function for
this itemlist would perform the following operations:
1. Set the state of the node to on.
2. Set the LAT keepalive timer to 40 seconds.
3. Set the node identification to LTC CLUSTER.
4. Set the LAT circuit timer to 160 milliseconds.
5. Enable LAT outbound connections.
6. Turn on user groups 2, 8, 10, 11, 12, 16, and 19. LAT$_ITM_USER_GROUPS
is represented by a bit field.
7. Set the outgoing session limit to five sessions.
For each entity type, only a subset of item codes may be set. Table 513 lists the
item codes that may be set for the LAT$C_ENT_NODE entity type.

554 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 513 LAT$C_ENT_NODE Item Codes
Item Code

Meaning

LAT$_ITM_STATE

Operating state of the LAT protocol. The following values are allowed:
LAT$C_OFF

Turns off LAT protocol processing. No new

connections allowed in either direction. Existing
connections are terminated immediately. This is the
default.

LAT$C_SHUT

Disallows new LAT connections in either direction.

Existing connections are allowed to remain active.

LAT$C_ON

Turns on LAT protocol processing.

LAT$_ITM_CIRCUIT_
TIMER

Circuit timer value in milliseconds. Valid values are 10 to 1000 milliseconds.

The default is 80 milliseconds.

LAT$_ITM_CPU_RATING

CPU rating. Valid values are 0 to 100. If this value is 0, then the CPU
rating value is not used in the rating calculation. Refer to the OpenVMS
System Management Utilities Reference Manual for a complete description of
this feature.

LAT$_ITM_DEVICE_SEED

Overrides the default lower boundary for new LTA devices. Valid values
are 0 to 9999; the default is 0. Refer to the OpenVMS System Management
Utilities Reference Manual for more information on this feature.

LAT$_ITM_KEEPALIVE_
TIMER

Keepalive timer value in seconds. Valid values are 10 to 255 seconds. The
default is 20 seconds.

LAT$_ITM_MULTICAST_
TIMER

Multicast timer value in seconds. Valid values are 10 to 180 seconds. The
default is 60 seconds.

LAT$_ITM_NODE_LIMIT

Maximum number of nodes in LAT database. The default is 0, where the

maximum is determined by system resources.

LAT$_ITM_RETRANSMIT_
LIMIT

LAT retransmit limit. Valid values are 4 to 120 retransmissions. The default
is 8 retransmissions.

LAT$_ITM_SERVER_
MODE

Controls whether the node allows the use of the MASTER side of the LAT
protocol for outbound connections. Valid values are:

LAT$_ITM_SERVICE_
RESPONDER

LAT$C_DISABLED

Server mode disabled (this is the default).

LAT$C_ENABLED

Server mode enabled.

Indicates whether the node is to respond to service inquiries originating from

a remote system. These inquiries are not necessarily directed at services
being offered by the node. Refer to the OpenVMS System Management
Utilities Reference Manual for a complete description of this feature. Valid
values are:
LAT$C_DISABLED

Service responder disabled (this is the default).

LAT$C_ENABLED

Service responder enabled.

LAT$_ITM_OUTGOING_
SES_LIMIT

Maximum number of outgoing LAT sessions. A value of 0, which is the

default, indicates that the limit is determined by system resources.

LAT$_ITM_INCOMING_
SES_LIMIT

Maximum number of interactive LAT sessions. A value of 0, which is the

default, indicates that the limit is determined by system resources.

LAT$_ITM_
CONNECTIONS

Controls whether inbound connections can be accepted. Valid values are:

LAT$_ITM_NODE_NAME

LAT$C_DISABLED

Inbound connections disabled.

LAT$C_ENABLED

Inbound connections enabled (this is the default).

Causes the LAT node name to be set to the given name. This item code may
be specified only if the entity status field of the P3 parameter is LAT$C_
ENTS_NEW; otherwise, a LAT$_ENTNOTFOU error results.
(continued on next page)

Terminal Driver 555

Terminal Driver
5.4 Terminal Function Codes
Table 513 (Cont.) LAT$C_ENT_NODE Item Codes
Item Code

Meaning

LAT$_ITM_
IDENTIFICATION

Node identification string. The default is the translation of

SYS$ANNOUNCE.

LAT$_ITM_SERVICE_
GROUPS

Specifies a default service group code bit mask. This mask is then used
when creating new local services. The default is group code 0 enabled and
all others disabled when the LAT software is initialized.
Note that the use of the LAT$V_CLEAR bit is an exception for this
parameter code. If you clear bit LAT$V_CLEAR, group codes corresponding
to the group code mask, as specified in the itemlist, are set. Alternatively, if
you set LAT$V_CLEAR, group codes corresponding to the group code mask,
as specified in the itemlist, are cleared.

LAT$_ITM_USER_
GROUPS

LAT group codes to be used when attempting outbound connections using the
MASTER side of the LAT protocol. The default is all group codes disabled
when the LAT software is initialized.
Note that the use of the LAT$V_CLEAR bit is an exception for this
parameter code. If you clear bit LAT$V_CLEAR, group codes corresponding
to the group code mask, as specified in the itemlist, are set. Alternatively, if
you set LAT$V_CLEAR, group codes corresponding to the group code mask,
as specified in the itemlist, are cleared.

LAT$_ITM_COUNTERS

Node counters block. Allows for zeroing of all node counters. This item
code may be specified only if the entity status field of the P3 parameter is
LAT$C_ENTS_OLD and the LAT$V_CLEAR bit is set. Violating either of
these two rules results in a returned status of SS$_BADPARAM.

LAT$_ITM_MAXIMUM_
UNITS

Maximum unit number. Sets the highest value for a LTA unit number. Must
be between 1 and 9999; defaults to 9999.

LAT$_ITM_HI_CIRCUITS

Indicates the highest number the resource attained since the host was
initialized for LAT connections to node.

LAT$_ITM_CUR_
CIRCUITS

Indicates current count of active connections to node.

LAT$_ITM_MAX_
CIRCUITS

Indicates maximum allowed virtual circuits to node.

LAT$_ITM_HI_
SESSIONS

Indicates highest number the resource attained since the host was initialized
for LAT sessions.

LAT$_ITM_CUR_
SESSIONS

Indicates current number of active sessions.

LAT$_ITM_MAX_
SESSIONS

Indicates maximum possible sessions.

LAT$_ITM_HI_OUT_
QUEUE

Indicates highest number the resource attained since the host was initialized
of outgoing queued connect requests.

LAT$_ITM_CUR_OUT_
QUEUE

Indicates current count of outgoing queued connect requests.

LAT$_ITM_MAX_OUT_
QUEUE

Indicates maximum number of simultaneous outgoing queued connect

requests.

LAT$_TIM_HI_IN_
QUEUE

Indicates highest number the resource attained since the host was initialized
of incoming queued requests.

LAT$_ITM_CUR_IN_
QUEUE

Indicates current number of entries in the incoming connect queue.

Alpha specific.

(continued on next page)

556 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 513 (Cont.) LAT$C_ENT_NODE Item Codes
Item Code

Meaning

LAT$_ITM_MAX_IN_
QUEUE

Indicates maximum number of entries allowed on the incoming connect

queue.

LAT$_ITM_HI_SAMS_
QUEUED

Indicates highest number the resource attained since the host was initialized
of outstanding, unprocessed service announcement messages by LATACP.

LAT$_ITM_CUR_SAMS_
QUEUED

Indicates current number of outstanding, unprocessed service announcement

messages on LATACPs queue.

LAT$_ITM_MAX_SAMS_
QUEUED

Indicates maximum number of outstanding, unprocessed service

announcement messages allowed on LATACPs queue. If this limit is ever
reached, subsequent service announcement messages are not delivered or
processed by LATACP.

LAT$_ITM_HI_SOL_
QUEUED

Indicates highest number the resource attained since the host was initialized
of outstanding, unprocessed solicit information messages by LATACP.

LAT$_ITM_CUR_SOL_
QUEUED

Indicates current number of outstanding, unprocessed solicit information

messages on LATACPs queue.

LAT$_ITM_MAX_SOL_
QUEUED

Indicates maximum number of outstanding, unprocessed solicit information

messages allowed on LATACPs queue. If this limit is ever reached,
subsequent solicit information messages are not delivered or processed
by LATACP.

LAT$_ITM_HI_AVAIL_
SVCS

Indicates highest number the resource attained since the host was initialized
of number of available services in LATACP database.

LAT$_ITM_CUR_AVAIL_
SVCS

Indicates count of currently available LAT services in LATACP database.

LAT$_ITM_MAX_AVAIL_
SVCS

Indicates maximum number of available services possible in LATACP

database.

LAT$_ITM_HI_REACH_
NODES

Indicates highest number the resource attained since the host was initialized
of reachable nodes in LATACP database.

LAT$_ITM_CUR_
REACH_NODES

Indicates current number of reachable nodes in LATACP database.

LAT$_ITM_MAX_
REACH_NODES

Indicates maximum number of nodes allowed in LATACP database.

LAT$_ITM_HI_LCL_
SVCS

Indicates highest number the resource attained since the host was initialized
of locally offered services.

LAT$_ITM_CUR_LCL_
SVCS

Indicates current count of locally offered service.

LAT$_ITM_MAX_LCL_
SVCS

Indicates maximum number of locally offered services.

LAT$_ITM_DISCARDED_
NODES

Indicates number of discarded service announcement messages.

LAT$_ITM_SERVICE_
CLASSES

Indicates returned service class bit mask for supported service classes on
node. It is returned for both local and remote nodes. If service class 1 is
enabled, then bit <1> is set in this mask. When bit setting equals 1, this
indicates the corresponding service class for that bit is enabled. That is,
when bit <3> equal 1, then service class 3 is enabled.

LAT$_ITM_LARGE_
BUFFERS

Indicates in Boolean logic whether or not the LAT software is using large
packet support by default.

LAT$_ITM_
ANNOUNCEMENTS

Indicates in Boolean logic whether or not the LAT software is transmitting

LAT service advertisement messages.

Alpha specific.

Terminal Driver 557

Terminal Driver
5.4 Terminal Function Codes
Table 514 lists the item codes that may be set for the LAT$C_ENT_SERVICE
entity type.
Table 514 LAT$C_ENT_SERVICE Item Codes
Item Code

Meaning

LAT$_ITM_RATING

Static LAT service rating. The default is the dynamic rating calculation.
Static ratings can be between 0 and 255.

LAT$_ITM_
IDENTIFICATION

Service identification string. The default is the translation of

SYS$ANNOUNCE.

LAT$_ITM_SERVICE_
TYPE

Defines the type of service. Valid values are:

LAT$C_ST_GENERAL

Creates a general timesharing service.

LAT$C_ST_APPLICATION

Creates a special application service

that must then be associated with ports
dedicated to accepting connections to this
service (dedicated ports).

LAT$C_ST_LIMITED

Indicates that the service is limited.

LAT$_ITM_COUNTERS

Service counters block. Allows for zeroing of all service counters. This item
code may be specified only if the entity status field is LAT$C_ENTS_OLD
and the LAT$V_CLEAR bit is set. Violating either of these two rules results
in a returned status of SS$_BADPARAM.

LAT$_ITM_PASSWORD

Indicates that if a value of LAT$C_ENABLED is indicated, then the service

is password protected. Indicates that if a value of LAT$C_DISABLED is
indicated, then the service is not password protected.

LAT$_ITM_LIM_PORT_
BLOCK

Indicates a subblock contained in an itemlist, which has a list of limited

ports associated with the named service. This subblock may be repeated
several times; that is, once for each limited LAT device associated with the
specified service.

Alpha specific.

558 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 515 lists the item codes that may be set for the LAT$C_ENT_LINK entity
type.
Table 515 LAT$C_ENT_LINK ItemCodes
Item Code

Meaning

LAT$_ITM_STATE

Operating state of the LAT protocol. Valid values are:

LAT$C_OFF

Turns off LAT protocol processing. No new

connections allowed in either direction.
Existing connections are terminated
immediately.

LAT$C_SHUT

Disallows new LAT connections in either

direction. Existing connections are allowed
to remain active.

LAT$C_ON

Turns on LAT protocol processing. This is

the default.

LAT$_ITM_DEVICE_
NAME

The name of the local area network (LAN) device to be used for
this link. The default is hardware-dependent.

LAT$_ITM_DECNET_
ADDRESS

Specifies whether to use the DECnet address when starting

the LAT protocol on the LAN controller associated with this
link. Valid values are:

LAT$_ITM_COUNTERS

LAT$C_DISABLED

DECnet address use disabled.

LAT$C_ENABLED

DECnet address use enabled (this is

the default).

Link counters block. Allows for zeroing of all link counters.

This item code may be specified only if the entity status field
is LAT$C_ENTS_OLD and the LAT$V_CLEAR bit is set.
Violating either of these two rules results in a returned status
of SS$_BADPARAM.

Table 516 lists the item codes that may be set for the LAT$C_ENT_PORT entity
type.
Table 516 LAT$C_ENT_PORT Item Codes
Item Code

Meaning

LAT$_ITM_PORT_
TYPE

Type of port. Valid values are:

LAT$_ITM_QUEUED

LAT$C_PT_APPLICATION

Application port for solicited

connections.

LAT$C_PT_DEDICATED

Dedicated port associated with

a local application service.

LAT$C_PT_LIMITED

Indicates that the port type is

limited.

Controls whether the solicited connection requests queued or

nonqueued access. Valid values are:
LAT$C_DISABLED

Queued access disabled.

LAT$C_ENABLED

Queued access enabled (this is

the default).

Alpha specific.

(continued on next page)

Terminal Driver 559

Terminal Driver
5.4 Terminal Function Codes
Table 516 (Cont.) LAT$C_ENT_PORT Item Codes
Item Code

Meaning

LAT$_ITM_SERVICE_
CLASS

Controls the class driver that the LAT driver communicates

with when a connection is established. This item code can
be used only with an entity status of LAT$C_ENTS_NEW.
Therefore, the service class must be specified when the
device is created. An attempt to change the service class of
an existing device returns SS$_BADPARAM. Valid values are:
LAT$C_SERVCLASS_
INTERACTIVE

Service class 1, TTDRIVER

(this is the default).

LAT$C_SERVCLASS_
XTRANSPORT

Service class 3, X Protocol.

LAT$C_SERVCLASS_FONT

Service class 4, X fonts.

LAT$_ITM_DISPLAY_
NUMBER

For X devices, this is the binary value of the display number,

which may need to be transmitted in some LAT messages.
Values range from 0255, with a default of 0. This item
code has meaning only when used with service classes 3
and 4 (LAT$C_SERVCLASS_XTRANSPORT AND LAT$C_
SERVCLASS_FONT).

LAT$_ITM_TARGET_
NODE_NAME

Target node name for connection. This parameter must be

specified for application ports and may optionally be specified
for forward ports.

LAT$_ITM_TARGET_
SERVICE_NAME

Target service name for connection. This parameter must be

specified for forward ports and may optionally be specified
for application ports. For dedicated ports, this parameter
specifies the local application service to which the port should
be associated.

LAT$_ITM_TARGET_
PORT_NAME

Target port name for connection. This parameter may

optionally be specified for application ports or forward ports; it
is ignored for all other kinds of ports.

LAT$_ITM_SERVICE_
PASSWORD

Password string for remote service on forward ports. This

parameter must be specified to access services that are
protected with a password. This parameter is ignored if it
is specified for a service that is not protected with a password.

LAT$_ITM_DIALUP

Indicates if an LTA device tells a remote node that the

connection is coming from a dialin source. Possible values
are LAT$C_ENABLED or LAT$C_DISABLED.

LAT$_ITM_
AUTOPROMPT

Indicates if a connect request has autoprompt enabled.

Possible values are LAT$C_ENABLED or LAT$C_DISABLED.

Alpha specific.

5.4.4.4 Obtaining Information About LAT Entities

The LAT SENSEMODE $QIO function (IO$_TTY_PORT!IO$M_LT_
SENSEMODE) is used to obtain information about LAT nodes, services, ports,
and links.
The LAT SENSEMODE $QIO function accepts four arguments: P1, P2, P3, and
P4. P1 is the address of a buffer into which information about the desired entity
is returned. The information is returned in the form of an item list. Unlike
system services such as $GETDVI or $GETJPI, you do not select which items
of information are returned. P2 is the length of the buffer specified in P1, in
bytes. The number of bytes of information returned in the P1 buffer is returned
in IOSB+2.

560 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
P3 specifies the type of entity to which the SENSEMODE operation applies. The
entity type can be one of five types:

Node (LAT$C_ENT_NODE). Node, including the local node.

Service (LAT$C_ENT_SERVICE). Service, including local services.

Link (LAT$C_ENT_LINK). Data link associated with the LAN.

Port (LAT$C_ENT_PORT).

Queue Entry (LAT$C_ENT_QUEUE_ENTRY). Indicates queue entry entities.

The value for the entity type occupies the low-order 16 bits (bits 015) of the P3
parameter. Bits 1623 are used as a flag field. Two bits are currently defined
within this field: LAT$V_SENSE_NEXT and LAT$V_SENSE_FULL. If the
LAT$V_SENSE_NEXT bit is 0, information about the current entity described
by the P3 and P4 parameters is returned to the user; if this bit is 1, information
about the next entity that logically follows the one described by P4 is returned.
If LAT$V_SENSE_FULL is 0, only those item codes marked SUMMARY in the
following tables are returned; if this bit is 1, all item codes that describe the
entity specified by the P3 and P4 parameters are returned.
P4 may contain the address of an entity name string descriptor. If this parameter
is omitted (contains a zero or the address of a descriptor that points to an empty
string) and the LAT$V_SENSE_NEXT bit is set, information about the first entity
that matches the entity type supplied by P3 is returned.
If P4 is omitted and the LAT$V_SENSE_NEXT bit is 0, a default entity name
may be used in some cases. The defaults for each entity type are as follows:

LAT$C_ENT_NODEThe local node.

LAT$C_ENT_SERVICENo default; you must specify the service name.

LAT$C_ENT_LINKThe string LAT$LINK.

LAT$C_ENT_PORTThe device name associated with the currently assigned

channel (the CHAN parameter of the $QIO function.)

SENSEMODE can return the following failure return codes:

SS$_NOPRIVNo privilege to complete the desired operation

SS$_ACCVIOPart of the argument list or item list is not addressable

SENSEMODE Item Codes

Each item in the itemlist starts with a one-word (16-bit) item code that describes
the type of information contained in the item. The item code is followed by a
value associated with the item.
Item codes in which the bit named LAT$V_STRING is 0 take a longword value.
The associated value is contained in the longword immediately following the item
code in the itemlist. Item codes in which this bit is 1 take a counted string for
their value. The byte immediately following the item code contains a byte count,
which describes the length of the string that immediately follows it.
Table 517 lists the item codes that are returned for the LAT$C_ENT_NODE
entity type. Item codes noted as LOCAL are returned only if the information
being returned is for the local node. Item codes noted as REMOTE are returned
only if the information being returned is for a remote node. Item codes noted as
BOTH are returned for both types of nodes.

Terminal Driver 561

Terminal Driver
5.4 Terminal Function Codes
Table 517 LAT$C_ENT_NODE Item Codes
Item Codes

Meaning

LAT$_ITM_NODE_
NAME (BOTH,
SUMMARY)

LAT node name for the node.

LAT$_ITM_
IDENTIFICATION
(BOTH, SUMMARY)

Node identification string.

LAT$_ITM_NODE_
TYPE (BOTH,
SUMMARY)

Type of node. Possible values are:

LAT$_ITM_STATE
(LOCAL,SUMMARY)

LAT$_ITM_NODE_
STATUS (REMOTE,
SUMMARY)

LAT$C_NT_LOCAL

Node is local node.

LAT$C_NT_REMOTE

Node is remote node.

Operating state of the LAT protocol. Possible values are:

LAT$C_ON

New connections are allowed and the LAT

protocol is running.

LAT$C_OFF

New connections are not allowed. The LAT

protocol is not running.

LAT$C_SHUT

No new connections are allowed. Currently

active connections are still maintained. The
LAT protocol remains running only until
the last active session is disconnected, at
which time the node is placed in the OFF
state.

Current status of remote node. This item code is present only

if a LAT virtual circuit does not currently exist between the
local node and this remote node. Possible values are:
LAT$C_REACHABLE

Remote node is reachable.

LAT$C_UNREACHABLE

Remote node is unreachable.

LAT$C_UNKNOWN

Remote node status is

unknown.

LAT$_ITM_
CONNECTED_COUNT
(REMOTE, SUMMARY)

Number of LAT sessions from the local node to this remote

node. This item code replaces the LAT$_ITM_NODE_STATUS
item code for remote nodes to which a LAT virtual circuit
currently exists.

LAT$_ITM_SERVICE_
GROUPS (BOTH)

A bit mask of LAT group codes that are serviced by the node.

LAT$_ITM_
PROTOCOL_VERSION
(BOTH)

LAT protocol version string.

LAT$_ITM_DATALINK_
ADDRESS (REMOTE)

LAN address used by the node.

LAT$_ITM_NODE_
LIMIT

Maximum number of nodes in LAT database. The default is 0,

where the maximum is determined by system resources.

LAT$_ITM_
RETRANSMIT_LIMIT

LAT retransmit limit. Possible values are 4 to 120

retransmissions. The default is 8 retransmissions.

LAT$_ITM_MAXIMUM_
UNITS (LOCAL)

Maximum LTA unit number.

(continued on next page)

562 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 517 (Cont.) LAT$C_ENT_NODE Item Codes
Item Codes

Meaning

LAT$_ITM_SERVER_
MODE (LOCAL)

Controls whether the node allows the use of the MASTER side
of the LAT protocol for outbound connections. Possible values
are:

LAT$_ITM_SERVICE_
RESPONDER (LOCAL)

LAT$C_DISABLED

Server mode disabled (this is

the default).

LAT$C_ENABLED

Server mode enabled.

Indicates whether the node is to respond to service inquiries

originating from a remote system. These inquiries are not
necessarily directed at services being offered by the node.
Refer to the OpenVMS System Management Utilities Reference
Manual for more information on this feature. Possible values
are:
LAT$C_DISABLED

Service responder disabled

(this is the default).

LAT$C_ENABLED

Service responder enabled.

LAT$_ITM_
OUTGOING_SES_
LIMIT (LOCAL)

Maximum number of outgoing LAT sessions. A value of 0,

which is the default, indicates that the limit is determined by
system resources.

LAT$_ITM_
INCOMING_SES_
LIMIT (LOCAL)

Maximum number of interactive LAT sessions. A value of 0,

which is the default, indicates that the limit is determined by
system resources.

LAT$_ITM_USER_
GROUPS (LOCAL)

Bit mask of LAT group codes to be used when attempting

outbound connections using the MASTER side of the LAT
protocol.

LAT$_ITM_CIRCUIT_
TIMER (BOTH)

Circuit timer value in milliseconds. Possible values are 10 to

1000 milliseconds. The default is 80 milliseconds.

LAT$_ITM_CPU_
RATING (LOCAL)

CPU rating.

LAT$_ITM_
KEEPALIVE_TIMER
(LOCAL)

Keepalive timer value in seconds. Possible values are 10 to

255 seconds. The default is 20 seconds.

LAT$_ITM_
MULTICAST_TIMER
(BOTH)

Multicast timer value in seconds. Possible values are 10 to 180

seconds. The default is 20 seconds.

LAT$_ITM_
CONNECTIONS
(BOTH)

Indicates whether inbound connections (interactive sessions)

can be accepted. Possible values are:
LAT$C_DISABLED

Inbound connections disabled.

LAT$C_ENABLED

Inbound connections enabled

(this is the default).

LAT$C_ITM_LARGE_
BUFFERS

Indicates in Boolean logic whether the LAT software is using

large packet support by default.

LAT$C_ITM_
ANNOUNCEMENTS

Indicates in Boolean logic whether the LAT software is

transmitting LAT service advertisement messages.

Node service information is presented as a list of node service subblocks, with

each subblock containing information about one particular service offered by the
node. The subblock item code LAT$_ITM_NODE_SVC_BLOCK has the LAT$V_
STRING bit set to 1, and the string length byte actually contains the length of
the entire subblock. Each subblock itself is an itemlist and consists of the item
codes listed in Table 518.

Terminal Driver 563

Terminal Driver
5.4 Terminal Function Codes
Table 518 Node Service Subblock Item Codes
Item Codes

Meaning

LAT$_ITM_SERVICE_NAME
(BOTH)

Name of a LAT service offered by the node.

LAT$_ITM_SERVICE_
STATUS (BOTH)

Status of the service. Possible values are:

LAT$_ITM_SERVICE_TYPE
(LOCAL)

LAT$C_AVAILABLE

Service available.

LAT$C_UNAVAILABLE

Service unavailable.

Type of service. Possible values are:

LAT$C_ST_GENERAL

Creates a general
timesharing service.

LAT$C_ST_APPLICATION

Creates a special
application service that
must then be associated
with ports dedicated to
accepting connections to
this service (dedicated
ports).

LAT$_ITM_RATING (BOTH)

LAT service rating associated with the service.

LAT$_ITM_RATING_TYPE
(LOCAL)

Type of LAT rating calculation being done by this node.

Possible values are:

LAT$_ITM_
IDENTIFICATION (BOTH)

LAT$C_STATIC

Static rating calculation

LAT$C_DYNAMIC

Dynamic rating
calculation

Identification string associated with the service.

On Alpha systems, port counters information is presented as a counters subblock.

The subblock item code LAT$_ITM_COUNTERS has the LAT$V_STRING bit
set to 1, and the string length byte actually contains the length of the entire
subblock. The subblock itself is an itemlist and consists of the item codes listed
in Table 519.
Table 519 Node Counters Item Codes for Port Counters Subblocks (Alpha
Only)
Item Codes

Meaning

LAT$_ITM_CTPRT_LCL

Indicates number of local accesses to port.

LAT$_ITM_CTPRT_SLCA

Indicates number of solicitations accepted.

LAT$_ITM_CTPRT_SLCR

Indicates number of solicitations rejected.

LAT$_ITM_CTPRT_ISOLA

Indicates number of incoming solicitations accepted.

LAT$_ITM_CTPRT_ISOLR

Indicates number of incoming solicitations rejected.

LAT$_ITM_CTPRT_FRAMERR

Indicates number of framing errors for named port.

Returned in port counter subblock.

LAT$_ITM_CTPRT_PARERR

Indicates number of parity errors for named port.

Returned in port counter subblock.

LAT$_ITM_CTPRT_OVERRUN

Indicates number of data overruns for named port.

Returned in port counter subblock.

LAT$_ITM_PASSWORD_
FAILURES

Indicates password failures.

564 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Node counters information is presented as a counters subblock. The subblock
item code LAT$_ITM_COUNTERS has the LAT$V_STRING bit set to 1, and
the string length byte actually contains the length of the entire subblock. The
subblock itself is an itemlist and consists of the item codes listed in Table 520.
Table 520 Node Counters Item Codes
Item Codes

Meaning

LAT$_ITM_CTNOD_SSZ
(BOTH)

Seconds since zeroed

LAT$_ITM_CTNOD_MSGR
(BOTH)

Messages received

LAT$_ITM_CTNOD_MSGT
(BOTH)

Messages transmitted

LAT$_ITM_CTNOD_SLTR
(BOTH)

Slots received

LAT$_ITM_CTNOD_SLTT
(BOTH)

Slots transmitted

LAT$_ITM_CTNOD_BYTR
(BOTH)

Bytes received

LAT$_ITM_CTNOD_BYTT
(BOTH)

Bytes transmitted

LAT$_ITM_CTNOD_MNA
(BOTH)

Multiple node addresses

LAT$_ITM_CTNOD_DUP
(BOTH)

Duplicates received

LAT$_ITM_CTNOD_MRT
(BOTH)

Messages retransmitted

LAT$_ITM_CTNOD_ILM
(BOTH)

Illegal messages received

LAT$_ITM_CTNOD_ILS (BOTH)

Illegal slots received

LAT$_ITM_CTNOD_SLCA
(BOTH)

Solicitations accepted

LAT$_ITM_CTNOD_SLCR
(BOTH)

Solicitations rejected

LAT$_ITM_CTNOD_TER
(LOCAL)

Transmit errors

LAT$_ITM_CTNOD_RES
(LOCAL)

Resource errors

LAT$_ITM_CTNOD_NTB
(LOCAL)

No transmit buffer

LAT$_ITM_CTNOD_TMO
(LOCAL)

Virtual circuit timeout

LAT$_ITM_CTNOD_DOB
(LOCAL)

Discarded output bytes

LAT$_ITM_CTNOD_LSTER
(LOCAL)

Last transmit error

LAT$_ITM_CTNOD_MCBXMT
(LOCAL)

Number of multicast bytes transmitted

(continued on next page)

Terminal Driver 565

Terminal Driver
5.4 Terminal Function Codes
Table 520 (Cont.) Node Counters Item Codes
Item Codes

Meaning

LAT$_ITM_CTNOD_MCBRCV
(LOCAL)

Number of multicast bytes received

LAT$_ITM_CTNOD_MCMXMT
(LOCAL)

Number of multicast messages transmitted

LAT$_ITM_CTNOD_MCMRCV
(LOCAL)

Number of multicast messages received

LAT$_ITM_CTNOD_SOLFAIL
(LOCAL)

Number of solicitation failures

LAT$_ITM_CTNOD_ATLOS
(LOCAL)

Number of times attention slot data was lost

LAT$_ITM_CTNOD_DATLOS
(LOCAL)

Number of times user data was lost

LAT$_ITM_CTNOD_NOREJ
(LOCAL)

Number of times a reject slot could not be sent

LAT$_ITM_CTNOD_LOSCT
(LOCAL)

Number of times remote node counters were lost

LAT$_ITM_CTNOD_LOSSAM
(LOCAL)

Number of service announcement messages lost

LAT$_ITM_CTNOD_NOSAM
(LOCAL)

Number of times a service announcement message

could not be sent

LAT$_ITM_CTNOD_NOSTS
(LOCAL)

Number of times node status was lost

LAT$_ITM_CTNOD_NOXMT
(LOCAL)

Number of times no link was available for a transmit

LAT$_ITM_CTNOD_
CTLERR(LOCAL)

Number of controller errors

LAT$_ITM_CTNOD_
CERRCOD(LOCAL)

Lost controller error

LAT$_ITM_CTNOD_
ISOLA(LOCAL)

Number of incoming solicitations accepted

LAT$_ITM_CTNOD_
ISOLR(LOCAL)

Number of incoming solicitations rejected

LAT$_ITM_CTNOD_PROTO
(LOCAL)

Protocol error count

LAT$_ITM_CTNOD_XSTR
(REMOTE)

Indicates that the node attempted to start up too many

LAT sessions for a specific virtual circuit

Alpha specific.

Several protocol errors are also included in a separate subblock. The protocol
errors item code is LAT$_ITM_PROTOCOL_ERRORS and has LAT$V_STRING
set (the size of the subblock is contained in the first byte following the item code).
The item codes and the events they represent are listed in Table 521.

566 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 521 Protocol Error Item Codes
Item Codes

Meaning

LAT$_ITM_CTPRO_IVM
(LOCAL)

Invalid message type received.

LAT$_ITM_CTPRO_ISM
(LOCAL)

Invalid start message received.

LAT$_ITM_CTPRO_IVS
(LOCAL)

Invalid sequence number received.

LAT$_ITM_CTPRO_NIZ
(LOCAL)

Zero-node index received.

LAT$_ITM_CTPRO_ICI
(LOCAL)

Node circuit index out of range.

LAT$_ITM_CTPRO_CSI
(LOCAL)

Node circuit sequence invalid.

LAT$_ITM_CTPRO_NLV
(LOCAL)

Node circuit index no longer valid.

LAT$_ITM_CTPRO_HALT
(LOCAL)

Circuit was forced to halt.

LAT$_ITM_CTPRO_MIZ
(LOCAL)

Invalid master slot index.

LAT$_ITM_CTPRO_SIZ
(LOCAL)

Invalid slave slot index.

LAT$_ITM_CTPRO_CRED
(LOCAL)

Invalid credit field.

LAT$_ITM_CTPRO_RCSM
(LOCAL)

Repeat creation of slot by master.

LAT$_ITM_CTPRO_RDSM
(LOCAL)

Repeat disconnection of slot by master.

LAT$_ITM_CTPRO_
INVCLASS (LOCAL)

Indicates the number of times a LAT message was

received with an invalid service class specified in that
message (local node only).

LAT$_ITM_CTPRO_
EXCSTART (LOCAL)

Indicates that a remote node attempted to start up too

many LAT sessions. When a virtual circuit is started
between two LAT nodes, the maximum number of sessions
on that virtual circuit is negotiated. If the master node
attempts to create more sessions than the maximum
number of sessions on a virtual circuit, then the operating
system rejects the excess connections and increments this
counter.

Alpha specific.

Table 522 lists the item codes that are returned for the LAT$C_ENT_SERVICE
entity type. As in Table 517, item codes noted as LOCAL are returned only if
the information being returned is for a locally offered service. Item codes noted
as REMOTE are returned only if the information being returned is for a service
offered by a remote node. Item codes noted as BOTH are returned for both types
of services.

Terminal Driver 567

Terminal Driver
5.4 Terminal Function Codes
Table 522 LAT$C_ENT_SERVICE Item Codes
Item Codes

Meaning

LAT$_ITM_SERVICE_
NAME
(BOTH, SUMMARY)

Service name.

LAT$_ITM_SERVICE_
STATUS
(BOTH, SUMMARY)

Status of the specified service. Possible values are:

LAT$_ITM_
SERVICE_TYPE
(LOCAL,SUMMARY)

LAT$_ITM_
IDENTIFICATION
(BOTH, SUMMARY)

LAT$C_AVAILABLE

Service available.

LAT$C_UNAVAILABLE

Service unavailable.

Type of service. Possible values are:

LAT$C_ST_GENERAL

General timesharing service.

LAT$C_ST_APPLICATION

Special application service

associated with ports
dedicated to accepting
connections to this service.

Service identification string, as advertised by the highest rated

node that currently offers the service.

Service node information is presented as a list of service node subblocks, with

each subblock containing information about one particular node that offers the
service. The subblock item code LAT$_ITM_SVC_NODE_BLOCK has the LAT$V_
STRING bit set to 1, and the string length byte actually contains the length of
the entire subblock. Each subblock itself is an itemlist and consists of the item
codes listed in Table 523.
Table 523 Service Node Subblock Item Codes
Item Codes

Meaning

LAT$_ITM_NODE_NAME
(BOTH)

Name of a LAT node that offers the selected service.

LAT$_ITM_STATE
(LOCAL)

Current state of the LAT protocol on the local node.

Possible values are:
LAT$C_ON

New connections are allowed, and the

LAT protocol is running.

LAT$C_OFF

New connections are not allowed,

and any current connections are
abnormally terminated. The LAT
protocol is not running.

LAT$C_SHUT

No new connections are allowed.

Currently active connections are
still maintained. The LAT protocol
remains running only until the last
active session is disconnected, at
which time the node is placed in the
OFF state.
(continued on next page)

568 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 523 (Cont.) Service Node Subblock Item Codes
Item Codes

Meaning

LAT$_ITM_NODE_STATUS
(REMOTE)

Current status of the remote node. This item code is

present only if a LAT virtual circuit does not currently
exist to the remote node. Possible values are:
LAT$C_REACHABLE

Remote node is
reachable.

LAT$C_UNREACHABLE

Remote node is
unreachable.

LAT$C_UNKNOWN

Remote node status is

unknown.

LAT$_ITM_CONNECTED_
COUNT
(REMOTE)

Number of LAT sessions from the local node to this

remote node. This item code replaces the LAT$_ITM_
NODE_STATUS item code for remote nodes to which a
LAT virtual circuit currently exists.

LAT$_ITM_RATING
(BOTH)

LAT service rating associated with the service.

LAT$_ITM_RATING_TYPE
(LOCAL)

Type of LAT rating calculation being done by this

node. Possible values are LAT$C_STATIC and LAT$C_
DYNAMIC.

LAT$_ITM_
IDENTIFICATION
(BOTH)

Identification string associated with the service.

Service counters information is presented as a counters subblock. The subblock

item code LAT$_ITM_COUNTERS has the LAT$V_STRING bit set, and the
string length byte actually contains the length of the entire subblock. Each
subblock itself is an itemlist and consists of the item codes listed in Table 524.

Terminal Driver 569

Terminal Driver
5.4 Terminal Function Codes
Table 524 Service Counters Subblock Item Codes
Item Codes

Meaning

LAT$_ITM_CTSRV_SSZ
(BOTH)

Seconds since zeroed.

LAT$_ITM_CTSRV_MCNA
(BOTH)

Outgoing connections attempted (the number of times the

local node has attempted to connect to the service offered
on a remote node).

LAT$_ITM_CTSRV_MCNC
(BOTH)

Outgoing connections completed (the number of times the

local node successfully connected to the service offered on
a remote node).

LAT$_ITM_CTSRV_SCNA
(BOTH)

Incoming connections accepted (the number of times

the local node has accepted a connection request from a
remote node to the locally offered service).

LAT$_ITM_CTSRV_SCNR
(BOTH)

Incoming connections rejected (the number of times the

local node rejected a connection request from a remote
node to the locally offered service).

LAT$_ITM_DED_PORT_
BLOCK
(LOCAL)

If the selected service is an application service offered

by the local node, a list of one or more port subblocks is
included in the itemlist. These subblocks describe the
dedicated port or ports associated with this application
service, with each subblock describing one particular port.
The subblock item code LAT$_ITM_DED_PORT_BLOCK
has the LAT$V_STRING bit set, and the string length
byte actually contains the length of the entire subblock.
Each subblock itself is an itemlist and currently consists
only of the following item code:
LAT$_ITM_PORT_NAME
(LOCAL)

LAT$_ITM_PASSWORD_
FAILURE

Name of the dedicated

port

Indicates password failures.

Alpha specific.

Table 525 lists the item codes that are returned for the LAT$C_ENT_LINK
entity type.
Table 525 LAT$C_ENT_LINK Item Codes
Item Codes

Meaning

LAT$_ITM_LINK_NAME
(SUMMARY)

Link name (such as LAT$LINK).

(continued on next page)

570 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 525 (Cont.) LAT$C_ENT_LINK Item Codes
Item Codes

Meaning

LAT$_ITM_STATE
(SUMMARY)

State of the link. Possible values are:

LAT$C_ON

New connections are allowed, and the

LAT protocol is running.

LAT$C_OFF

New connections are not allowed,

and any current connections are
abnormally terminated. The LAT
protocol is not running.

LAT$C_SHUT

No new connections are allowed.

Currently active connections are
still maintained. The LAT protocol
remains running only until the last
active session is disconnected, at
which time the node is placed in the
OFF state.

LAT$_ITM_DEVICE_NAME
(SUMMARY)

The name of the LAN device used for the link.

LAT$_ITM_DATALINK_
ADDRESS

The LAN devices current physical address for the link.

LAT$_ITM_DECNET_
ADDRESS

Indicates whether the link attempts to use the default

DECnet LAN address when starting the data link
controller (enabling the LAT protocol). Possible values
are:
LAT$C_DISABLED

DECnet LAN address use

disabled.

LAT$C_ENABLED

DECnet LAN address use

enabled (this is the default).

Link counters information is presented as a counters subblock. The subblock

item code LAT$_ITM_COUNTERS has the LAT$V_STRING bit set, and the
string length byte actually contains the length of the entire subblock. Because
the link counters are independent of the protocol type, they include not only
LAT messages and events, but also all other protocol messages and events (that
is, DECnet) associated with the same LAN device. The counters are actually
maintained by the LAN device driver and are identified within the subblock by
the nonprotocol-specific item codes listed in Table 526.
Table 526 Link Counters Item Codes
Item Codes

Meaning

NMA$C_CTLIN_ZER

Seconds since zeroed

NMA$C_CTLIN_DBR

Messages received

NMA$C_CTLIN_DBS

Messages transmitted

NMA$C_CTLIN_MBL

Multicast messages received

NMA$C_CTLIN_MBS

Multicast messages transmitted

NMA$C_CTLIN_BRC

Bytes received

NMA$C_CTLIN_BSN

Bytes transmitted
(continued on next page)

Terminal Driver 571

Terminal Driver
5.4 Terminal Function Codes
Table 526 (Cont.) Link Counters Item Codes
Item Codes

Meaning

NMA$C_CTLIN_MBY

Multicast bytes received

NMA$C_CTLIN_MSN

Multicast bytes transmitted

NMA$C_CTLIN_RFL

Receive errors

NMA$C_CTLIN_SFL

Transmit errors

NMA$C_CTLIN_OVR

Data overrun

NMA$C_CTLIN_UBU

User buffer unavailable

NMA$C_CTLIN_SBU

System buffer unavailable

NMA$C_CTLIN_LBE

Local buffer errors

NMA$C_CTLIN_BS1

Messages sent, single collisions

NMA$C_CTLIN_BSM

Messages sent, multiple collisions

NMA$C_CTLIN_BID

Messages sent, initially deferred

NMA$C_CTLIN_CDC

Transmit collision detection check failure

Table 527 lists additional link counter item codes of the LINK entity.
Table 527 Link Counters Item Codes
Item Codes

Meaning

LAT$_ITM_CTLAT_RMSG

Count of LAT messages received through link

LAT$_ITM_CTLAT_RBYT

Count of bytes for LAT received through link

LAT$_ITM_CTLAT_XMSG

Count of LAT messages transmitted through link

LAT$_ITM_CTLAT_XBYT

Count of bytes for LAT transmitted through link

LAT$_ITM_CTLAT_MUL_
RMSG

Count of LAT multicast messages received through link

LAT$_ITM_CTLAT_MUL_
RBYT

Count of multicast bytes for LAT received through link

LAT$_ITM_CTLAT_MUL_
XMSG

Count of LAT multicast messages transmitted through

link

LAT$_ITM_CTLAT_MUL_
XBYT

Count of multicast bytes for LAT transmitted through

link

LAT$_ITM_LAT_DEV_CTR_
BLOCK

This block contains the LAT-specific counters for the

specified link. Counters returned in this block are the
ones defined above (with CTLAT in their name). These
counters are LAT-specific for the link (device). They do
not include counts from other protocols using the same
adapter.

The counter item codes listed in Table 527 are used by LATCP in the display
generated by the $SHOW LINK /COUNTER command. The display looks similiar to
the following:
Link Name:
LAT$LINK
Device Name: _XQA1:

572 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Seconds Since Zeroed:
Messages Received:
LAT Messages Received:
Multicast Msgs Received:
LAT Multicast Msgs Received:
Bytes Received:
LAT Bytes Received:
Multicast Bytes Received:
LAT Multicast Bytes Received:
System Buffer Unavailable:
Unrecognized Destination:
Receive Errors:

65535
7080630
1484817
5578139
5093417
678189475
107809441
602984574
565264261
1638401
65537
7

Receive Errors (bitmask = 001) Block Check Error:

Framing Error:
Frame Too Long:
Frame Status Error:
Frame Length Error:

Yes
No
No
No
No

Messages Sent:
2135394
LAT Messages Sent:
2086167
Multicast Msgs Sent:
10775
LAT Multicast Msgs Sent:
9142
Bytes Sent:
1312778402
LAT Bytes Sent:
1278118808
Multicast Bytes Sent:
1696264
LAT Multicast Bytes Sent:
1448342
User Buffer Unavailable:
1
Data Overrun:
1
Transmit Errors:
1
Transmit Errors (bitmask = 001)
Excessive Collisions:
Carrier Check Failure:
Short Circuit:
Open Circuit:
Frame Too Long:
Remote Failure To Defer:
Transmit Underrun:
Transmit Failure:

Yes
No
No
No
No
No
No
No

CSMACD Specific Counters

-----------------------Transmit CDC Failure:
Messages Transmitted Single Collision:
Multiple Collisions:
Initially Deferred:

1
5208
4732
0

Table 528 lists the item codes that are returned for the LAT$C_ENT_PORT
entity type.
Table 528 LAT$C_ENT_PORT Item Codes
Item Codes

Meaning

LAT$_ITM_PORT_NAME
SUMMARY

Name of the port (such as _LTA15:).

LAT$_ITM_PORT_TYPE
SUMMARY

Type of port. Possible values are:

LAT$C_PT_FORWARD

Forward port used for

outgoing LAT connections
or for management
functions.

LAT$C_PT_INTERACTIVE

Interactive port created

as the result of an
incoming LAT connection
request.

LAT$C_PT_APPLICATION

Application port for

solicited connections.

LAT$C_PT_DEDICATED

Dedicated port associated

with a local service.
(continued on next page)

Terminal Driver 573

Terminal Driver
5.4 Terminal Function Codes
Table 528 (Cont.) LAT$C_ENT_PORT Item Codes
Item Codes

Meaning

LAT$_ITM_QUEUED

Controls whether the solicited connection requests queued

or nonqueued access. Possible values are:

LAT$_ITM_SERVICE_
CLASS

LAT$C_DISABLED

Queued access disabled.

LAT$C_ENABLED

Queued access enabled

(this is the default).

Indicates the class driver with which the device is

communicating. This item code can be used only with
an entity status of LAT$C_ENTS_NEW. Therefore, the
service class must be specified when the device is created.
An attempt to change the service class of an existing
device returns SS$_BADPARAM. Possible values are:
LAT$C_SERVCLASS_
INTERACTIVE

Service class 1,
TTDRIVER (this is the
default).

LAT$C_SERVCLASS_
TESTSERVICE

Service class 2, TEST

SERVICE.

LAT$C_SERVCLASS_
XTRANSPORT

Service class 3, X
Protocol.

LAT$C_SERVCLASS_FONT

Service class 4, X fonts.

LAT$_ITM_DISPLAY_
NUMBER

Display number value for the device. This field has

meaning for services classes 3 and 4 (X) only. It returns a
value of 0 for all other service classes.

LAT$_ITM_DISCONNECT_
REASON

Reason (if any) for the last disconnect on the port. If it

is not a 019 LAT rejection code, it is a LAT message
code. The 019 LAT rejection code meanings are listed in
Table 532.

LAT$_ITM_CONNECTED_
SERVICE_NAME1

Name of service to which this port is connected. For

forward and application ports, this is the name of the
remote service to which the port is connected (if any). For
interactive and dedicated ports, this is the name of the
local service that accepted the remote-initiated connection.

LAT$_ITM_CONNECTED_
NODE_NAME1

Name of remote node to which this port is connected.

LAT$_ITM_CONNECTED_
PORT_NAME1

Name of remote port to which this port is connected.

LAT$_ITM_CONNECTED_
LINK_NAME1

Name of the link on which the LAT connection exists.

LAT$_ITM_TARGET_
SERVICE_NAME2

Target service name for connection of forward or

application ports. For dedicated ports, this item
code specifies the local service with which the port is
associated.

LAT$_ITM_TARGET_NODE_
NAME2

Target node name for connection of forward or application

ports.

LAT$_ITM_TARGET_PORT_
NAME2

Target port name for connection of forward or application

ports.

1 Returned

only when the LTA port has an active LAT connection.

2 Shows

information about how the port is set up. May be returned even if there is no current LAT
connection.

(continued on next page)

574 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
Table 528 (Cont.) LAT$C_ENT_PORT Item Codes
Item Codes

Meaning

LAT$_ITM_NODE_
QUEUE_POSITION

Indicates current node queue position for connect request.

Returned during SENSEMODE of port entity.

LAT$_ITM_SERVICE_
QUEUE_POSITION

Indicates current service queue position for connect

request. Returned during SENSEMODE of port entity.

LAT$_ITM_PORT_STATE

Current port state. Possible values are:

LAT$C_PT_STATE_
INACTIVE

Port is inactive.

LAT$C_PT_STATE_
CONNECTING

Port connection in
progress but not
complete.

LAT$C_PT_STATE_ACTIVE

Port has active LAT

connection.

LAT$C_PT_STATE_
DISCONNECTING

PORT LAT connection in

process of terminating.

Alpha specific.

On Alpha systems, the item codes for queue entries are listed in Table 529.
Table 529 LAT SENSMODE Queue Entries (Alpha Only)
Item Code

Meaning

LAT$_ITM_QUEUED_ENTRY_
ID (SUMMARY)

Indicates by string the queue entry ID name.

LAT$_ITM_NODE_QUEUE_
POSITION (SUMMARY)

Indicates the current position of entry in node wide queue.

LAT$_ITM_SERVICE_QUEUE_
POSITION (SUMMARY)

Indicates the current position of entry in service wide queue.

LAT$_ITM_NODE_NAME
(SUMMARY)

Indicates where the remote node name queue entry came from.

LAT$_ITM_SERVICE_NAME
(SUMMARY)

Indicates the target service name to which the queue entry is queued (if
specified).

LAT$_ITM_PORT_NAME
(SUMMARY)

Indicates the target port name to which the entry is queued (if
specified).

LAT$_ITM_LINK_NAME

Returns the link name on which the queued request is active.

LAT$_ITM_DATALINK_
ADDRESS

Returns the remote node that issued requests data link address.

5.4.4.5 Programming Application Ports

An application port is used to connect to a remote device (typically a printer)
on a terminal server or to a dedicated port on another LAT service node. The
LAT port driver can only connect to a remote device if the device is currently
not in use. Table 530 lists the conditions that can occur when an application
program issues an IO$M_LT_CONNECT request for a connection to a remote
device. After a request is queued on the terminal server (or dedicated port on
another LAT service node), the QIO request is not completed until the connection
is established, rejected, or times out.

Terminal Driver 575

Terminal Driver
5.4 Terminal Function Codes
Table 530 IO$M_LT_CONNECT Request Status
Event

IOSB Status

Explanation

Connection established

SS$_NORMAL

The connection is successful, and

the port is ready for use.

Connection timeout

SS$_TIMEOUT

The connection did not complete

because communication was
never established with the
remote end. IOSB+2 contains
LAT$_CONTIMEOUT.

Connection rejected

SS$_ABORT. IOSB+2
contains LAT rejection
code or LAT facility
message code.

The connection cannot be made.

The LAT port driver updates
the I/O status block. The LAT
rejection codes (019) are listed
in Table 532.

Connection request

SS$_ILLIOFUNC

The QIO request is not to an

application, dedicated, or forward
port. The LAT port driver rejects
the request immediately.

Connection already
established on port

SS$_DEVACTIVE

The QIO request is for a port

already in use. The LAT port
driver rejects the request
immediately.

Incorrectly configured
LAT port

SS$_DEVREQERR

The LAT port is incorrectly

configured. This may mean that
the port type was neither forward
nor application nor dedicated,
because a forward port had no
service name mapped or because
an application port had no node
name mapped.

Insufficient resources

SS$_INSFMEM

The QIO request failed because

the LAT port driver could not get
system memory to complete the
connection.

Before the application port can be used, it must be mapped to a remote node
name, and either the port name or the service name of the remote terminal
server port. (These names must be defined locally on the terminal server.) The
application port is mapped with the IO$M_LT_SETMODE modifier, specifying the
following items in the P1 itemlist parameter:

LAT$_ITM_TARGET_NODE_NAMEThe node name. The node name is the

name of the terminal server where the application device is located.

LAT$_ITM_TARGET_PORT_NAMEThe port name.

LAT$_ITM_TARGET_SERVICE_NAMEThe service name.

The queued status of the connection can also be mapped to the port by specifying
the LAT$_ITM_QUEUED item in the P1 itemlist parameter. Valid values for this
item are:

LAT$C_ENABLEDPort has queued status. This is the default.

LAT$C_DISABLEDThe port does not have queued status.

576 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
5.4.4.6 Programming Application Services and Dedicated Ports
Rather than the normal timesharing service offered by the operating system,
application programs can make use of LAT application services that allow
terminal server users (or users on sytems with outgoing connections) to connect to
a specialized application. To do this, the system manager must create LAT ports
that are dedicated to a particular application service. (Alternatively, this LAT
port creation can be done from a program using the QIOs discussed in previous
sections, providing OPER privilege.) When the remote user makes the connection
to the application service, the connection is directly to the application program
that controls a LAT port (LTA device) associated with the service. In this case the
prompt, Username:, is not received. Compaq recommends that you follow these
steps to create an application service:
1. Define the dedicated ports in LAT$SYSTARTUP.COM and execute the
command procedure in SYSTARTUP_VMS.COM. (Refer to the OpenVMS
System Management Utilities Reference Manual and the OpenVMS System
Managers Manual for additional information.)
2. Run the application program. Within the application program,
allocate dedicated ports with the same name as those defined in
LAT$SYSTARTUP.COM. Use the Assign I/O Channel ($ASSIGN) system
service to assign service channels to the ports.
3. Post a read request to the dedicated ports. When the terminal user connects
to the service and presses the Return key, the application program can
perform I/O to the dedicated port.
4. To break the connection, use the Deassign I/O Channel ($DASSGN) system
service to deassign the channel and the Deallocate Device ($DALLOC) system
service to deallocate the device. The application program must reallocate the
port and reassign the channel in preparation for the next connection.
An example of the application service concept is a program that provides the
time of day. For this example, the system manager includes the following lines in
LAT$SYSTARTUP.COM (or enters them manually in the LATCP program):
CREATE SERVICE TIME/ID="At the tone, the time will be"/APPLICATION
CREATE PORT LTA99:/DEDICATED
SET PORT LTA99:/SERVICE=TIME
An application program then assigns a channel to device LTA99. When a
terminal server user types CONNECT TIME, the user is connected to this
application program, and the program prints out the time of day. The program
then deassigns the channel, which disconnects the server user.
A system manager may associate more than one LAT port with the same service.
In that case, the application program that offers the service should assign
channels to all of the LTA devices created for that service.
5.4.4.7 Programming Forward Ports
An outbound LAT connection to a remote service node can be made using a
forward port. The LAT port driver can connect to a remote service node only if
outgoing connections are enabled on the local node. Outgoing connections can
be enabled with LATCP or with a LAT SETMODE QIO to the local node. In
addition, user group codes on the local node must match the service group codes
of the service to which they are being connected. LATCP can list the services to
which the local node can connect. (Refer to the OpenVMS System Management
Utilities Reference Manual for additional information.) Before the forward port
can be used to make an outbound LAT connection, it must be mapped to a service
Terminal Driver 577

Terminal Driver
5.4 Terminal Function Codes
and optionally, a node and port. The forward port is mapped with the IO$M_LT_
SETMODE modifier, specifying the following items in the P1 item list parameter:

LAT$_ITM_TARGET_SERVICE_NAMEThe service name. The service

name is the name of the service to which to connect.

LAT$_ITM_TARGET_NODE_NAMEThe node name. The node name is the

name of a specific service node offering the service.

LAT$_ITM_TARGET_PORT_NAMEThe port name. The port name is the

name of a specific port on the target node. The LAT$_ITM_TARGET_NODE_
NAME item must be supplied when supplying this item.

LAT$_ITM_SERVICE_PASSWORDThe password. The password is required

for access to a password-protected service.

A LAT SETMODE QIO on a forward port does not require OPER privilege if
the port name is not specified in the P4 parameter. In other words, the LAT
SETMODE QIO must be to the port corresponding to the CHAN parameter (the
forward port attained by assigning a channel to _LTA0:). Note that SS$_NOPRIV
is returned if you attempt to change the port type by specifying the LAT$_ITM_
PORT_TYPE item code in the P1 itemlist parameter. If the P4 parameter is
specified, the LAT port driver also returns SS$_NOPRIV.
Table 530 lists the conditions that can occur when an application program issues
an IO$M_LT_CONNECT request for a connection to a remote service node. The
QIO request is completed when a session is established with the service node.
Once the connection completes, data can be read and written to the port with the
QIO read and write functions.
5.4.4.8 Queue Change Notification (Alpha Only)
On Alpha systems, the IO$M_LT_QUE_CHG_NOTIF function modifier for $QIO
allows a process to enable an attention asynchronous system trap (AST), which
is used with the LAT $QIO connect request. The IO$M_LT_QUE_CHG_NOTIF
function is available only for APPLICATION and FORWARD LAT devices.
If a $QIO connect request has been issued to a remote node and that request has
been queued, this attention AST will be set each time the queue position changes.
This AST can be used as long as the $QIO connect request is queued. Like a
Ctrl/Y AST, it is set only once; it must be reenabled after each completion.
If the LAT $QIO connect succeeds or if a LAT connection exists for the intended
service, the AST completes with the SS$_DEVACTIVE status code.
If the LAT device does not have the queued characteristic, issuing the IO$M_LT_
QUE_CHG_NOTIF function results in the return of SS$_DEVREQERR status
code.
The implementation of IO$M_LT_QUE_CHG_NOTIF is shown in the following C
example:

578 Terminal Driver

Terminal Driver
5.4 Terminal Function Codes
status - sys$qiow (
0,
/* efn
ltchannel,
/* channel
IO$_TTY_PORT|IO$M_LT_QUE_CHG_NOTIF,
/* function
q_iosb,
/* iosb
0,
/* astadr
0,
/* astprm
queue_pos_change, /* P1 = ast routine
0, 0, 0, 0, 0);
/* P2 through P6 not

*/
*/
*/
*/
*/
*/
*/
used */

When a queue position change occurs, the AST routine is called with a 32-bit
value. If this value is 0, then the LAT connect $QIO is about to complete, if it has
not already. If the value is not 0, the lower word of 16 bits indicates the service
queue position, and the upper word of 16 bits indicates the node queue position.
5.4.4.9 Hangup Notification
To allow notification by the terminal driver of abnormal termination during I/O
operations, enable a Ctrl/Y AST on the channel. This ensures that the terminal
driver notifies application programs of an abnormal connection termination. Note
that the operating system does not return an AST parameter to the Ctrl/Y AST
routine.
When an application with a pending read or write request has an abnormal
LAT connection completion, the terminal driver returns a SS$_HANGUP status
in the first word of the IOSB. The reason for the abnormal LAT connection
completion can be attained with a LAT SENSEMODE QIO request to the port.
Search the resulting P1 itemlist for the value corresponding to the LAT$_ITM_
DISCONNECT_REASON item code. The value is either a LAT reject code or
a LAT facility message. The LAT$V_SENSE_FULL bit must be set in the P3
parameter in order to receive this information.
If IOSB indicates an abnormal completion (SS$_ABORT, see Table 530) on a
IO$M_LT_CONNECT modifier QIO, the LAT port driver returns the reason for
the abnormal completion in IOSB+2. The reason can also be attained with the
LAT SENSEMODE QIO function.

5.4.5 Sense Mode and Sense Characteristics

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

IO$_SENSEMODE

IO$_SENSECHAR

IO$_SENSEMODE returns the temporary characteristics of the terminal (the

characteristics associated with the current process), and IO$_SENSECHAR
returns the permanent characteristics of the terminal. IO$_SENSEMODE is a
logical I/O function and requires no privilege. IO$_SENSECHAR is a physical I/O
function and requires the privilege necessary to perform physical I/O.
These function codes take the following device- or function-dependent arguments:

P1Address of a characteristics buffer

P2Length of characteristics buffer (default length is 8 bytes)

For remote terminals, specify a P2 value of 8 or 12 only.

Terminal Driver 579

Terminal Driver
5.4 Terminal Function Codes
Figure 511 Sense Mode Characteristics Buffer
31

24 23

16 15

Buffer Size *

8 7
Type

Page Length

0
Class

Basic Terminal Characteristics

Extended Terminal Characteristics

* Page Width

P2 = 12
ZK0693GE

The P1 argument points to a variable-length block, as shown in Figure 511.

In the buffer, the device class is DC$_TERM, which is defined by the $DCDEF
macro. The terminal type is defined by the $TTDEF macro, such as TT$_LA36.
The maximum entry for the buffer size (page width) is 255. Table 55 lists
the values for terminal characteristics. Table 56 lists the extended terminal
characteristics. Characteristics values are defined by the $TTDEF macro.
The sense mode and sense characteristics functions can take the type-ahead
count, read modem, and broadcast function modifiers described in the following
sections.
5.4.5.1 Type-ahead Count Function Modifier
The type-ahead count function modifier 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 P1 argument points to a characteristics buffer returned by IO$M_
TYPEAHDCNT. Figure 512 shows the format of this buffer.
Figure 512 Sense Mode Characteristics Buffer (type-ahead)
31

24 23
(Reserved)

16 15
First Character

Number of Characters in TypeAhead Buffer

(Reserved)
ZK0694GE

5.4.5.2 Read Modem Function Modifier

The read modem function modifier allows access to controller-dependent
information. The following combinations of function code and modifier are
provided:

IO$_SENSEMODE!IO$M_RD_MODEM

IO$_SENSECHAR!IO$M_RD_MODEM

These function code modifier pairs take the following device- or functiondependent argument:

580 Terminal Driver

P1The address of a quadword block

Terminal Driver
5.4 Terminal Function Codes
Figure 513 shows the format of this block.
Figure 513 Sense Mode P1 Block
31
P1:

24 23

16 15

Receive Modem

8 7

Controller Type

ZK0695GE

The receive modem field returns the value of the current input modem signals.
Any or all of the following signals can be returned:

TT$M_DS_DSRData set ready (DSR)

TT$M_DS_RINGCalling indicator (RING)

TT$M_DS_CARRIERData channel received line signal detector (CARRIER)

TT$M_DS_CTSReady for sending (CTS)

TT$M_DS_SECRECReceived backward channel data (Sec RxD)

The $TTDEF macro defines the symbols for the receive modem field.
The controller type field returns the type of terminal controller in use by the
currently active terminal line. The $DCDEF macro defines the symbols for the
following types of controllers:

DT$_DZ11DZ11 and DZV11

DT$_DZ32DZ32

DT$_DMF32DMF32

DT$_DMB32DMB32

DT$_DMZ32DMZ32

DT$_DHVDHV11

DT$_DHUDHU11

DT$_LATLAT server
Note 1
For LAT devices, the receive modem field of the IO$M_RD_MODEM
function modifier does not return any valid modem signal data.

Note 2
The IO$M_RD_MODEM function modifier is not supported for remote
terminals. The status SS$_DEVREQERR is returned in the I/O status
block.

Terminal Driver 581

Terminal Driver
5.4 Terminal Function Codes
5.4.5.3 Broadcast Function Modifier
The broadcast function modifier returns those bits that have been set by the set
mode function modifier IO$M_BRDCST (see Table 512 in Section 5.4.3.6). The
following combination of function code and modifier is provided:

IO$_SENSEMODE!IO$M_BRDCST

This function code modifier pair takes the following device- or function-dependent
arguments:
P1A buffer that contains the bits that specify the requester IDs to be
broadcast. (If the bit is set in the first longword, that particular command is
turned off for broadcast.)
P2The length of the P1 buffer.

5.5 I/O Status Block

The I/O status block (IOSB) formats for the read, write, set mode, set
characteristics, sense mode, sense characteristics, and LAT port driver I/O
functions are shown in Figures 514, 516, 517, and 518. Figure 515 shows
the IOSB format for the itemlist read function. Appendix A lists the status
returns for these functions. (The OpenVMS system messages documentation
provides explanations and suggested user actions for these returns.)
In Figure 514, the offset to terminator at IOSB+2 is the count of characters
before the terminator character (see Section 5.4.1.2). The terminator character
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. In the case of multiple character escape sequences that act as
terminators, the terminator at IOSB+4 is the first character (ESC) of the escape
sequence. IOSB+6 contains the size of the terminator string, usually 1. However,
in an escape sequence, IOSB+6 contains the size of the validated escape sequence
(see Section 5.2.1.4). The sum of IOSB+2 and IOSB+6 is the number of characters
in the buffer.
Figure 514 IOSB ContentsRead Function
+2

IOSB

Offset to Terminator

Status

Terminator Size

Terminator
+6

+4
ZK0696GE

In Figure 515 the terminator position word contains a number, the character
of which is determined by the mode of operation. For itemlist read operations
that do not specify TRM$K_EM_RDVERIFY, this word contains the number
of characters from the end of the buffer to the cursor location at the time the
terminator character was received. If TRM$K_EM_RDVERIFY is specified, the
terminator position word contains the offset into the buffer from the nonverified
character.

582 Terminal Driver

Terminal Driver
5.5 I/O Status Block
Figure 515 IOSB ContentsItemlist Read Function

Offset to Terminator

Cursor Position
from EOL

Terminator
Length

Status

Terminator
Character

(Reserved)

IOSB Contents: Itemlist Read Function

ZK1306GE

The byte at IOSB+5 passes the status information, listed in Table 531,
on TRM$K_EM_RDVERIFY operations in which TRM$M_TM_ARROWS or
TRM$M_TM_TOGGLE is set in TRM$_MODIFIERS.
Table 531 Byte IOSB+5 Status Information
Bit

Interpretation

7 (sign bit)

0 to indicate rest of bits valid. This applies to

insert/overstrike and arrow key read verify
functionality only.

62

Always 0 if bit 7 is equal to 0. Not used; reserved for

future use.

1 TRM$V_ST_OTHERWAY

Set to indicate that read is terminated in left-justify

insert mode or right-justify overstrike mode.

0 TRM$V_ST_FIELD_FULL

Read terminated on an auto-tab field full condition.

IOSB+7 contains an index to the cursor.

In Figure 516, the remote terminal driver does not return the number of lines
output or the cursor position.
Figure 516 IOSB ContentsWrite Function

Byte Count

Status

0
IOSB Contents: Write Function
ZK1307GE

In Figure 517, the TTdriver attempts to return the correct data in IOSB after a
SETMODE or SETCHAR. To be sure the returned data is correct, the user should
follow the SETMODE or SETCHAR with a SENSEMODE or SENSECHAR.

Terminal Driver 583

Terminal Driver
5.5 I/O Status Block
Figure 517 IOSB ContentsSet Mode, Set Characteristics, Sense Mode, and
Sense Characteristics Functions
Receive Speed * Transmit Speed
0

Parity Flags

Status
LF Fill Count

CR Fill Count

* Only specified if different than transmit speed.

ZK0698GE

When an application program makes an I/O request for a connection to a remote

device on a terminal server, the LAT port driver places status information about
the request into the first word of the I/O status block, as shown in Figure 518.
Table 530 lists the possible status returns.
If the server rejects the request, the LAT port driver returns a numeric LAT
rejection code in the second word of the I/O status block. Table 532 lists the LAT
rejection codes.
Figure 518 IOSB ContentsLAT Port Driver Function
+2
Rejection Code
(Reserved)

0
Status
(Reserved)
ZK6135GE

Table 532 LAT Rejection Codes

Value

Reason

Reason is unknown.

User requested disconnect.

System shutdown in progress.

Invalid slot received.

Invalid service class received.

Insufficient resources to satisfy request.

Service in use.

No such service.

Service is disabled.

Service is not offered on the requested port.

10

Port name is unknown.

11

Invalid password.

12

Entry is not in queue.

(continued on next page)

584 Terminal Driver

Terminal Driver
5.5 I/O Status Block
Table 532 (Cont.) LAT Rejection Codes
Value

Reason

13

Immediate access rejected (server queue full).

14

Access denied (group code mismatch).

15

Corrupted solicit request.

16

COMMAND_TYPE code is illegal/not supported.

17

Start slot cannot be sent.

18

Queue entry deleted by local node.

19

Inconsistent or illegal request parameters.

Terminal Driver 585

Terminal Driver
5.6 Terminal Driver Programming Examples

5.6 Terminal Driver Programming Examples

The VAX C program LAT.C shown in Example 51 initiates and maintains an
outbound LAT session from the local node. It demonstrates the following LAT
$QIO functions:

Cloning the LAT template device (LTA0:)

IO$M_LT_SETMODE

IO$M_LT_CONNECT (on forward port)

IO$M_LT_SENSEMODE

Example 51 LAT.C Terminal Driver Programming Example

#module LAT_FORWARD_CONNECT "X1.0-001"
/*
**++
**
** MODULE DESCRIPTION:
**
**
In initiating and maintaining an outbound LAT session from the local
**
node, this program demonstrates the following LAT $QIO functions:
**
**
o Cloning the LAT template device (LTA0:)
**
o IO$M_LT_SETMODE
**
o IO$M_LT_CONNECT (on forward port)
**
o IO$M_LT_SENSEMODE
**
**-*/
/*
**
** INCLUDE FILES
**
*/
#include <descrip>
#include <iodef>
#include <latdef>
#include <ssdef>

/*
/*
/*
/*

VMS Descriptor Definitions

*/
I/O Function Codes Definitions */
LAT Definitions
*/
System Service Return Status
*/
/* Code Definitions
#include <ttdef> /* Terminal Characteristics
*/
#include <tt2def> /* Terminal Extended
*/
/* Characteristics
/*
**
** MACRO DEFINITIONS
**
*/

*/
*/

/*
** Service name which the session will be to.
*/
#define SERVICE_NAME
"LAT_SERVICE"
#define SERVICE_NAME_LENGTH 11
(continued on next page)

586 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
**
**
**
**
**
**
**
**
**
**
**
**
**
**
*/

For the sake of clarity, the sizes of the buffers used for reading from
and writing to the LTA and TT devices are set to the values below. In
order to gain maximum throughput from this program, the following system
parameters can be set:
o TTY_ALTYPAHD - 1500
o TTY_TYPAHDSZ - 80
To get the best performance from this program without touching these
system parameters on your system, modify the program to set the size of
the buffers to the following:
o LTA_BUFFER_SIZE = MIN(TTY_ALTYPAHD, 1500)
o TT_BUFFER_SIZE = MIN(TTY_TYPAHDSZ, 132)

#define LTA_MAXBUF
#define TT_MAXBUF

1500
80

/*
** Size of the LAT SENSEmode itemlist.
*/
#define MAX_SENSE_ITEMLIST_SIZE 1500
/*
** Character user can press to terminate the LAT connection (CTRL+\).
*/
#define CONNECTION_TERMINATOR

0x1C

/*
**
** FUNCTION PROTOTYPES
**
*/
unsigned long
void
void
void
void
void
void

SetDeviceChars(void);
ConnectAST(void);
LTAreadChannelAST(void);
TTreadChannelAST(void);
LTAhangupHandler(void);
EndSession(void);
ExitHandler(void);

/*
**
** GLOBAL DATA
**
*/
char

*LTAbuffer, /* LTA device I/O buffer

*TTbuffer, /* TT device I/O buffer

*/
*/

/*
** Text for LAT reject codes. Note that some LAT
** implementations will return a 0 reject code to
** indicate a normal disconnect.
*/

(continued on next page)

Terminal Driver 587

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
*LATrejectTable[] = {
"Unknown",
"User requested disconnect",
"System shutdown in progress",
"Invalid slot received",
"Invalid service class received",
"Insufficient resources at server",
"Port or service in use",
"No such service",
"Service is disabled",
"Service is not offeredon the requested port",
"Port name is unknown",
"Invalid service password",
"Remote entry is not in queue",
"Immediate access rejected",
"Access denied",
"Corrupted request",
"Requested function is not supported",
"Session cannot be started",
"Queue entry deleted by server",
"Illegal request parameters"
};
unsigned short LTAchannel,
TTchannel,
LTA_QIOiosb[4],
TT_QIOiosb[4];
unsigned long

/*
/*
/*
/*

LTA device I/O channel

TT device I/O channel
IOSB for LTA device functions
IOSB for TT device functions

*/
*/
*/
*/

ReadTerminatorMask[2] = { 0, 0 },
/* $QIO read terminator mask
*/
SavedTTdeviceChar[3],
/* Saved TT device characteristics
*/
DeviceCharBuffSize = sizeof(SavedTTdeviceChar);
/* Size of device characteristics buffer*/
ExitConditionValue, /* Exit condition value of program
*/
LATrejectTableSize =/* Number of elements in LAT reject tbl */
sizeof(LATrejectTable) / sizeof(LATrejectTable[0]);

/*
** Itemlist for setting LAT port with the target service name.
*/
struct {
unsigned short item_code;
char
item_byte_count;
char
item_value[ SERVICE_NAME_LENGTH ];
} PortSetmodeItemlist = {
LAT$_ITM_TARGET_SERVICE_NAME, SERVICE_NAME_LENGTH, SERVICE_NAME
};
/*
** Exit handler block.
*/
struct {
unsigned long
void
unsigned long
unsigned long
} ExitHandlerBlock = {

flink;
(*exit_handler)();
arg_count;
*exit_status;
0, ExitHandler, 1, &ExitConditionValue };
(continued on next page)

588 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
** Devices which channels are assigned to.
*/
$DESCRIPTOR(LTAtemplateDSC, "LTA0:");
$DESCRIPTOR(TTchannelDSC, "SYS$COMMAND");
main()
{
/*
** Local Variables:
*/
unsigned long

status,
portSetmodeItemlistSize = sizeof(PortSetmodeItemlist);

/*
** BEGIN:
**
** Declare an exit handler.
*/
if (!((status = sys$dclexh(&ExitHandlerBlock)) & 1))
lib$signal(status);
/*
** Assign a channel to LTA0: to get a forward LAT port and assign a
** channel to the terminal.
*/
if (!((status = sys$assign(&LTAtemplateDSC, &LTAchannel, 0, 0)) & 1))
lib$signal(status);
if (!((status = sys$assign(&TTchannelDSC, &TTchannel, 0, 0)) & 1))
lib$signal(status);
/*
** Allocate memory for the channel data buffers.
*/
LTAbuffer = malloc(LTA_MAXBUF);
TTbuffer = malloc(TT_MAXBUF);
/*
** Set device characteristics for the two channels.
*/
if (!((status = SetDeviceChars()) & 1))
lib$signal(status);
/*
** Do SETmode $QIO to set the port entity with the target service name
** specified in the item list.
*/

(continued on next page)

Terminal Driver 589

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_TTY_PORT|IO$M_LT_SETMODE,
&LTA_QIOiosb, 0, 0,
&PortSetmodeItemlist,
portSetmodeItemlistSize,
LAT$C_ENT_PORT|(LAT$C_ENTS_OLD << 0x10),
0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
/*
** Enable a CTRL+Y AST on the LAT channel.
*/
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_SETMODE|IO$M_CTRLYAST,
&LTA_QIOiosb, 0, 0,
LTAhangupHandler,
0, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
/*
**
**
**
**
*/

Post the first

first burst of
important that
$QIO to ensure

read (with AST) on the LTA device to ensure that the

data from the target service is not lost. It is very
the first read is queued before doing the connect
no data lossage.

if (!((status = sys$qio(
0,
LTAchannel,
IO$_READVBLK|IO$M_NOECHO,
&LTA_QIOiosb,
LTAreadChannelAST, 0,
LTAbuffer,
1, 0, &ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
/*
** Do the LAT connect $QIO and hibernate until program exit. The
** ConnectAST will execute when the connection completes and post the
** initial read on the TT channel.
*/
if (!((status = sys$qio(
0,
LTAchannel,
IO$_TTY_PORT|IO$M_LT_CONNECT,
&LTA_QIOiosb,
ConnectAST, 0, 0, 0, 0, 0, 0, 0)) & 1))
lib$signal(status);
sys$hiber();
}

/* END - main() */

(continued on next page)

590 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine sets device characteristics of the LTA and TT devices.
**
The HOSTSYNC, NOBRDCST, EIGHTBIT and PASTHRU characteristics are set
** on the LTA device. The ESCAPE and TTSYNC characteristics are cleared.
**
**
The TTSYNC, HOSTSYNC, EIGHTBIT, and PASTHRU characteristics are set
**
on the TT device. The ESCAPE characteristic is cleared. The TT
**
characterisitcs are also saved for restoration at program exit.
**
**-*/
unsigned long SetDeviceChars(void)
{
/*
** Local Variables:
*/
unsigned long

status,
deviceChar[3];

/*
** BEGIN:
**
** Mask and set the characteristics of the LTA device. Sense the
** current characteristics, and mask in and set the new ones.
*/
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_SENSEMODE,
&LTA_QIOiosb, 0, 0,
&deviceChar,
DeviceCharBuffSize, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
deviceChar[1] =
(deviceChar[1] | (TT$M_HOSTSYNC | TT$M_NOBRDCST | TT$M_EIGHTBIT))
& ~TT$M_ESCAPE & ~TT$M_TTSYNC;
deviceChar[2] |= TT2$M_PASTHRU;
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_SETMODE,
&LTA_QIOiosb, 0, 0,
&deviceChar,
DeviceCharBuffSize, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
(continued on next page)

Terminal Driver 591

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
** Repeat the procedure for TT device characteristics. However, save
** the current characteristics for restoration at program exit.
*/
if (!((status = sys$qiow(
0,
TTchannel,
IO$_SENSEMODE,
&TT_QIOiosb, 0, 0,
&SavedTTdeviceChar,
DeviceCharBuffSize, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(TT_QIOiosb[0] & 1))
lib$signal(TT_QIOiosb[0]);
deviceChar[0] = SavedTTdeviceChar[0];
deviceChar[1] = (SavedTTdeviceChar[1] |
(TT$M_TTSYNC | TT$M_HOSTSYNC | TT$M_EIGHTBIT)) & ~TT$M_ESCAPE;
deviceChar[2] = SavedTTdeviceChar[2] | TT2$M_PASTHRU;
if (!((status = sys$qiow(
0,
TTchannel,
IO$_SETMODE,
&TT_QIOiosb, 0, 0,
&deviceChar,
DeviceCharBuffSize, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(TT_QIOiosb[0] & 1))
lib$signal(TT_QIOiosb[0]);
return(status);
}

/* END - SetDeviceChars */

/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine is an AST which executes when the connect $QIO completes.
**
First the IOSB is checked. If the connection timed out or was aborted,
**
simply end the session. Any other abnormal status causes the program
**
to exit.
**
**
Otherwise the connection completed successfully and a read on the TT
**
channel is posted.
**
**-*/
void
{

ConnectAST()
/*
** Local Variables:
*/
unsigned long

status;

(continued on next page)

592 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
**
**
**
**
**
*/

BEGIN:
If the status in the IOSB indicates that the connection timed out
or aborted, call the session end routine. Any other abnormal
status causes program exit.

if ((LTA_QIOiosb[0] == SS$_TIMEOUT) || (LTA_QIOiosb[0] == SS$_ABORT))

EndSession();
if (!(LTA_QIOiosb[0] & 1))
sys$exit(LTA_QIOiosb[0]);
/*
** The connection completed successfully! Post a read (with AST) on
** the TT device and return.
*/
if (!((status = sys$qio(
0,
TTchannel,
IO$_READVBLK|IO$M_NOECHO,
&TT_QIOiosb,
TTreadChannelAST, 0,
TTbuffer,
1, 0, &ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
return;
}

/* END - ConnectAST */

/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine is an AST which executes when the first character read on
**
the LTA channel completes. It does a "flush" read of the channel to
**
drain any data out of the ALTYPAHD buffer and writes the data to the
**
TT channel. It then posts another read on the channel.
**
**-*/
void
{

LTAreadChannelAST(void)
/*
** Local Variables:
*/
unsigned long

status;

/*
** BEGIN:
**
** If the status in the IOSB indicates channel hangup, simply end the
** session. Signal any other abnormal status.
*/
(continued on next page)

Terminal Driver 593

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
if (LTA_QIOiosb[0] == SS$_HANGUP)
EndSession();
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
/*
** Do a "flush" read of the LTA device. This is done by doing a timed
** read with a 0 timeout. There may or may not be any data to drain.
** This method is more efficient than using single character reads.
*/
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_READVBLK|IO$M_TIMED|IO$M_NOECHO,
&LTA_QIOiosb, 0, 0,
LTAbuffer+1,
LTA_MAXBUF-1, 0,
&ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1) && (LTA_QIOiosb[0] != SS$_TIMEOUT))
lib$signal(LTA_QIOiosb[0]);
/*
** The second word of the IOSB contains the number of characters
** read. Write the characters plus 1 for the initial read to the
** TT device.
*/
if (!((status = sys$qiow(
0,
TTchannel,
IO$_WRITEVBLK,
&TT_QIOiosb, 0, 0,
LTAbuffer,
LTA_QIOiosb[1]+1, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(TT_QIOiosb[0] & 1))
lib$signal(TT_QIOiosb[0]);
/*
** Post another read on the LTA device.
*/
if (!((status = sys$qio(
0,
LTAchannel,
IO$_READVBLK|IO$M_NOECHO,
&LTA_QIOiosb,
LTAreadChannelAST, 0,
LTAbuffer,
1, 0, &ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
return;
}

/* END - LTAreadChannelAST */

(continued on next page)

594 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine is an AST which executes when the first character read on
**
the TT channel completes. It does a "flush" read of the channel to
**
drain any data out of the TYPAHD buffer and writes the data to the
**
LTA channel. It then posts another read on the channel.
**
**-*/
void
{

TTreadChannelAST(void)
/*
** Local Variables:
*/
unsigned long

status;

/*
** BEGIN:
**
** If the user pressed the connection terminator character, do a LAT
** disconnect $QIO and exit.
*/
if (*TTbuffer == CONNECTION_TERMINATOR)
{
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_TTY_PORT|IO$M_LT_DISCON,
&LTA_QIOiosb, 0, 0, 0, 0, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
return;
}
/*
** Do a "flush" read of the TT device. This is done by doing a timed
** read with a 0 timeout. There may or may not be any data to drain.
*/
if (!((status = sys$qiow(
0,
TTchannel,
IO$_READVBLK|IO$M_TIMED|IO$M_NOECHO,
&TT_QIOiosb, 0, 0,
TTbuffer+1,
TT_MAXBUF-1, 0,
&ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
if (!(TT_QIOiosb[0] & 1) && (TT_QIOiosb[0] != SS$_TIMEOUT))
lib$signal(TT_QIOiosb[0]);

(continued on next page)

Terminal Driver 595

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
** The second word of the IOSB contains the number of characters
** read. Write the characters plus 1 for the initial read to the
** TT device.
*/
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_WRITEVBLK,
&LTA_QIOiosb, 0, 0,
TTbuffer,
TT_QIOiosb[1]+1, 0, 0, 0, 0)) & 1))
lib$signal(status);
/*
** If the status in the IOSB indicates channel hangup, simply end
** the session. Signal any other abnormal status.
*/
if (LTA_QIOiosb[0] == SS$_HANGUP)
EndSession();
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
/*
** Post another read on the LTA device.
*/
if (!((status = sys$qio(
0,
TTchannel,
IO$_READVBLK|IO$M_NOECHO,
&TT_QIOiosb,
TTreadChannelAST, 0,
TTbuffer,
1, 0, &ReadTerminatorMask, 0, 0)) & 1))
lib$signal(status);
return;
}

/* END - TTreadChannelAST */

/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine is the CTRL+Y AST for the LTA channel. It executes when
**
a hangup on the LTA channel is recognized (connection timed out or
**
aborted). It will call the session end routine if it hasnt already
**
been called by ConnectAST.
**
**
NOTE: CTRL+Y ASTs for application ports will NOT execute when the
**
connection is disconnected.
**
**-*/
(continued on next page)

596 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
void
{

LTAhangupHandler(void)
/*
** BEGIN:
**
** Call the session end routine and return.
*/
EndSession();
return;

/* END - LTAhanghupHandler */

/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This routine is executed at session end. It will do a $QIO SENSEmode
**
and search the resulting itemlist to find the reason for the LAT
**
disconnect. The reason for the disconnect is displayed on the
**
terminal and the image exits.
**
**-*/
void
{

EndSession(void)
/*
** Local Variables:
*/
struct ITEM_ENTRY
unsigned long
char

*itemlistEntry;
status;
*senseItemlist = malloc(MAX_SENSE_ITEMLIST_SIZE),
*itemlistEntryPointer;

/*
** BEGIN:
**
** Do the SENSEmode on the port.
*/
if (!((status = sys$qiow(
0,
LTAchannel,
IO$_TTY_PORT|IO$M_LT_SENSEMODE,
&LTA_QIOiosb, 0, 0,
senseItemlist,
MAX_SENSE_ITEMLIST_SIZE,
LAT$C_ENT_PORT|(LAT$M_SENSE_FULL << 0x10),
0, 0, 0)) & 1))
lib$signal(status);
if (!(LTA_QIOiosb[0] & 1))
lib$signal(LTA_QIOiosb[0]);
/*
** Set up two pointers used to traverse the itemlist.
*/
itemlistEntry = (struct ITEM_ENTRY *) senseItemlist;
itemlistEntryPointer = senseItemlist;
(continued on next page)

Terminal Driver 597

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
** Search the itemlist for the LAT$_ITM_DISCONNECT_REASON code to find
** out why the connection terminated.
*/
while (itemlistEntry->LAT$R_ITM_CODE.LAT$W_ITEMCODE !=
LAT$_ITM_DISCONNECT_REASON)
{
/*
** If the current itemcode being checked has a string value,
** advance the pointer to the next itemcode by skipping
** BCNT bytes plus 3 bytes for the BCNT byte itself and the
** 2 byte itemcode.
*/
if (itemlistEntry->
LAT$R_ITM_CODE.LAT$R_ITM_BITS.LAT$V_STRING)
itemlistEntryPointer +=
itemlistEntry->LAT$R_ITEM_VALUE.
LAT$R_ITEM_COUNTED_STRING.LAT$B_ITEM_BCNT + 3;
/*
** If the current itemcode being checked has a scalar value,
** advance the pointer to the next itemcode by skipping 6
** bytes for the itemcode and the 4 byte scalar.
*/
else
itemlistEntryPointer += 6;
itemlistEntry = (struct ITEM_ENTRY *) itemlistEntryPointer;
}
/*
** If the disconnect reason is a LAT reject code, print out the
** text corresponding to the code and set the exit condition value
** to SS$_NORMAL.
*/
if (itemlistEntry->LAT$R_ITEM_VALUE.LAT$L_ITEM_SCALAR_VALUE <=
LATrejectTableSize)
{
printf("\nSession disconnected. Reason: %s\n\n\n",
LATrejectTable[ itemlistEntry->LAT$R_ITEM_VALUE.
LAT$L_ITEM_SCALAR_VALUE ]);
ExitConditionValue = SS$_NORMAL;
}
/*
** The scalar value is a LAT facility message code. Set the exit
** condition value to be the scalar. Upon image exit, the
** corresponding LAT facility message will be displayed.
*/
else
ExitConditionValue =
itemlistEntry->LAT$R_ITEM_VALUE.LAT$L_ITEM_SCALAR_VALUE;
sys$exit(ExitConditionValue);
}

/* END - EndSession */

(continued on next page)

598 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 51 (Cont.) LAT.C Terminal Driver Programming Example
/*
**++
**
** FUNCTIONAL DESCRIPTION:
**
**
This is the program exit handler which is executed upon image exit.
**
It will cancel all pending I/O on the two channels and restore the
**
TT channel characteristics.
**
**-*/
void
{

ExitHandler(void)
/*
** Local Variables:
*/
unsigned long

status;

/*
** BEGIN:
**
** Cancel I/O on the channels, reset terminal characteristics and
** return.
*/
if (!((status = sys$cancel(LTAchannel)) & 1))
lib$signal(status);
if (!((status = sys$cancel(TTchannel)) & 1))
lib$signal(status);
if (!((status = sys$qiow(
0,
TTchannel,
IO$_SETMODE,
&TT_QIOiosb, 0, 0,
&SavedTTdeviceChar,
DeviceCharBuffSize, 0, 0, 0, 0)) & 1))
lib$signal(status);
if (!(TT_QIOiosb[0] & 1))
lib$signal(TT_QIOiosb[0]);
return;
}

/* END - ExitHandler */
The VAX MACRO program FULL_DUPLEX_TERMINAL.MAR (Example 52)
shows several I/O operations using the full-duplex capabilities of the
terminal. This program shows some important concepts about terminal driver
programming: assigning an I/O channel, performing full-duplex I/O operations,
enabling Ctrl/C AST requests, and itemlist read operations. The program is
designed to run with a terminal set to full-duplex mode.
The initialization code queues a read request to the terminal and enables Ctrl/C
AST requests. The main loop then prints out a random message every three
seconds. When you enter a message on the terminal, the read AST routine prints
an acknowledgment message and queues another read request. If you press
Ctrl/C, the associated AST routine cancels the I/O operation on the assigned
channel and exits to the command interpreter.

Terminal Driver 599

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
.TITLE FULL_DUPLEX TERMINAL PROGRAMMING EXAMPLE
.IDENT /05/
; ********************************************************************
;
;
TERMINAL PROGRAM
;
; ********************************************************************
.SBTTL DECLARATIONS
.DISABLE
GLOBAL
;
; Declare the external symbols and MACRO libraries.
;
.EXTERNAL
.LIBRARY
.LIBRARY

LIB$GET_EF
SYS$LIBRARY:LIB.MLB
SYS$LIBRARY:STARLET.MLB

;
; Define symbols
;
$IODEF
$QIODEF
$SSDEF
$TRMDEF
$TTDEF
;
; Define macros
;
.SHOW
.MACRO
.WORD
.WORD
.LONG
.LONG
.ENDM
.NOSHOW

;
;
;
;
;

Define I/O function codes

Define QIO definition codes
Define the system service status codes
Define itemlist read codes
Terminal characteristic definitions

ITEM
LEN=0,CODE,VALUE
LEN
TRM$_CODE
VALUE
0
ITEM

;
; Declare exit handler control
;
EXIT_HANDLER_BLOCK:
.LONG 0
.LONG EXIT_HANDLER
.LONG 1
.LONG STATUS
STATUS: .BLKL 1

block
;
;
;
;
;

System uses this for pointer

Address of exit handler
Argument count for handler
Destination of status code
Status code from $EXIT

;
; Allocate terminal descriptor and channel number storage
;
TT_DESC:
.ASCID /SYS$INPUT/
TT_CHAN:
.BLKW 1

; Logical name of terminal

; TT channel number storage
(continued on next page)

5100 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
;
; Define acknowledgment message. This is done right above input buffer
; so that we can concatenate the two together when the acknowledgment
; message is issued.
;
ACK_MSG:
.ASCII <CR><LF> /Following input acknowledged: /
ACK_MSGLEN=.-ACK_MSG
; Calculate length of message
;
; Allocate input buffer
;
IN_BUFLEN = 20
; Set length of buffer
IN_BUF:
.BLKB IN_BUFLEN
; Allocate character buffer
IN_IOSB:
.BLKQ 1
; Input I/O status block
;
; Define out-of-band ast character mask
;
CNTRLA_MASK:
.LONG 0
.LONG ^B0010
; Control A mask
;
; Define old terminal characteristics buffer
;
OLDCHAR_BUF_LEN = 12
OLDCHAR_BUF:
.BLKB OLDCHAR_BUF_LEN
;
; Define new terminal characteristics buffer
;
NEWCHAR_BUF_LEN = 12
NEWCHAR_BUF:
.BLKB NEWCHAR_BUF_LEN
;
; Define carriage control symbols
;
CR=^X0D
LF=^X0A
;
;
;
;
;
;
;

; Carriage return
; Line feed

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

(continued on next page)

Terminal Driver 5101

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
ARRAY:
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG

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

;
;
;
;

Table of message addresses and

lengths
First message address
First message length

;
; Define messages
;
10$:
.ASCII
<CR><LF>/RED ALERT! RED ALERT!/
15$=.-10$
;
20$:
.ASCII
<CR><LF>/ALL SYSTEMS GO/
25$=.-20$
;
30$:
.ASCII
<CR><LF>/WARNING..INTRUDER ALARM/
35$=.-30$
;
40$:
.ASCII
<CR><LF>/** SYSTEM OVERLOAD **/
45$=.-40$
;
; Static QIO packet for message output using QIO$_G form
;
WRITE_QIO:
$QIO

EFN=SYNC_EFN, - ; QIO packet

FUNC=IO$_WRITEVBLK!IO$M_BREAKTHRU!IO$M_REFRESH, IOSB=SYNC_IOSB

;
; Declare the required I/O status blocks.
;
SYNC_IOSB::
.BLKQ 1
; I/O status block for synchronous terminal processing.
;
; Declare the required event flags.
;
ASYNC_EFN::
.BLKL 1
; Event flag for asynchronous terminal processing.
SYNC_EFN
==
WRITE_QIO + 4 ; Event flag for sync terminal processing.
TIMER_EFN::
.BLKL 1
; Event flag for timer processing.
;
; Timer storage
;
WAITIME:
.LONG
TIME:
.BLKQ

-10*1000*1000*3,-1
1

; 3 second delta time

; Current storage time used for

; random number
(continued on next page)

5102 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
.PAGE
.SBTTL START - MAIN ROUTINE
.ENABLE LOCAL_BLOCK
;++
;
; Functional description:
;
; ********************************************************************
;
;
Start program
;
; ********************************************************************
;
;
The following code performs initialization functions.
;
It is assumed that the terminal is already in
;
FULL-DUPLEX mode.
;
;
NOTE: When doing QIO_S calls, parameters P1 and P3-P6 should be
;
passed by value, while P2 should be passed by reference.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
;-.ENTRY START ^M < >
;

Get the required event flags.

PUSHAL
CALLS
BLBC
PUSHAL
CALLS
BLBC
PUSHAL
CALLS
BLBC

ASYNC_EFN
# 1, G^ LIB$GET_EF
R0, 10$
SYNC_EFN
# 1, G^ LIB$GET_EF
R0, 10$
TIMER_EFN
# 1, G^ LIB$GET_EF
R0, 10$

; Get EFN for async terminal operations.

; Error - branch.
; Get EFN for sync terminal operations.
; Error - branch.
; Get EFN for timer operations.
; Error - branch.

Initialize the terminal characteristics.

$ASSIGN_S

DEVNAM=TT_DESC,-;
CHAN=TT_CHAN
;
BLBC
R0, 10$
;
BSBW
CHANGE_CHARACTERISTICS ;
;
BSBW
ENABLE_CTRLCAST
;
BSBW
ENABLE_OUTBANDAST
;
BSBW
ENABLE_READ
;
MOVZWL TT_CHAN, WRITE_QIO+8
;
BRB
LOOP
;

Assign terminal channel using

logical name and channel number
Error - branch.
Change the characteristics of
terminal
Allow Ctrl/C traps
Enable Ctrl/A out-of-band AST
Queue read
Insert channel into
static QIO packet

10$:
BRW

ERROR

;
; This loop outputs a message based on a random number and then
; delays for 3 seconds
;
(continued on next page)

Terminal Driver 5103

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
LOOP:
$GETTIM_S
TIMADR=TIME
BLBC
R0, 10$
EXTZV #6, #2, TIME, R0
MOVQ
ARRAY[R0], WRITE_QIO+QIO$_P1

;
;
;
;
;
;

Get random time

Error - branch.
Load random bits into switch
Load message address
and size into QIO
packet

;
; Issue QIO write using packet defined in data area
;
$QIOW_G
BLBC
MOVZWL
BLBC

WRITE_QIO
R0, 10$
SYNC_IOSB, R0
R0, 10$

; QIO error - branch.

; Get the terminal driver status.
; Terminal driver error - branch.

;
; Delay for 3 seconds before issuing next message
;
$SETIMR_S

EFN=TIMER_EFN,- ; Timer service

DAYTIM=WAITIME ; will set event flag
; in 3 seconds
BLBC
R0, 10$
; Error - branch.
$WAITFR_S
EFN=TIMER_EFN ; Wait for event flag
BLBS
R0, LOOP
; No error if set
BRB
10$
; Error - branch.
.DISABLE

LOCAL_BLOCK

.PAGE
.SBTTL CHANGE_CHARACTERISTICS - CHANGE CHARACTERISTICS OF TERMINAL
;++
;
; Functional description:
;
;
Routine to change the characteristics of the terminal.
;
; Input parameters:
;
None
;
; Output parameters:
;
R0 - status from $QIO call.
;
R1 - R5 destroyed
;
;-;
CHANGE_CHARACTERISTICS:
$QIOW_S EFN=SYNC_EFN, ; Get current terminal characteristics
CHAN=TT_CHAN, FUNC=#IO$_SENSEMODE, IOSB=SYNC_IOSB, P1=OLDCHAR_BUF, P2=#OLDCHAR_BUF_LEN
BLBC
R0, 10$
; Error if clear
MOVZWL SYNC_IOSB, R0
; Get the terminal driver status.
BLBC
R0, 10$
; Error - branch
(continued on next page)

5104 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
$DCLEXH_S EXIT_HANDLER_BLOCK
BLBC
MOVC3

R0, 10$
#OLDCHAR_BUF_LEN, OLDCHAR_BUF, NEWCHAR_BUF
BISL2 #TT$M_NOBRDCST, NEWCHAR_BUF+4
$QIOW_S EFN=SYNC_EFN, CHAN=TT_CHAN, FUNC=#IO$_SETMODE, IOSB=SYNC_IOSB, P1=NEWCHAR_BUF, P2=#NEWCHAR_BUF_LEN
BLBC
R0, 10$
MOVZWL SYNC_IOSB, R0
BLBC
R0, 10$
RSB

;
;
;
;
;

Declare exit handler to reset

characteristics
Error - branch.
Move old characteristics into
new characteristics buffer

; Set nobroadcast bit

; ...
; Set current terminal characteristics

; QIO error - branch.

; Get the terminal driver status.
; Terminal driver error - branch.

10$:
BRW

ERROR

.PAGE
.SBTTL ENABLE_CTRLCAST - ENABLE Ctrl/C AST
;++
;
; Functional description:
;
;
Routine to allow Ctrl/C recognition.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
;-;
ENABLE_CTRLCAST:
$QIOW_S EFN=SYNC_EFN, CHAN=TT_CHAN, FUNC=#IO$_SETMODE!IO$M_CTRLCAST, IOSB=SYNC_IOSB, P1=CTRLCAST, ; AST routine address
P3=#3
; User mode
BLBC
R0, 10$
; Error - branch.
MOVZWL SYNC_IOSB, R0
; Get the terminal driver status.
BLBC
R0, 10$
; Terminal driver error - branch.
RSB

(continued on next page)

Terminal Driver 5105

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
10$:
BRW

ERROR

.PAGE
.SBTTL ENABLE_OUTBANDAST - ENABLE Ctrl/A AST
;++
;
; Functional description:
;
;
Routine to allow CNTRL/A recognition.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
ENABLE_OUTBANDAST:
$QIOW_S EFN=SYNC_EFN, CHAN=TT_CHAN, FUNC=#IO$_SETMODE!IO$M_OUTBAND, IOSB=SYNC_IOSB, P1=CTRLAAST, ; AST routine address
P2=#CNTRLA_MASK, ; Character mask
P3=#3
; User mode
BLBC
R0, 10$
; QIO error - branch.
MOVZWL SYNC_IOSB, R0
; Get the terminal driver status.
BLBC
R0, 10$
; Terminal driver error - branch.
RSB
10$:
BRW

ERROR

.PAGE
.SBTTL ENABLE_READ - QUEUE A READ TO THE TERMINAL.
;++
;
; Functional description:
;
;
Routine to queue a read operation to the terminal.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
; Define item list for itemlist read
;
ITEM_LST:
ITEM
0, MODIFIERS, ; Convert lowercase to
TRM$M_TM_CVTLOW!TRM$M_TM_NOEDIT ; upper and inhibit line
ITEM
6, TERM,MASK_ADDR
; editing
; Set up terminator mask

(continued on next page)

5106 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
ITEM_LEN
MASK_ADDR:
.LONG

. - ITEM_LST

1@^XD

; Terminator mask is
; <CR>
; and "$"

.WORD 1@4
ENABLE_READ:
$QIO_S EFN=ASYNC_EFN, ; Must not be QIOW form or read will block
CHAN=TT_CHAN, ; process
FUNC=#IO$_READVBLK!IO$M_EXTEND, IOSB=IN_IOSB, ASTADR=READAST, ; AST routine to execute
P1=IN_BUF, ; on
P2=#IN_BUFLEN, P5=#ITEM_LST, ; Itemlist read address
P6=#ITEM_LEN
; Itemlist read size
BLBC
R0, 10$
; QIO error - branch.
; The queued read operation will not affect write operations due
; to the fact that breakthru has been set for the write operations.
RSB
10$:
BRW

ERROR

.PAGE
.SBTTL READAST - AST ROUTINE FOR READ COMPLETION
.ENABLE LOCAL_BLOCK
;++
;
; Functional description:
;
;
AST routine to execute on read completion.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
;-;
10$:
MOVZWL IN_IOSB, R0

; Get the terminal driver status

BRW

; Exit with error status.

20$:
ERROR

.ENTRY READAST
BLBC
MOVZWL
ADDL2
$QIO_S

BLBC

^M < R2, R3, R4, R5 >

; Procedure entry mask

IN_IOSB, 10$
; Terminal driver error - branch
IN_IOSB+2, R0
; Get number of characters read into R0
#ACK_MSGLEN, R0
; Add size of fixed acknowledge message
EFN=ASYNC_EFN, ; Issue acknowledge message
CHAN=TT_CHAN, ; Note, ACK must be asynchronous (QIO)
FUNC=#IO$_WRITEVBLK, - ; and the terminal driver write status
P1=ACK_MSG, ; is ignored (no IOSB and AST routine).
P2=R0
; Specify IOSB and AST routine if output
; must be displayed on the terminal.
R0, 20$
; QIO error - branch

(continued on next page)

Terminal Driver 5107

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
;
; Process read message
;
;
.
;
.
;
.
;(user-provided code to decode command inserted here)
;
.
;
.
;
.
BSBW
RET

ENABLE_READ

.DISABLE

; Queue next read

; Return to mainline loop

LOCAL_BLOCK

.PAGE
.SBTTL CTRLAAST - AST ROUTINE FOR Ctrl/A
.SBTTL CTRLCAST - AST ROUTINE FOR Ctrl/C
.SBTTL ERROR - EXIT ROUTINE
;++
;
; Functional description:
;
;
AST routine to execute when Ctrl/C or Ctrl/A is entered.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
CTRLCAST::
CTRLAAST::
.WORD
MOVL

^M < >
#SS$_NORMAL, R0

; Procedure entry mask

; Put success in R0

ERROR::
$EXIT_S R0
RSB

; Exit

.PAGE
.SBTTL EXIT_HANDLER - EXIT HANDLER ROUTINE
;++
;
; Functional description:
;
;
Exit handler routine to execute when image exits. It cancels
;
any outstanding I/O on this channel and resets the terminal
;
characteristics to their original state.
;
; Input parameters:
;
None
;
; Output parameters:
;
None
;
;-;

(continued on next page)

5108 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 52 (Cont.) FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example
.ENTRY EXIT_HANDLER
^M< >
$CANCEL_S
CHAN=TT_CHAN
$QIOW_S EFN=SYNC_EFN, CHAN=TT_CHAN, FUNC=#IO$_SETMODE, IOSB=SYNC_IOSB, P1=OLDCHAR_BUF, P2=#OLDCHAR_BUF_LEN
BLBC
R0, 10$
MOVZWL SYNC_IOSB, R0

; Flush any I/O on queue

; Reset terminal characteristics

; QIO error - branch.

; Get the terminal driver status.

10$:
RET
.END

START
The VAX MACRO program READ_VERIFY.MAR (Example 53) shows the read
verify function. The program shows a typical build of itemlists (both the right and
left fields), channel assignment, a right- and left-justified read verify operation,
and then the read QIO operation.

Example 53 READ_VERIFY.MAR Terminal Driver Programming Example

.TITLE READ_VERIFY - Read Verify Coding Example
.IDENT V05-000
.SBTTL DECLARATIONS
.DISABLE
GLOBAL
;
; Declare the external system routines and MACRO libraries.
;
.EXTERNAL
LIB$GET_EF
.EXTERNAL
SCR$ERASE_PAGE
.LIBRARY
.LIBRARY

SYS$LIBRARY:LIB.MLB
SYS$LIBRARY:STARLET.MLB

;
; Include files:
;
$IODEF
$TRMDEF
;
; Macros:
;
.MACRO ITEM LEN=0,CODE,VALUE
.WORD LEN
.WORD TRM$_CODE
.LONG VALUE
.LONG 0
.ENDM ITEM
;
; Equated symbols:
;
INBUF_LEN = 20
ESC = ^X1B

(continued on next page)

Terminal Driver 5109

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 53 (Cont.) READ_VERIFY.MAR Terminal Driver Programming Example
;
; Own storage:
;
; Build item lists for the read verify QIO
;
;
; Right-justified field
;
R_ITEM_LIST:
ITEM
CODE
= MODIFIERS, VALUE = TRM$M_TM_R_JUST
ITEM

; Right justify

CODE
VALUE

= EDITMODE, = TRM$K_EM_RDVERIFY

; Enable read verify

CODE
VALUE
LEN

= PROMPT, = R_PROMPT_ADDR, = R_PROMPT_LEN

; Set up prompt

CODE
VALUE
LEN

= INISTRNG, = R_INISTR_ADDR, = R_INISTR_LEN

; Set up initial string

ITEM

CODE
VALUE

= INIOFFSET, = R_INISTR_LEN

ITEM

CODE
VALUE
LEN

= PICSTRNG, = R_PICSTR_ADDR, = R_PICSTR_LEN

CODE
VALUE

= FILLCHR, = <^A/* />

ITEM

ITEM

ITEM

; Set up picture string

; clear = *, fill = space

R_ITEM_LIST_LEN = .-R_ITEM_LIST
R_PROMPT_ADDR:
.ASCII <ESC> /[12;12H$/
R_PROMPT_LEN = .-R_PROMPT_ADDR
R_INISTR_ADDR:
.ASCII / , /
R_INISTR_LEN = .-R_INISTR_ADDR
MASK = TRM$M_CV_NUMERIC!TRM$M_CV_NUMPUNC
R_PICSTR_ADDR:
.BYTE MASK
.BYTE MASK
.BYTE MASK
.BYTE 0
; Marker character
.BYTE MASK
.BYTE MASK
.BYTE MASK
R_PICSTR_LEN = .-R_PICSTR_ADDR
;
; Left-justified field
;
L_ITEM_LIST:
ITEM
CODE
= MODIFIERS, VALUE = TRM$M_TM_CVTLOW!TRM$M_TM_AUTO_TAB
; Upcase input and
; complete on field full
(continued on next page)

5110 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 53 (Cont.) READ_VERIFY.MAR Terminal Driver Programming Example
ITEM

CODE
VALUE

= EDITMODE, = TRM$K_EM_RDVERIFY

; Enable read verify

CODE
VALUE
LEN

= PROMPT, = L_PROMPT_ADDR, = L_PROMPT_LEN

; Set up prompt

CODE
VALUE
LEN

= INISTRNG, = L_INISTR_ADDR, = L_INISTR_LEN

; Set up initial string

ITEM

CODE
VALUE

= INIOFFSET, = 0

ITEM

CODE
VALUE
LEN

= PICSTRNG, = L_PICSTR_ADDR, = L_PICSTR_LEN

; Set up picture string

CODE
VALUE

= FILLCHR, = <^A/* />

; clear = *, fill = space

ITEM

ITEM

ITEM

L_ITEM_LIST_LEN = .-L_ITEM_LIST
L_PROMPT_ADDR:
.ASCII <ESC>/[13;12H Enter Date: /
L_PROMPT_LEN = .-L_PROMPT_ADDR
L_INISTR_ADDR:
.ASCII / - - /
L_INISTR_LEN = .-L_INISTR_ADDR
MASK1 = TRM$M_CV_NUMERIC
MASK2 = TRM$M_CV_UPPER!TRM$M_CV_LOWER
L_PICSTR_ADDR:
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
L_PICSTR_LEN =
IN_IOSB:
TT_CHAN:
INBUF:
SYSINPUT:
SYNC_EFN:

MASK1
MASK1
0
; Marker character
MASK2
MASK2
MASK2
0
; marker character
MASK1
MASK1
.-L_PICSTR_ADDR
.BLKL
.BLKW
.BLKB
.ASCID
.BLKL

2
1
INBUF_LEN
/SYS$INPUT/
1

.PAGE
.ENTRY READ_VERIFY

^M < >

;
; Get the required event flags.
;
PUSHAL SYNC_EFN
CALLS # 1, G^ LIB$GET_EF
BLBC
R0, ERROR

; Error - branch

;
; Assign the channel to SYS$INPUT
;
(continued on next page)

Terminal Driver 5111

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 53 (Cont.) READ_VERIFY.MAR Terminal Driver Programming Example
$ASSIGN_S CHAN = TT_CHAN DEVNAM = SYSINPUT
BLBC
R0, ERROR

; SYS$INPUT
; Branch on error

;
; Clear the screen
;
CLRQ
CALLS
BLBC

-(SP)
#2, G^ SCR$ERASE_PAGE
R0, ERROR

;
; Do the right-justified read operation
;
PUSHL
PUSHAB
CALLS
BLBC

#R_ITEM_LIST_LEN
R_ITEM_LIST
#2, DO_READ
R0, ERROR

;
; Do the left-justified read operation
;
PUSHL
PUSHAB
CALLS
BLBC

#L_ITEM_LIST_LEN
L_ITEM_LIST
#2, DO_READ
R0, ERROR

ERROR:
RET
.PAGE
;++
;
; DO_READ - do the actual QIO
;
; Inputs:
;
;
4(AP) the address of the itemlist
;
8(AP) the length of the itemlist
;
;-.ENTRY DO_READ, ^M<>
$QIOW_S EFN=SYNC_EFN, CHAN = TT_CHAN, FUNC = #<IO$_READVBLK!IO$M_EXTEND>, IOSB = IN_IOSB, p1 = inbuf, p2 = #inbuf_len, p5 = 4(AP), P6 = 8(AP)
BLBC
R0, 10$
; QIO error - branch
MOVZWL IN_IOSB, R0
; Get the terminal driver status.
BLBC
R0, 10$
; Terminal driver error - branch
; Handle the input...
(continued on next page)

5112 Terminal Driver

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 53 (Cont.) READ_VERIFY.MAR Terminal Driver Programming Example
10$:
RET
.END READ_VERIFY

Example 54 LIB$XXABLE_CTRL.C Terminal Driver Programming Example

/*
// Demonstrates CTRL/Y and CTRL/C handling under OpenVMS, as well as
// some basic dynamic string descriptor operations and a few other
// string-related operations.
//
// To build and use:
//
$ CC/DECC LIB$XXABLE_CTRL
//
$ LINK LIB$XXABLE_CTRL
//
$ RUN LIB$XXABLE_CTRL
*/
#include <descrip.h>
#include <iodef.h>
#include <libclidef.h>
#include <lib$routines.h>
#include <ssdef.h>
#include <starlet.h>
#include <stdio.h>
#include <stsdef.h>
void CtrlYHandler()
{
int RetStat;
$DESCRIPTOR( Y, "<CTRL/Y> was detected" );
RetStat = lib$put_output( &Y );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return;
RetStat = lib$enable_ctrl( &LIB$M_CLI_CTRLY );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return;
return;
}
void CtrlCHandler()
{
int RetStat;
$DESCRIPTOR( Y, "<CTRL/C> was detected" );
RetStat = lib$put_output( &Y );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return;
RetStat = lib$enable_ctrl( &LIB$M_CLI_CTRLY );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return;
return;
}
(continued on next page)

Terminal Driver 5113

Terminal Driver
5.6 Terminal Driver Programming Examples
Example 54 (Cont.) LIB$XXABLE_CTRL.C Terminal Driver Programming Example
main()
{
int RetStat;
unsigned short int IOChan;
unsigned short int GotLen;
struct dsc$descriptor GotDsc = { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };
$DESCRIPTOR( Prompt, "Enter CTRL/Y, CTRL/C, or any characters and RETURN:" );
$DESCRIPTOR( Exiting, "Exiting" );
$DESCRIPTOR( TTDsc, "TT:");
RetStat = lib$disable_ctrl( &LIB$M_CLI_CTRLY );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = sys$assign( &TTDsc, &IOChan, 0, 0 );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = sys$qiow( 0, IOChan, IO$_SETMODE|IO$M_CTRLYAST, 0, 0, 0,
CtrlYHandler, 0, 0, 0, 0, 0 );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = sys$qiow( 0, IOChan, IO$_SETMODE|IO$M_CTRLCAST, 0, 0, 0,
CtrlCHandler, 0, 0, 0, 0, 0 );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = lib$get_input( &GotDsc, &Prompt, &GotLen );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = sys$dassgn( IOChan );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = lib$enable_ctrl( &LIB$M_CLI_CTRLY );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = lib$put_output( &Exiting );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
RetStat = lib$sfree1_dd( &GotDsc );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
return SS$_NORMAL;
}

5114 Terminal Driver

6
Pseudoterminal Driver
This chapter describes the use of the pseudoterminal driver (FTDRIVER) and the
pseudoterminal software.
A pseudoterminal is a software device that appears as a real terminal to
an application communicating with it, but does not require the existence
of a physical terminal. A pseudoterminal consists of two components: the
pseudoterminal device and a control program. The control program acts like
a keyboard; that is, anything written to the control program appears on the
pseudoterminal device as if the keystrokes had been typed in at a physical
terminal. The control program also acts like a viewport to the pseudoterminal
device; that is, the control program reads anything that is written by the system
to the pseudoterminal device.
A pseudoterminal allows an application to be set up on the control side of the link
to communicate with another application that is on the pseudoterminal side. This
arrangement allows development of applications that either simulate users or
monitor the communication between a real user (at a physical terminal) and an
application. As with other devices, the work of the pseudoterminal is performed
by a device driver and is tightly coupled to the operating system.
The pseudoterminal driver software includes a set of control connection routines.
Applications can use these routines to perform pseudoterminal operations and
functions. Appendix D provides the calling conventions for these routines.

6.1 Pseudoterminal Operations

This section contains information on the following pseudoterminal operations:

Creating a pseudoterminal

Canceling a request

Deleting a pseudoterminal

6.1.1 Creating a Pseudoterminal

To create a pseudoterminal, use the PTD$CREATE routine described in
Appendix D. When a pseudoterminal is created, it inherits the current system
terminal default attributes unless you specify an alternate set of characteristics.
In either case, you cannot use PTD$CREATE to alter the following startup
attributes:

TT$M_CRFILL is cleared. To change this attribute, issue the SET MODE

$QIO function.

TT$M_LFFILL is cleared. To change this attribute, issue the SET MODE

$QIO function.

TT$M_MODEM is cleared. This attribute cannot be changed.

TT$M_REMOTE is cleared. This attribute cannot be changed.

Pseudoterminal Driver 61

Pseudoterminal Driver
6.1 Pseudoterminal Operations

TT$M_HOSTSYNC is set. To change this attribute, issue the SET MODE

$QIO function.

TT$M_TTSYNC is set. To change this attribute, issue the SET MODE $QIO
function.

TT2$M_DMA is cleared. To change this attribute, issue the SET MODE

$QIO function. Changing it does not alter the behavior of TTDRIVER or the
pseudoterminal.

TT2$M_AUTOBAUD is cleared. To change this attribute, issue the SET

MODE $QIO function. Changing it does not alter the behavior of TTDRIVER
or the pseudoterminal.

TT2$M_FALLBACK is cleared. To change this attribute, issue the SET

MODE $QIO function.

TT2$M_HANGUP is cleared. To change this attribute, issue the SET MODE

$QIO function.

TT2$M_DCL_MAILBX is cleared. This attribute cannot be changed.

When you create a pseudoterminal, you can specify a repeating asynchronous

system trap (AST) to be delivered when the terminal connection is freed. This
AST can be supplied only when the pseudoterminal is created, and it cannot be
deleted. A terminal is freed when a process logs out or deassigns the last channel
to the device. The AST allows the control program to determine whether or not a
user of a pseudoterminal is using it. At this point, the control program can reuse
or delete the pseudoterminal by deassigning the control channel.

6.1.2 Canceling a Request

To cancel a queued control connection request, the control program uses the
PTD$CANCEL routine. This routine enables the pseudoterminal driver to
differentiate between control requests and terminal requests that are being
canceled. This routine cannot be used to flush event notification ASTs.

6.1.3 Deleting a Pseudoterminal

To delete the pseudoterminal, the control program uses the PTD$DELETE
routine. When a pseudoterminal is deleted, any process that is using the
pseudoterminal (except the control process) is disconnected. If you have the
TT2$M_DISCONNECT bit set in the default terminal characteristics parameter
(TTY_DEFCHAR2) and virtual terminals have been enabled (see Section 5.2.2.3),
you get a virtual terminal upon logging in to a pseudoterminal. In this case,
the process is not logged out, but the virtual terminal is disconnected from the
pseudoterminal.
The PTD$DELETE request causes any pending I/O for the control program to
be aborted. It deletes any queued event notification ASTs and returns the I/O
buffers to the application. It also causes the pseudoterminal unit control block
(UCB) to be deleted once the reference count returns to zero.
Note
If an application exits without calling PTD$DELETE, the pseudoterminal
is still deleted.

62 Pseudoterminal Driver

Pseudoterminal Driver
6.2 Pseudoterminal Driver Features

6.2 Pseudoterminal Driver Features

The terminal portion of a pseudoterminal is similar to a regular terminal. The
pseudoterminal driver provides the following features:

Type-ahead buffer

Specifiable or default line terminators

Special operating modes, such as NOECHO and PASTHRU

Escape sequence detection

Terminal/mailbox interaction

Terminal control characters, such as Ctrl/S and Ctrl/Q for starting and
stopping output, Ctrl/O for discarding output, and all other special characters
that are handled by the standard terminal driver

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

For more information on these features, see Section 5.2.

6.3 Pseudoterminal Driver Device Information

The pseudoterminal inherits its device characteristics from the system default
parameters, with the following exceptions:

The device inherits initial device characteristics from the SYSGEN-supplied

default values. You can modify the device characteristics during device
creation by supplying new characteristics.

The HOSTSYNC terminal characteristic is always set.

The device is set to NOMODEM and cannot be set to MODEM.

The device is set not to time output character transmission. Hardware

controllers time output character transmission to determine whether the
controller is broken.

You can obtain information on pseudoterminal characteristics by using the Get

Device/Volume Information ($GETDVI) system service, as described in Section 5.3
and the OpenVMS System Services Reference Manual.
Applications should assign a channel other than the control channel to read data
from, write data to, read, or alter the pseudoterminal characteristics. An attempt
to perform such I/O with the control channel, or any other attempt to queue an
illegal or unsafe I/O request, results in an SS$_CHANINTLK error.

6.4 I/O Buffers

When you create a pseudoterminal, you must provide at least one page to be used
as an I/O buffer.
On Alpha systems, you can allocate one page and divide it into I/O buffers as
needed.
On VAX systems, each page becomes one I/O buffer. You should allocate no more
than six I/O buffers for each pseudoterminal.
No read or write request should reference more than one I/O buffer at a time. The
I/O buffers must be page aligned; therefore, you should create these pages with
the $EXPREG system service or the LIB$GET_VM_PAGE routine. The pages
are owned by the driver until you delete the pseudoterminal. The application

Pseudoterminal Driver 63

Pseudoterminal Driver
6.4 I/O Buffers
is responsible for managing the pages and cannot use buffers that are owned
by another pseudoterminal. The application must decide whether to delete the
buffers when they are freed by the driver or to reuse them.
The I/O buffers must be valid pages in virtual address space. Creating or deleting
an I/O buffer does not alter the contents of the pages.
The low-order word of the status information longword contains the status of the
request. The high-order word of the status information longword contains the
actual number of bytes that are read or written.
Assume that an I/O buffer starting at 200 hexadecimal is available for use. If you
want to read 20 bytes from the pseudoterminal, the readbuf address would be
200, and the readbuf_len would be 20. An application can use the rest of this
buffer for other purposes, including reading or writing to the pseudoterminal.
Figure 61 shows how the buffer would look.
Figure 61 Buffer Layout
Byte Count

Status

200 16
204 16

Data

218 16

ZK9656GE

6.5 Pseudoterminal Functions

This section discusses the following pseudoterminal functions:

Reading data

Writing data

Using write with echo

Flow control

Event notification

6.5.1 Reading Data

To read data from the pseudoterminal, the control program uses the PTD$READ
routine. The read request completes with a minimum of one character and a
maximum of the number of characters requested. The read operation completes
when the pseudoterminal has characters to output. If a read request is issued
and no data is available, the read request is queued and then completed at a later
time.
An application that issues an asynchronous pseudoterminal read can use the
$SYNCH system service to find out when the read completed. The efn argument
for the $SYNCH service must be the same as the efn specified in the original
PTD$READ call, and the iosb for the $SYNCH service must match the readbuf
of the PTD$READ call.

64 Pseudoterminal Driver

Pseudoterminal Driver
6.5 Pseudoterminal Functions
6.5.2 Writing Data
To write data to the pseudoterminal, the control program uses the PTD$WRITE
routine. The write request allows you to specify a buffer to receive any output
that the write request generates; you do not need to issue a separate read request
to read this data. When you use an echo buffer, the control application can
significantly reduce the number of I/O requests required.
An application can issue only one write request at a time. Once the write request
completes, the application must check the write buffer status longword to see
whether all the data supplied was written. If not, the application must issue
additional write requests until all the data has been accepted.

6.5.3 Using Write with Echo

If a read request is pending when a write-with-echo request is issued, the echo
data is placed in the echo buffer. If more data is echoed than can fit in the
echo buffer, the remaining data is placed in the pending read requests buffer.
If no pending read exists, the data is held by the driver until another request
that can take the data is issued. Both the read and the write with echo must
use completion ASTs to allow the driver to report request completions to the
application in the correct order.
If an application is not using the write-with-echo capability, the application
should avoid using completion ASTs if possible. Unnecessary use of completion
ASTs significantly increases the number of instructions needed to complete a read
or write operation.
When using write with echo, both the wrtbuf and echobuf arguments contain
I/O status information. An application must check both of these status longwords
if the PTD$WRITE completes successfully. If a write operation wrote no
characters, characters might still be in the echo buffer. If no data was echoed, the
status in the echobuf is SS$_NORMAL with zero bytes transferred.

6.5.4 Flow Control

By default, the driver attempts to notify the control program of data overrun or
loss. The pseudoterminal sends an XOFF AST when the type-ahead buffer is
getting full. Once the pseudoterminal delivers an XOFF AST, the pseudoterminal
also returns a status of SS$_DATAOVERUN with the actual number of characters
input. This prevents a single request from flooding the type-ahead buffer. If a
control program makes repeated attempts to insert data after receiving the
SS$_DATAOVERUN message, it can flood the terminal type-ahead buffer. When
the type-ahead buffer has filled, the pseudoterminal returns the status of SS$_
DATALOST.
If the control program is writing to the terminal or terminal driver, it should let
the terminal and terminal driver handle flow control. To do this, the application
should enable all three input flow control notification ASTs. The control program
should write a DC1 to the terminal if an XON AST is delivered. It should write
a DC3 to a terminal if an XOFF AST is delivered, and write a BELL character
to the terminal if the BELL AST is delivered. These signals allow the terminal
to decide what to do with the flow control data. The application should ignore
the SS$_DATAOVERUN and SS$_DATALOST return status and continue writing
data to the pseudoterminal.

Pseudoterminal Driver 65

Pseudoterminal Driver
6.5 Pseudoterminal Functions
6.5.5 Event Notification
This section describes how the pseudoterminal driver provides notification of
important driver events.
6.5.5.1 Input Flow Control
The driver provides three ways to indicate when the class driver wants to stop
input and one way to signal when it is safe to resume output:

The driver returns a status of SS$_DATAOVERUN and the number of

characters input for the control program write.

The control program can enable a BELL attention AST to be delivered when
the class driver calls the PTD$SET_TERMINAL_NOTIFICATION routine.
This AST is delivered if the pseudoterminal does not have the HOSTSYNC
attribute set. If only a BELL or only an XOFF AST event is enabled and
an XOFF or a BELL AST needs to be delivered, the AST that is available is
delivered.

The control program can enable an XOFF attention AST to be delivered when
the class driver calls the PTD$SET_TERMINAL_NOTIFICATION routine.
This AST is delivered if the pseudoterminal has the HOSTSYNC attribute
set.

The control program can enable an XON attention AST to be delivered

when the class driver calls the PTD$SET_TERMINAL_NOTIFICATION
routine. This AST is delivered only if the pseudoterminal has the HOSTSYNC
attribute set.

6.5.5.2 Output Stop

The Output Stop AST tells the control program that the terminal driver is
stopping output. This keeps the control program from having to determine
whether an XOFF written to the control side is being treated by the terminal
driver as flow control or data.
6.5.5.3 Output Resume
The Output Resume AST tells the control program that the terminal driver
wants to resume output. This AST can be delivered at any time, even if output is
active or has previously been stopped. The control program should always restart
output processing when it receives this AST.
6.5.5.4 Characteristics Changed
The Characteristics Changed AST tells the control program that the terminal
driver has called the pseudoterminal CHANGE CHARACTERISTICS routine.
This routine is called whenever the terminal driver has changed the device
characteristics. The control program should then read the pseudoterminal
characteristics to determine what has changed.
6.5.5.5 Output Abort
The Output Abort AST tells the control program that the terminal driver has
called the pseudoterminal ABORT OUTPUT routine. This routine is called when
the terminal driver wants to flush any outstanding output data. The control
program should flush any internally buffered data when this AST is received.

66 Pseudoterminal Driver

Pseudoterminal Driver
6.5 Pseudoterminal Functions
6.5.5.6 Terminal Driver Read Events
Three special event types notify the control program when a terminal read
request starts and finishes. By default, the pseudoterminal does not deliver the
read notification ASTs associated with these events. The PTD$SET_EVENT_
NOTIFICATION routine must be used explicitly to enable or disable their
delivery.

Start ReadTells the control program that the terminal driver is starting a
read request. Some applications require this in order to know when to start
inputting a logged session script.

Middle ReadTells the control program that the terminal driver has finished
writing the prompt string if one was supplied.

End ReadTells the control program that the terminal driver has finished a
read request.

Once an event notification AST is enabled, it continues to be delivered until

it is canceled, or until the device is deleted. This characteristic allows the
control program to enable the AST once, which greatly reduces the risk of
missing multiple rapid occurrences of an event. If the driver cannot get sufficient
resources to deliver the notification AST, that report is lost. Only one AST per
event is allowed, and attempts to specify multiple ASTs result in use of the last
one specified.
To enable or disable event notification, the control program uses the PTD$SET_
EVENT_NOTIFICATION routine, which is described in Appendix D.

6.6 Pseudoterminal Driver Programming Example

Example 61 shows how to use the pseudoterminal. (The example is also included
in the SYS$EXAMPLES directory.) This section begins with a brief overview of
the example. The example itself briefly discusses each module; the pseudocode
for that module follows its discussion.
The scenario chosen for this example is a simple terminal session logging utility
that uses most of the pseudoterminal capabilities. This example also shows
how to use the write-with-echo capability, which provides a significant gain in
performance.

6.6.1 Design Overview

The design approach writes the log record in a main loop that hibernates when
it has no work to do. The loop uses ASTs to read keystrokes from the terminal,
write to the pseudoterminal, and write data to the terminal. When a block of
characters is written to the terminal, that block is placed into a queue of blocks
to be written to the log file, and a wake request is issued. Logging is stopped if
you log out of the subprocess, if you enter the stop logging character Ctrl\, or if
a severe error occurs during data processing. When any of these events occur, all
outstanding log records are written before the program exits.
One major design consideration is how flow control should be handledeither by
attempting to enforce flow control, or by letting the terminal and terminal driver
handle it. In this example, the terminal and terminal driver handle flow control;
the driver sends XON, XOFF, or BELL characters to the terminal as necessary.

Pseudoterminal Driver 67

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
One of the six I/O buffers is permanently reserved as the terminal read buffer.
This buffer is passed directly to the terminal read $QIO. This eliminates having
to move data that is read from the terminal into the read buffer. The other five
buffers are placed in a queue and are allocated and deallocated as needed. This
pool of buffers reserves the first two longwords to be used as queue headers and
traditional IOSBs. The third longword and the I/O status longwords are used by
the pseudoterminal driver.
Example 61 Sample Pseudocode for Pseudoterminal Driver Program
/*
** Main Routine
**
** Function: Intitializes the environment and then hibernates, waiting
** to be awakened. When awakened, the program checks to see whether it
** is exiting, or whether more log data is available. If more data is
** available, the data is appended to the current log record and checked
** to see whether a log record should be written. A log record is written
** either when maxbuf characters are in the log buffer,
** or when it finds a <CR><LF> character pair. The algorithm
** allows an unlimited number of <NULL> fill characters to occur
** between the <CR> and the <LF>. If the program is
** exiting, it closes the log file, deletes the pseudoterminal, resets the
** terminal, and exits.
*/
Initialize environments (This includes creating pseudoterminal, the log file
and starting up the subprocess.)
If (Initialization OK) Then
Do
while (I/O buffer to log)
Data size = number of bytes in I/O buff
For all data in I/O buffer
If (cr_seen) Then
If (current char == <LF>) Then
write current log buffer
reset cr_seen
point to start of log buffer
Else if (current char != <NULL>) Then
insert <CR> and current char into log buffer
move log buffer ptr over 2 characters
reset cr_seen
Endif
Else if (current character != <CR>) Then
insert character into log buffer
move log buffer ptr over 1 character
Else
set cr_seen
Endif
(continued on next page)

68 Pseudoterminal Driver

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
If (log buffer ptr >= IOC$GW_MAX-48) Then
write log buffer
reset log buffer pointer
reset cr_seen
Endif
Endloop
Free I/O buffer call free_io_buffers
Endwhile
If (not exiting) Then
Wait for more to do call SYS$HIBER
Endif
Until ((exiting) and (no I/O buffers to log))
close log file
If ((close failed) and (exit reason is SS$_NORMAL)) Then
set exit to status to failure reason
Endif
If (subprocess still running) Then
call SYS$FORCEX to run down the subprocess
Endif
call PTD$CANCEL to flush all pending pseudoterminal read requests
call SYS$CANCEL to flush all terminal requests
call PTD$DELETE to delete the pseudoterminal
If ((delete failed) and (exit reason is SS$_NORMAL)) Then
set exit to status to failure reason
Endif
reset terminal to startup condition using SYS$QIOW
If ((terminal reset failed) and (exit reason is SS$_NORMAL)) Then
exit to status to failure reason
Endif
Endif
call LIB$SIGNAL and report exit reason
Exit
/*
**
** Initialization Code
**
** Function: This routine sets the terminal characteristics, creates the
** pseudoterminal, starts up the subprocess, and opens the log file. If
** any of these steps fail, the program undoes any steps already done and
** returns to the main routine.
**
*/
(continued on next page)

Pseudoterminal Driver 69

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
read the maximum buffer size from IOC$GW_MAXBUF
Assign a channel to SYS$INPUT
If (assign ok) Then
Read the terminal characteristics from the terminal
If (read of terminal characteristics ok) Then
Open log file with maximum record size of IOC$GW_MAXBUF
If (open ok) Then
Create the pseudoterminal with characteristics of terminal
If (create ok) then
Place 4 of the buffers on the queue of free I/O buffers
Copy terminal characteristics and modify them to NOECHO and PASTHRU
Set the terminal characteristics use modified value
If (set ok) Then
Get device name of pseudoterminal use SYS$GETDVI
If (get ok) Then
Create subprocess
If (create ok) Then
Enable XON, XOFF, BELL, SET_LINE event notification ASTs
If (AST setup OK) Then
Call PTD$READ to start reading from the pseudoterminal
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (read ok) Then
Call SYS$QIO and read a single character from the
keyboard ASTADR = kbd_read_ast
If (read failed) Then
Call PTD$CANCEL to flush queued pseudoterminal read
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Close log file and delete it
Endif
Else
Close log file and delete it
Endif
(continued on next page)

610 Pseudoterminal Driver

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
Endif
Endif
Endif
/*
** kbd_read_ast
**
** Function: This routine is called every time data is read from the terminal.
** If the program is exiting, then the routine exits without restarting the
** read. The character read is checked to see if the terminate processing
** character Ctrl\ was entered. If the terminate processing character was
** entered, the exiting state is set and a SYS$WAKE is issued to start the
** main routine. Now an attempt is made to obtain an I/O buffer in which
** to store echoed output. If an I/O buffer is unavailable, a simple
** PTD$WRITE is issued; a PTD$WRITE with echo is issued if a buffer is
** available. If the write completes successfully, another read is issued
** to the keyboard.
**
*/
If (not exiting) Then
If (read ok) Then
Search input data for Ctrl\
Allocate a read buffer call allocate_io_buffer
If (got a buffer) Then
Call PTD$WRITE to write characters to pseudoterminal
ASTADR = ft_echo_ast
ASTPRM = allocated I/O buffer
WRTBUF = read I/O buffer
WRTBUF_LEN = number of characters read
ECHOBUF = allocated I/O buffer
ECHOBUF_LEN = 500
Else
Call PTD$WRITE to write characters to pseudoterminal
WRTBUF = read I/O buffer
WRTBUF_LEN = number of characters read
Endif
If (write setup ok)
If ((write status is ok) or (write status is SS$_DATALOST))
Issue another single character read to terminal with
ASTADR = kbd_read_ast, with data going to read I/O buffer
If (read setup failed) Then
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to read failure status
Endif
If (exiting) Then
Wake the mainline call SYS$WAKE
Endif
Endif
(continued on next page)

Pseudoterminal Driver 611

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
/*
**
**
**
**
**
**
**
**
**
**
**
*/
If

terminal_output_ast
Function: This routine is called every time an I/O buffer is written
to the terminal. If the terminal write request completes successfully,
it inserts the I/O buffer into the queue of I/O buffers to be logged.
If the I/O buffer is the only entry on the queue, it issues a SYS$WAKE
to start the main routine. To prevent spurious wake requests,
SYS$WAKE is not issued if multiple entries are already on
the queue. If a terminal write error occurs, the routine sets the
exit flag and wakes the main routine.

(terminal write completed ok) Then

insert I/O buffer onto logging queue
If (this is only entry on queue) Then
wake the mainline call SYS$WAKE
Endif
Else
set exit flag
set exiting reason to terminal write error reason
wake the mainline call SYS$WAKE
Endif
/*
**
** ft_read_ast
**
** Function: This routine is called when a pseudoterminal read request
** completes. It writes the buffer to the terminal and attempts to start
** another read from the pseudoterminal. If the program is not exiting,
** this routine writes the buffer to the terminal and does not start another
** pseudoterminal read.
**
*/
If (not exiting)
If (Pseudoterminal read ok) Then
write buffer to the terminal ASTADR = terminal_output_ast
If (write setup ok) Then
Allocate another read buffer call allocate_io_buffer
If (got a buffer) Then
Call PTD$READ to restart reads from the pseudoterminal.
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (read setup failed) Then
Set exit flag
Set exiting reason to read failure reason
Wake the mainline call SYS$WAKE
Endif
Else
Set read stopped flag
Endif
Else
Set exit flag
Set exiting reason to terminal write failure reason
Wake the mainline call SYS$WAKE
Endif
Else
Set exit flag
Set exiting reason to terminal read failure reason
(continued on next page)

612 Pseudoterminal Driver

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
Wake the mainline call SYS$WAKE
Endif
Endif
/*
**
** ft_echo_ast
**
** Function: This routine is called if a write to the pseudoterminal used
** an ECHO buffer. If any data was echoed, the output is written to the
** terminal. If no data was echoed, the I/O buffer is freed so it can be
** used later. If the program is exiting, this routine exits.
**
*/
If (not exiting) Then
If (ECHO buffer has data) Then
Write the buffer to the terminal with ASTADR = terminal_output_ast
If (error setting up write) Then
Set exit flag
Set exiting reason to write failure reason
Wake mainline call SYS$WAKE
Endif
Else
Free I/O buffer call free_io_buffers
Endif
Endif
/*
** free_io_buffers
**
** Function: This routine places a free I/O buffer on the queue of available
** I/O buffers. It also restarts any stopped read operations from the
** pseudoterminals. This routine disables AST delivery while it is running
** in order to synchronize reading and resetting the read stopped flag.
**
*/
If (not exiting) Then
Disable AST deliver using SYS$SETAST
If (Pseudoterminal reads not stopped) Then
Insert I/O buffer on the interlocked queue of free I/O buffers
Else
Call PTD$READ to restart reads from the pseudoterminal.
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (no error starting read) Then
Clear read stopped flag
Else
Set exit flag
Set exit reason to read setup reason
Endif
Endif
Enable AST delivery using SYS$SETAST
Endif
(continued on next page)

Pseudoterminal Driver 613

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
/*
**
**
**
**
**
**
**
*/
If

allocate_io_buffer
Function: This routine obtains a free I/O buffer from the queue of
available I/O buffers. If the program is exiting, this routine
returns an SS$_FORCEDEXIT error.

(not exiting) Then

remove a I/O buffer from the interlocked queue of I/O buffers
If (queue empty) Then
exit with reason LIB$_QUEWASEMP
else
exit with reason SS$_FORCEDEXIT
Endif
/*
** subprocess_exit
**
** Function: This routine is called when the subprocess has completed
** and exited. This routine checks whether the program is already exiting.
** If not, then the routine indicates that the program is exiting and wakes
** up the main program.
**
*/
If (not exiting) Then
indicate subprocess no longer running
set exit status to SS$_NORMAL
indicate exiting
call SYS$WAKE to start up main loop
Endif
/*
** xon_ast
**
** Function: This routine is called for the pseudoterminal driver to signal
** that it is ready to accept keyboard input. The routine attempts to send
** an XON character to the terminal by sending XON DC1 using SYS$QIO.
** If the attempt fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIO to send a <DC1> character to the terminal
Endif
/*
** bell_ast
**
** Function: This routine is called when the pseudoterminal driver wants
** to warn the user to stop sending keyboard data. The routine attempts
** to ring the terminal bell by sending the BELL character to the terminal
** using SYS$QIO. If the attempt fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIO to send a <BELL> character to the terminal
Endif
(continued on next page)

614 Pseudoterminal Driver

Pseudoterminal Driver
6.6 Pseudoterminal Driver Programming Example
Example 61 (Cont.) Sample Pseudocode for Pseudoterminal Driver Program
/*
**
**
**
**
**
**
**
*/
If

xoff_ast
Function: This routine is called when the pseudoterminal driver wants to
signal that it will stop accepting keyboard input. The routine attempts
to send an XOFF character to the terminal by sending XOFF DC3 to the
terminal using SYS$QIO. If the attempt fails, it is not retried.

(not exiting) Then

call SYS$QIO to send a <DC3> character to the terminal
Endif
/*
** set_line_ast
**
** Function: This routine is called when the pseudoterminal device
** characteristics change. The routine reads the current pseudoterminal
** characteristics, changes the characteristics to set PASTHRU and NOECHO,
** and applies the characteristics to the input terminal. If the attempt
** to alter the terminal characteristics fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIOW to read the pseudoterminals characteristics
If (not error) Then
Set the alter the just read characteristics to have PASTHRU and NOECHO
attributes
call SYS$QIO to set the terminal characteristics.
Endif
Endif

Pseudoterminal Driver 615

7
Shadow-Set Virtual Unit Driver
This chapter provides an overview of Compaq Volume Shadowing for OpenVMS
and describes the use of the shadow-set virtual unit driver (SHDRIVER).

7.1 Introduction
Compaq Volume Shadowing for OpenVMS ensures that data is available for
applications and end users by duplicating data on multiple disks. Because the
same data is recorded on multiple disk volumes, if one disk fails, the remaining
disk or disks can continue to service I/O requests. This ability to shadow disk
volumes is sometimes referred to as disk mirroring.
Volume shadowing supports the clusterwide shadowing of DIGITAL SCSI and
DSA storage systems. Volume shadowing also supports shadowing of all mass
storage control protocol (MSCP) served DSA disks and DIGITAL SCSI disks.
For more information about Volume Shadowing supported devices, refer to the
Volume Shadowing for OpenVMS Software Product Description.
You can mount one, two or three compatible disk volumes, including the system
disk, to form a shadow set. Each disk in the shadow set is known as a shadow
set member. Volume Shadowing for OpenVMS logically binds the shadow set
devices together and represents them as a single virtual device called a virtual
unit. This means that multiple members of the shadow set, represented by the
virtual unit, appear to applications and users as a single, highly available disk.
Volume Shadowing features include:

Controller independence. Shadow set members can be located on any node in

an OpenVMS Cluster that has Volume Shadowing enabled.

Clusterwide, homogeneous shadow-set maintenance functions.

Ability to survive controller, disk, and media failures transparently.

Shadowing functions that do not affect application I/O.

Applications and users read and write data to and from a shadow set using the
same commands and program language syntax and semantics that are used for
nonshadowed I/O operations. Volume shadowed sets are managed and monitored
using the same commands and utilities that are used for nonshadowed disks. The
only difference is that access is through the virtual unit, not to individual devices.
SHDRIVER, the driver that controls the virtual unit functions, is described in
Section 7.3.
For more detailed information on Compaq Volume Shadowing for OpenVMS, refer
to the Volume Shadowing for OpenVMS manual.

Shadow-Set Virtual Unit Driver 71

Shadow-Set Virtual Unit Driver

7.2 Configurations

7.2 Configurations
Compaq Volume Shadowing for OpenVMS does not depend on specific hardware
in order to operate. All shadowing functions can be performed on VAX and Alpha
systems running the OpenVMS operating system. Shadow set members must
have the same physical geometry (that is, the same number of identical logical
blocks [LBNs]) and members can be located anywhere in an OpenVMS Cluster.

7.2.1 Supported Hardware

Volume shadowing requires a minimum of one VAX computer, one mass storage
controller, and DSA (DIGITIAL Storage Architecture) or Small Computer System
Interface (SCSI) disk drives.
Refer to the most recent Volume Shadowing for OpenVMS Software Product
Descriptions (SPD 27.29.xx) for additional information about hardware
requirements.

7.2.2 Compatible Disk Drives and Volumes

Volume shadowing requires compatibility among the physical units (disk drives
and volumes) that form a shadow set. For example:

Units must have the same geometry, including the same number of sectors
per track, the same number of tracks per cylinder, and the same number of
cylinders per volume.

Units must be Files-11 On-Disk Structure Level 2 (ODS-2) data disks.

Units and controllers must conform to DSA and OpenVMS MSCP, or must be
SCSI compliant.

Units should not have hardware write protection enabled. Hardware write
protection stops the volume shadowing software from maintaining identical
volumes. However, the shadow set virtual unit may be mounted software
write-locked with the /NOWRITE qualifier to MOUNT.

7.3 Driver Functions

This section describes the major virtual unit functions supported by SHDRIVER.
In addition to the virtual unit functions described in this section, SHDRIVER
supports all OpenVMS disk functions. SHDRIVER receives QIO operations
from application programs and is a client of the disk class drivers DUDRIVER.
Applications access the shadow set as they would access a standard OpenVMS
disk.
Table 71 summarizes the major SHDRIVER functions.
Important Note
The MOUNTSHAD, ADDSHADMBR, COPYSHAD, and REMSHADMBR
functions are reserved for Compaq internal use. Use of these functions
by customer or third-party provided software may cause unpredictable
results including system crashes and data corruption.

72 Shadow-Set Virtual Unit Driver

Shadow-Set Virtual Unit Driver

7.3 Driver Functions
Table 71 Functions of the Shadow Set Virtual Unit Driver
Function

Description

MOUNTSHAD

Creates a virtual unit

ADDSHAD

Evaluates a physical member and adds members

COPYSHAD

Triggers and controls copy operations

REMSHAD

Removes a physical member

AVAILABLE

Virtual unit dissolution

SENSECHAR

Verifies shadow set status

READ

Directs I/O to a physical member

WRITE

Propagates a write operation to all physical members

7.3.1 Read and Write Functions

With minor changes, the read and write functions for SHDRIVER operate the
same as for the disk class driver (see Sections 2.4.1 and 2.4.2).
During an SHDRIVER read operation, the host directs the read to the member
volume with the shortest path.
During a write operation, SHDRIVER directs the write to each member volume.
The write operations for each member volume usually proceed in parallel; the
virtual unit write operation terminates when all writes have completed. The
write function for SHDRIVER takes the IO$M_VUEX_FC function modifier; this
modifier should not be used by application programs.
The read and write SHDRIVER functions, as well as all user functions, are issued
by user programs. All other SHDRIVER functions are invoked by MOUNT and
DISMOUNT commands, or the $MOUNT and $DISMOUNT system services.
Remember that volume shadowing provides data availability by protecting
against hardware problems or communication path problems that might cause a
disk volume to be a single point of failure. If a write request is made to a shadow
set, but the system fails before a completion status is returned from all of the
shadow set members, it is possible that:

All members might contain the new data.

All members might contain the old data.

Some members might contain new data and others might contain old data.

When the system recovers, volume shadowing performs a merge or copy operation
to ensure that the corresponding blocks on each shadow set member contain the
same data (right or wrong); therefore, the goal here is not one of data correctness
but of data availability. Volume shadowing is designed to make the data on all
disks identical, then, if necessary, incorrect data can be reconciled either by the
user reentering the data or by an application automatically employing database
or journaling techniques.
For example, when used with volume shadowing, OpenVMS RMS journaling
allows you to develop applications that can automatically recover from failures
such as:

Permanent loss of the path between a CPU data buffer containing the data
being written and the disk being written to during a multiple block I/O

Shadow-Set Virtual Unit Driver 73

Shadow-Set Virtual Unit Driver

7.3 Driver Functions
operation. Communication path loss can occur due to node failure or a failure
of node-to-node communications.

Failure of a CPU (such as a system crash, halt, power failure, or system

shutdown) during a multiple block write I/O operation.

Mistaken deletion of a file.

Corruption of file system pointers.

OpenVMS RMS file corruption due to a software error or incomplete bucket

write operation to an indexed file.

Cancellation of an in-progress multiple block write operation.

Refer to the Volume Shadowing for OpenVMS manual for more information about
shadowing merge and copy operations.

7.4 Error Processing

Shadow set recovery and repair are handled by volume processing, which replaces
mount verification for shadow sets. Membership failure decisions are made by
the VAX hosts. Device errors that result in inaccessibility of physical member
units first utilize the class drivers connection walking algorithm. If that fails, a
local decision is made on the shadow set membership. The rules are:

If some, but not all, members of the set are accessible, then the local node
sequentially adjusts the membership and notifies the other hosts.

If no members are accessible, no modifications to the set membership are

made.

There are two types of volume processing: active and passive. Active volume
processing handles error processing on a local node. Triggered by a failed I/O
operation, active volume processing also controls mount verification functions,
member removal, and failover. Passive volume processing is triggered by lock
messages or by a cluster event. Passive volume processing revalidates shadow
set membership, ensures that the shadow set reflects changes made outside the
shadow set, and handles the following functions:

Member additions from other nodes

Member removals from other nodes

A new node mounting the shadow set

A node dismounting the shadow set

A system crash on a node that has the shadow set mounted

For more information, refer to the Volume Shadowing for OpenVMS manual.

74 Shadow-Set Virtual Unit Driver

8
Using the OpenVMS Generic SCSI Class Driver
This chapter describes the use of the OpenVMS Generic Small Computer System
Interface (SCSI) class driver.

8.1 Overview of SCSI

The American National Standard for information systemsSmall Computer
System Interface2 (SCSI2) specification defines mechanical, electrical, and
functional requirements for connecting small computers to a wide variety of
intelligent devices, such as rigid disks, flexible disks, magnetic tape devices,
printers, optical disks, and scanners. It specifies standard electrical bus signals,
timing, and protocol, as well as a standard packet interface for sending commands
to devices on the SCSI bus.
Certain OpenVMS systems employ the SCSI bus as an I/O bus. For these
systems, Compaq offers SCSI-compliant disk and tape drives, such as the RZ55
300 MB read/write disk, the RRD40 600 MB compact disk, and the TZK50 95 MB
streaming tape drive. The operating system also allows devices including disk
drives, tape drives, and scanners, supplied by sources other than Compaq, to be
connected to the SCSI bus of such a system.
SCSI has been widely adopted by manufacturers for a variety of peripheral
devices; however, because the ANSI SCSI standard is broad in scope, not all
devices that implement its specifications can fully interrelate on the bus. Compaq
fully supports SCSI-compliant equipment sold or supplied by Compaq. Proper
operation of products not sold or supplied by Compaq cannot be assured.
For more information, refer to the following documents:

American National Standard for Information SystemsSmall Computer

System Interface2 (SCSI2) specification (X3T9.2/86109)
Copies of this document can be purchased from: Global Engineering
Documents, 2805 McGaw, Irvine, California 92714, United States; or (800)
854-7179 or (714) 261-1455. Please refer to document X3.131198X.

American National Standard for Information SystemsSmall Computer

System Interface specification (X3.1311986)
Copies of this document can be obtained from: American National Standards
Institute, Inc., 1430 Broadway, New York, New York, 10018. This document
is now known as the SCSI1 standard.

Compaq publishes two additional documents to help third-party vendors prepare

SCSI peripherals and peripheral software for use with DIGITAL workstations.

The Small Computer System Interface: An Overview (EKSCSISOV001)

provides a general description of the DIGITAL SCSI third-party support
program.

Using the OpenVMS Generic SCSI Class Driver 81

Using the OpenVMS Generic SCSI Class Driver

8.1 Overview of SCSI

The Small Computer System Interface: A Developers Guide

(EKSCSISSP001) presents the details of implementation of SCSI within
DIGITAL operating systems.

8.2 OpenVMS SCSI Class/Port Architecture

The operating system employs a class/port driver architecture to communicate
with devices on the SCSI bus. The class/port design allows the responsibilities for
communication between the operating system and the device to be cleanly divided
between two separate driver modules (see Figure 81).
Figure 81 OpenVMS SCSI Class/Port Interface
$QIO

DeviceLevel Operations
Handles SCSI commands
Handles SCSI status
BusLevel Operations
Handles SCSI phases and timing
Handles SCSI messages
Handles data movement

Class
Driver

SCSI Port Interface

Port
Driver

Port Hardware
ZK1366AGE

The SCSI port driver transmits and receives SCSI commands and data. It
knows the details of transmitting data from the local processors SCSI port
hardware across the SCSI bus. Although it understands SCSI bus phases,
protocol, and timing, it has no knowledge of which SCSI commands the device
supports, what status messages it returns, or the format of the packets in
which this information is delivered. Strictly speaking, the port driver is a
communications path. When directed by a SCSI class driver, the port driver
forwards commands and data from the class driver onto the SCSI bus to the

82 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.2 OpenVMS SCSI Class/Port Architecture
device. On any given OpenVMS system, a single SCSI port driver handles
bus-level communications for all SCSI class drivers that may exist on the system.
The SCSI class driver acts as an interface between the user and the SCSI
port, translating an I/O function as specified in a users $QIO request to a
SCSI command targeted to a device on the SCSI bus. Although the class driver
knows about SCSI command descriptor buffers, status codes, and data, it has
no knowledge of underlying bus protocols or hardware, command transmission,
bus phases, timing, or messages. A single class driver can run on any given
OpenVMS system, in conjunction with the SCSI port driver that supports that
system. The operating system supplies a standard SCSI disk class driver and a
standard SCSI tape class driver to support its disk and tape SCSI devices.

8.3 Overview of the OpenVMS Generic SCSI Class Driver

The OpenVMS generic SCSI class driver provides a mechanism by which an
application program can control a SCSI device, supplied by a source other than
Compaq, that cannot be controlled by the standard OpenVMS disk and tape
class drivers. By means of a Queue I/O Request ($QIO) system service call, a
program can pass to the generic SCSI class driver a preformatted SCSI command
descriptor block. The generic SCSI class driver, in conjunction with the standard
OpenVMS SCSI port driver, delivers this SCSI command to the device, manages
any transfer of data from the device to a user buffer, and returns SCSI status to
the application.
In effect, an application using the generic SCSI class driver implements details
of device control usually managed within device driver code. The programmer of
such an application must understand which SCSI commands the device supports
and which SCSI status values the device returns. The programmer must also
be aware of the devices timeout requirements, data transfer capabilities, and
command retry behavior.
The application program sets up the characteristics of the connection the generic
SCSI class driver uses when delivering commands to, exchanging data with, and
receiving status from the device. The program associates each I/O operation the
device can perform with a specific SCSI command. When it receives a request
for a particular operation, the application program creates the specific command
descriptor block that, when passed to the device, causes it to perform that
operation.
The application initiates all transactions to the SCSI device by means of a $QIO
call to the generic SCSI class driver, supplying the address and length of the SCSI
command descriptor block, plus the parameters of any data transfer operation,
in the call. When the transaction completes and the application program regains
control, it interprets the returned status value, processes any returned data, and
services any failure. To avoid conflicts with other applications accessing the same
device, an application may need to explicitly allocate the device.
Because the generic SCSI class driver has no knowledge of specific device errors,
it neither logs device errors nor implements error recovery. An application
using the driver must manage device-specific errors itself. To service an error
returned on a single transaction, the application must issue additional $QIO
requests and initiate further transactions to the device. If more precise or more
efficient error recovery is required for a device, the developer should consider
writing a third-party SCSI class driver, as described in the OpenVMS VAX
Device Support Manual (available on the Documentation CD-ROM). A third-party
SCSI class driver can log errors associated with device activity by using the

Using the OpenVMS Generic SCSI Class Driver 83

Using the OpenVMS Generic SCSI Class Driver

8.3 Overview of the OpenVMS Generic SCSI Class Driver
method described in the OpenVMS VAX Device Support Manual (available on the
Documentation CD-ROM).
A third-party class driver is the only means of supporting devices that themselves
generate transactions on the SCSI bus, such as notification of a device selection
event to the host processor. Refer to the description of asynchronous event
notification (AEN) in the OpenVMS VAX Device Support Manual (available on the
Documentation CD-ROM).
Figure 82 shows the flow of a $QIO request through the generic SCSI class
driver and the port driver.
When direct access to a target device on the SCSI bus is required, the generic
SCSI class driver is loaded for that device, as described in Section 8.6. An
application program using the generic class driver performs the following tasks to
issue a command to the target device:
1. Calls the Assign I/O Channel ($ASSIGN) system service to assign a channel
to the generic SCSI class driver, and to allocate the device for the applications
exclusive use.
2. Formats a SCSI command descriptor block.
3. Formats any data to be transferred to the device.
4. Calls the Queue I/O Request ($QIO) system service to request the generic
SCSI class driver to send the SCSI command descriptor block to the port
driver.
5. Upon completion of the I/O request, interprets the SCSI status byte and any
data returned from the target device.
These operations are described in following sections.
Note
Because incorrect or malicious use of the generic SCSI class driver can
result in SCSI bus hangs and lead to SCSI bus resets, DIAGNOSE and
PHY_IO or LOG_IO privileges are required to access the driver. An
application program can be designed in such a way as to filter user
I/O requests, which allows nonprivileged users access to some device
functions.

8.4 Accessing the OpenVMS Generic SCSI Class Driver

Interactive commands and procedure calls can use the OpenVMS generic SCSI
class driver to access devices on the SCSI bus. However, it is unlikely that a user
application would access a device on the SCSI bus by directly using the $QIO
interface of the generic SCSI class driver. First of all, any user process directly
using the $QIO interface would require DIAGNOSE and PHY_IO or LOG_IO
privileges. Under normal circumstances, it would be a system security risk to
grant DIAGNOSE and PHY_IO or LOG_IO privileges to many system users.
Secondly, it would be cumbersome for end users of the device to identify, format,
and issue SCSI commands to the device. Rather, it would be more efficient to
develop an interface that hides these details.

84 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.4 Accessing the OpenVMS Generic SCSI Class Driver
Figure 82 Generic SCSI Class Driver Flow

User
Interface

Application
Program

$QIO

GKDRIVER

Class
Port
SCSI Port Interface

Port
Driver

Port Hardware
ZK1370AGE

A utility program, installed with the DIAGNOSE and PHY_IO or LOG_IO

privileges, can provide nonprivileged users with a command-line interface to a
SCSI device. The utility translates interactive commands provided by the user
into the appropriate set of SCSI commands and sends them to the device using
the $QIO interface provided by the generic SCSI class driver. The utility checks
user commands to ensure that only valid SCSI commands are sent to the device.
Using the OpenVMS Generic SCSI Class Driver 85

Using the OpenVMS Generic SCSI Class Driver

8.4 Accessing the OpenVMS Generic SCSI Class Driver
Refer to the OpenVMS System Managers Manual and the OpenVMS System
Management Utilities Reference Manual for information about installing images
with privileges.
A privileged shareable image can provide system applications with a procedure
interface to a SCSI device. The image contains a set of procedures that translate
operations specified by the caller into the appropriate set of SCSI commands.
The SCSI commands are sent to the device through the $QIO interface of the
generic SCSI class driver. The privileged shareable image checks its callers
parameters to ensure that only valid SCSI commands are sent to the device.
Refer to the OpenVMS Programming Concepts Manual for information about
creating shareable images.

8.5 SCSI Port Features Under Application Control

The standard OpenVMS SCSI port driver provides mechanisms by which the
generic SCSI class driver can control the nature of data transfers and command
transmission across the SCSI bus. An application uses the $QIO interface to
tailor these mechanisms to the specific device it supports. Among the features
under application program control are the following:

Data transfer mode

Disconnection and reselection

Command retry

Command timeouts

The following sections discuss these features.

8.5.1 Setting the Data Transfer Mode

The SCSI bus defines two data transfer modes, asynchronous and synchronous.
In asynchronous mode, for each REQ from a target there is an ACK from the
host prior to the next REQ from the target. Synchronous mode allows higher
data transfer rates by allowing a pipelined data transfer mechanism where, for
short bursts (defined by the REQ-ACK offset), the target can pipeline data to an
initiator without waiting for the initiator to respond.
Whether or not a port or a target device allows synchronous data transfers,
it is harmless for the program to set up the connection to use such transfers.
If synchronous mode is not supported, the port driver automatically uses
asynchronous mode.
For example, to use synchronous mode in a transfer, a programmer using the
generic SCSI class driver must ensure that both the SCSI port and the SCSI
device involved in the transfer support synchronous mode. The SCSI port of
the VAXstation 3520/3540 system allows both synchronous and asynchronous
transfers, whereas that of OpenVMS 3100 systems supports only asynchronous
transfers.
To set up a connection to use synchronous data transfer mode, a program using
the generic SCSI class driver sets the syn bit in the flags field of the generic
SCSI descriptor, the address of which is passed to the driver in the p1 argument
to the $QIO request.

86 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.5 SCSI Port Features Under Application Control
8.5.2 Enabling Disconnection and Reselection
The ANSI SCSI specification defines a disconnection facility that allows a target
device to yield ownership of the SCSI bus while seeking or performing other timeconsuming operations. When a target disconnects from the SCSI bus, it sends
a sequence of messages to the initiator that cause it to save the state of the I/O
transfer in progress. Once this is done, the target releases the SCSI bus. When
the target is ready to complete the operation, it reselects the initiator and sends
to it another sequence of messages. This sequence uniquely identifies the target
and allows the initiator to restore the context of the suspended I/O operation.
Whether disconnection should be enabled or disabled on a given connection
depends on the nature and capabilities of the device involved in the transfer, as
well as on the configuration of the system. In configurations where there is a
slow device present on the SCSI bus, enabling disconnection on connections that
transfer data to the device can increase bus throughput. By contrast, systems
where most of the I/O activity is directed towards a single device for long intervals
can benefit from disabling disconnection. By disabling disconnection when there
is no contention on the SCSI bus, port drivers can increase throughput and
decrease the processor overhead for each I/O request.
By default, the OpenVMS class/port interface disables the disconnect facility on
a connection. To enable disconnection, an application program using the generic
SCSI class driver sets the dis bit of the flags field of the generic SCSI descriptor,
the address of which is passed to the driver in the p1 argument to the $QIO call.

8.5.3 Disabling Command Retry

The SCSI port driver implements a command retry mechanism, which is enabled
on a given connection by default.
When the command retry mechanism is enabled, the port driver retries up to
three times any I/O operation that fails during the COMMAND, Message, Data,
or STATUS phases. For instance, if the port driver detects a parity error during
the Data phase, it aborts the I/O operation, logs an error, and retries the I/O
operation. It repeats this sequence twice more, if necessary. If the I/O operation
completes successfully during a retry attempt, the port driver returns success
status to the class driver. However, if all retry attempts fail, the port driver
returns failure status to the class driver.
An application may need to disable the command retry mechanism under certain
circumstances. For example, repeated execution of a command on a sequential
device may produce different results than are intended by a single command
request. A tape drive could perform a partial write and then repeat the write
without resetting the tape position.
An application program using the generic SCSI class driver can disable the
command retry mechanism by setting the dpr bit of the flags field of the generic
SCSI descriptor, the address of which is passed to the driver in the p1 argument
to the $QIO request.

Using the OpenVMS Generic SCSI Class Driver 87

Using the OpenVMS Generic SCSI Class Driver

8.5 SCSI Port Features Under Application Control
8.5.4 Setting Command Timeouts
The SCSI port driver implements several timeout mechanisms, some governed
by the ANSI SCSI specification and others required by OpenVMS. The timeouts
required by OpenVMS include the following:
Timeout

Description

Phase change timeout

Maximum number of seconds for a target to change the SCSI

bus phase or complete a data transfer. (This value is also
known as the DMA timeout.)
Upon sending the last command byte, the port driver waits
this many seconds for the target to change the bus phase
lines and assert REQ (indicating a new phase). Or, if the
target enters the DATA IN or DATA OUT phase, the transfer
must be completed within this interval.

Disconnect timeout

Maximum number of seconds, from the time the initiator

receives the DISCONNECT message, for a target to reselect
the initiator so that it can proceed with the disconnected I/O
transfer.

An application program using the generic SCSI class driver is responsible for
maintaining both of these timeout values. It has the following options:

Accepting a connections default value. The default value for both timeouts is
20 seconds.

Altering the connections default value. To modify the default values, the
class driver specifies nonzero values for the phase change timeout and
disconnect timeout fields of the generic SCSI descriptor, the address of
which is passed to the driver in the p1 argument to the $QIO system service
call.

8.6 Configuring a Device Using the Generic Class Driver

On VAX systems, the System Generation utility (SYSGEN) loads the generic
SCSI class driver into system virtual memory, creates additional data structures
for the device unit, and calls the drivers controller initialization routine and
unit initialization routine. SYSGEN automatically loads and autoconfigures the
SCSI port driver at system initialization. As part of autoconfiguration, SYSGEN
polls each device on each SCSI bus. If the device identifies itself as a directaccess device, direct-access CD-ROM device, or flexible disk device, SYSGEN
automatically loads the disk class driver (DKDRIVER). If the device identifies
itself as a sequential-access device, SYSGEN automatically loads the tape class
driver (MKDRIVER). If the autoconfiguration facility does not recognize the type
of the SCSI device, it does not load a driver.
If a third-party-supplied SCSI device requires that the generic class driver be
loaded, it must be configured by an explicit SYSGEN CONNECT command, as
follows:
$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> CONNECT GKpd0u /NOADAPTER

88 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.6 Configuring a Device Using the Generic Class Driver
On Alpha systems, SYSMAN performs the same functions that SYSGEN performs
on VAX systems. If a third-party-supplied SCSI device requires that the generic
class driver be loaded, the device must be configured by an explicit SYSMAN
CONNECT command, as follows:
$ RUN SYS$SYSTEM:SYSMAN
SYSMAN> IO CONNECT GKpd0u /NOADAPTER/DRIVER=SYS$GKDRIVER
On VAX and Alpha systems, GK is the device mnemonic for the generic SCSI
class driver (GKDRIVER); p represents the SCSI port ID (for instance, the
controller ID A or B); d represents the SCSI device ID (a digit from 0 to 7); 0
signifies the digit zero; and u represents the SCSI logical unit number (a digit
from 0 to 7).
Multiple devices residing on any SCSI bus in the system can share GKDRIVER
as a class driver, as long as a CONNECT command is issued for each target
device that requires the driver.
Because just one connection can exist through the SCSI port driver to each target,
the generic class driver cannot be used for a target if a different SCSI class driver
is already connected to that target. For example, if the SCSI disk class driver
has a connection to device ID 2 on the SCSI bus identified by SCSI port ID B
(DKB200), the generic class driver cannot be used to communicate with this disk.
An attempt to connect GKDRIVER for this target results in GKB200 being placed
off line.

8.6.1 Disabling the Autoconfiguration of a SCSI Device (VAX Only)

On VAX systems, in special cases you may need to prevent the autoconfiguration
facility from loading the disk or tape class driver for a device with a specific
port ID and device ID. This would be the case if a SCSI device, supplied by a
source other than Compaq, should identify itself as either a random-access or
sequential-access device and were to be controlled by the generic SCSI class
driver.
To disable the loading of a disk or tape driver for any given device ID, OpenVMS
defines the special system parameter SCSI_NOAUTO.
The SCSI_NOAUTO system parameter, as shown in Figure 83, stores a bit
mask of 32 bits in which the low-order byte corresponds to the first SCSI bus
(PKA0), the second byte corresponds to the second SCSI bus (PKB0), and so on.
For each SCSI bus, setting the low-order bit inhibits automatic configuration
of the device with SCSI device ID 0; setting the second low-order bit inhibits
automatic configuration of the device with SCSI device ID 1, and so forth. For
instance, the value 0000200016 would prevent the device with SCSI ID 5 on the
bus identified by SCSI port ID B from being configured. By default, all of the bits
in the mask are cleared, allowing all devices to be configured.

8.7 Assigning a Channel to GKDRIVER

On VAX and Alpha systems, an application program assigns a channel to the
generic SCSI class driver using the standard call to the $ASSIGN system service,
as described in the OpenVMS System Services Reference Manual. The application
program specifies a device name and a word to receive the channel number.

Using the OpenVMS Generic SCSI Class Driver 89

Using the OpenVMS Generic SCSI Class Driver

8.8 Issuing a $QIO Request to the Generic Class Driver
Figure 83 SCSI_NOAUTO System Parameter
07

07

07

SCSI Device ID

SCSI Port ID
ZK1371AGE

8.8 Issuing a $QIO Request to the Generic Class Driver

The format of the Queue I/O Request ($QIO) system service that initiates
a request to the SCSI generic class driver is as follows. This explanation
concentrates on the special elements of a $QIO request to the SCSI generic
class driver. For a detailed description of the $QIO system service, refer to the
OpenVMS System Services Reference Manual.
VAX MACRO Format
$QIO [efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6]
High-Level Language Format
SYS$QIO ([efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6])
Arguments
chan
I/O channel assigned to the device to which the request is directed. The chan
argument is a word value containing the number of the channel, as returned by
the Assign I/O Channel ($ASSIGN) system service.
func
Longword value containing the IO$_DIAGNOSE function code. Only the IO$_
DIAGNOSE function code is implemented in the generic SCSI class driver.
iosb
I/O status block. The iosb argument is required in a request to the generic SCSI
class driver; it has the following format:
31

16 15
Transfer count
(loworder)

31

24 23

SCSI STS

0
VMS status code

16 15

IOSB 1

0
Transfer count
(highorder)

IOSB 2
ZK1372AGE

The status code provides the final status indicating the success or failure of the
SCSI command. The SCSI status byte contains the status value returned from
the target device, as defined in the ANSI SCSI specification. The transfer count
field specifies the actual number of bytes transferred during the SCSI bus DATA
IN or DATA OUT phase.
810 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.8 Issuing a $QIO Request to the Generic Class Driver
[efn]
[astadr]
[astprm]
These arguments apply to $QIO system service completion. For an explanation of
these arguments, refer to the OpenVMS System Services Reference Manual.
p1
Address of a generic SCSI descriptor of the following format:
31

0
opcode

flags

SCSI command address

SCSI command length

12

SCSI data address

16

SCSI data length

20

SCSI pad length

24

phase change timeout

28

disconnect timeout

32
36

reserved
56
ZK1373AGE

p2
Length of the generic SCSI descriptor.
Descriptor Fields
opcode
Currently, the only supported opcode is 1, indicating a pass-through function.
Other opcode values are reserved for future expansion.
flags
Bit map having the following format:
31

4
reserved

dpr syn

dis

dir

ZK1374AGE

Bits in the flags bit map are defined as follows:

Using the OpenVMS Generic SCSI Class Driver 811

Using the OpenVMS Generic SCSI Class Driver

8.8 Issuing a $QIO Request to the Generic Class Driver
Field

Definition

dir

Direction of transfer.
If this bit is set, the target is expected at some time to enter the DATA IN
phase to send data to the host. To facilitate this, the port driver maps the
specified data buffer for write access.
If this bit is clear, the target is expected at some time to enter the DATA OUT
phase to receive data from the host. To facilitate this, the port driver maps the
specified data buffer for read access.
The generic SCSI class driver ignores the dir flag if either the SCSI data
address or SCSI data length field of the generic SCSI descriptor is zero.

dis

Enable disconnection.
If this bit is set, the target device is allowed to disconnect during the execution
of the command.
If this bit is clear, the target cannot disconnect during the execution of the
command.
Note that targets that hold on to the bus for long periods of time without
disconnecting can adversely affect system performance. See Section 8.5.2 for
additional information.

syn

Enable synchronous mode.

If this bit is set, the port driver uses synchronous mode for data transfers, if
both the host and target allow this mode of operation.
If this bit is clear, or synchronous mode is not supported by either the host or
target, the port driver uses asynchronous mode for data transfers.
See Section 8.5.1 for additional information.

dpr

Disable port retry.

If this bit is clear, the port driver retries, up to three times, any command that
fails with a timeout, bus parity, or invalid phase transition error.
If this bit is set, the port driver does not retry commands for which it detects
failure.
See Section 8.5.3 for additional information.

SCSI command address

Address of a buffer containing a SCSI command.
SCSI command length
Length of the SCSI command. The maximum length of the SCSI command is 128
bytes.
SCSI data address
Address of a data buffer associated with the SCSI command.
If the dir bit is set in the flags field, data is written into this buffer during the
execution of the command. Otherwise, data is read from this buffer and sent to
the target device.
If the SCSI command requires no data to be transferred, then the SCSI data
address field should be clear.
SCSI data length
Length, in bytes, of the data buffer pointed to by the SCSI data address field.
The maximum data buffer size is 65,535 bytes.
If the SCSI command requires no data to be transferred, then this field should be
clear.

812 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.8 Issuing a $QIO Request to the Generic Class Driver
SCSI pad length
This field is used to accommodate SCSI device classes that require that the
transfer length be specified in terms of a larger data unit than the count of bytes
expressed in the SCSI data length field. If the total amount of data requested
in the SCSI command does not match that specified in the SCSI data length
field, this field must account for the difference.
For example, suppose an application program is using the generic class driver
to read the first 2 bytes of a disk block. The length field in the SCSI READ
command contains 1 (indicating one logical block, or 512 bytes), while the SCSI
data length field contains a 2. The SCSI pad length field must contain the
difference, 510 bytes.
For most transfers, this field should contain 0. Failure to initialize the SCSI pad
length field properly causes port driver timeouts and SCSI bus resets.
phase change timeout
Maximum number of seconds for a target to change the SCSI bus phase or
complete a data transfer. A value of 0 causes the SCSI port drivers default phase
change timeout value of 4 seconds to be used.
See Section 8.5.4 for additional information.
disconnect timeout
Maximum number of seconds for a target to reselect the initiator to proceed with
a disconnected I/O transfer. A value of 0 causes the SCSI port drivers default
disconnect timeout value of 4 seconds to be used.
See Section 8.5.4 for additional information.

8.9 Generic SCSI Class Driver Device Information

A call to the Get Device/Volume Information ($GETDVI) system service returns
the following information for any device serviced by the generic SCSI class driver.
(Refer to the description of the $GETDVI system service in the OpenVMS System
Services Reference Manual.)

Using the OpenVMS Generic SCSI Class Driver 813

Using the OpenVMS Generic SCSI Class Driver

8.9 Generic SCSI Class Driver Device Information
$GETDVI returns the following device characteristics when you specify the item
code DVI$_DEVCHAR:
DEV$M_AVL

Available device

DEV$M_IDV

Input device

DEV$M_ODV

Output device

DEV$M_SHR

Shareable device

DEV$M_RND

Random-access device

DVI$DEVCLASS returns the device class, which is DC$_MISC; DVI$DEVTYPE

returns the device type, which is DT$_GENERIC_SCSI.

8.10 Call a Generic SCSI Class Driver

Example 81 is an application that uses the generic SCSI class driver to send a
SCSI INQUIRY command to a device.
Example 81 Generic SCSI Class Driver Call Example
/*
GKTEST.C
This program uses the SCSI generic class driver to send an inquiry command
to a device on the SCSI bus.
*/
#include ctype
/* Define the descriptor used to pass the SCSI information to GKDRIVER */
#define
#define
#define
#define
#define
#define
#define
#define
#define

OPCODE 0
FLAGS 1
COMMAND_ADDRESS 2
COMMAND_LENGTH 3
DATA_ADDRESS 4
DATA_LENGTH 5
PAD_LENGTH 6
PHASE_TIMEOUT 7
DISCONNECT_TIMEOUT 8

#define FLAGS_READ 1
#define FLAGS_DISCONNECT 2
#define GK_EFN 1
#define SCSI_STATUS_MASK 0X3E
#define INQUIRY_OPCODE 0x12
#define INQUIRY_DATA_LENGTH 0x30
globalvalue
IO$_DIAGNOSE;
short
gk_chan,
transfer_length;
int
i,
status,
gk_device_desc[2],
gk_iosb[2],
gk_desc[15];
(continued on next page)

814 Using the OpenVMS Generic SCSI Class Driver

Using the OpenVMS Generic SCSI Class Driver

8.10 Call a Generic SCSI Class Driver
Example 81 (Cont.) Generic SCSI Class Driver Call Example
char
scsi_status,
inquiry_command[6] = {INQUIRY_OPCODE, 0, 0, 0, INQUIRY_DATA_LENGTH, 0},
inquiry_data[INQUIRY_DATA_LENGTH],
gk_device[] = {"GKA0"};
main ()
{
/* Assign a channel to GKA0 */
gk_device_desc[0] = 4;
gk_device_desc[1] = &gk_device[0];
status = sys$assign (&gk_device_desc[0], &gk_chan, 0, 0);
if (!(status & 1)) sys$exit (status);
/* Set up the descriptor with the SCSI information to be sent to the target */
gk_desc[OPCODE] = 1;
gk_desc[FLAGS] = FLAGS_READ + FLAGS_DISCONNECT;
gk_desc[COMMAND_ADDRESS] = &inquiry_command[0];
gk_desc[COMMAND_LENGTH] = 6;
gk_desc[DATA_ADDRESS] = &inquiry_data[0];
gk_desc[DATA_LENGTH] = INQUIRY_DATA_LENGTH;
gk_desc[PAD_LENGTH] = 0;
gk_desc[PHASE_TIMEOUT] = 0;
gk_desc[DISCONNECT_TIMEOUT] = 0;
for (i=9; i<15; i++) gk_desc[i] = 0;
/* Clear reserved fields */
/* Issue the QIO to send the inquiry command and receive the inquiry data */
status = sys$qiow (GK_EFN, gk_chan, IO$_DIAGNOSE, gk_iosb, 0, 0,
&gk_desc[0], 15*4, 0, 0, 0, 0);
/* Check the various returned status values */
if (!(status & 1)) sys$exit (status);
if (!(gk_iosb[0] & 1)) sys$exit (gk_iosb[0] & 0xffff);
scsi_status = (gk_iosb[1] >> 24) & SCSI_STATUS_MASK;
if (scsi_status) {
printf ("Bad SCSI status returned: %02.2x\n", scsi_status);
sys$exit (1);
}
/* The command succeeded. Display the SCSI data returned from the target */
transfer_length = gk_iosb[0] >> 16;
printf ("SCSI inquiry data returned: ");
for (i=0; i<transfer_length; i++) {
if (isprint (inquiry_data[i]))
printf ("%c", inquiry_data[i]);
else
printf (".");
}
printf ("\n");
}

Using the OpenVMS Generic SCSI Class Driver 815

9
Local Area Network (LAN) Device Drivers
This chapter describes the QIO interface of local area network (LAN) drivers that
control the LAN devices.
In addition to the QIO interface, the OpenVMS operating system supports
another interface into LAN drivers. The VMS Communications Interface (VCI)
provides a low overhead, privileged interface.

9.1 Local Area Network (LAN) Terminology

The following is a list of terms relevant to local area networks:

CSMA/CD Stands for carrier sense multiple access with collision detection,
a technique that mediates demands by nodes for a single shared network
channel; carrier sense determines whether the communications medium is
already in use, while collision detection detects when more than one node is
attempting to transmit.

Ethernet One of the earliest and the most common local area networks
(LANs), Ethernet can refer to either a general LAN application (for example,
Ethernet address) or to the specific CSMA/CD technology that implements
the Intel, Xerox, and Digital intercompany Ethernet specifications. The data
transmission rate is 10 Mb/s.

Fast Ethernet This technology is an extension of Ethernet to a transmission

rate of 100 Mb/s using the CSMA/CD access method.

Gigabit Ethernet This technology is an extension of Ethernet and Fast

Ethernet to a data transmission rate of 1000 Mb/s (1 gigabit/sec), using the
CSMA/CD access method.

FDDI Fiber Distributed Data Interface is a 100 Mb/s token ring LAN
technology standardized by the American National Standards Institute
(ANSI).

Token Ring This LAN is the IEEE 802.5 standard token passing ring. The
data transmission rate is 4 or 16 Mb/s.

ATM Asynchronous transfer mode (ATM) is supported for emulated local

area networks (ELANs) and conforms to the standards defined by the ATM
Forums LANE V1.0 specifications. The Classical Internet Protocol (CLIP)
over ATM is supported only on the DGLTA, DGLPA, and DGLPB devices and
conforms to the standards defined in the RFC 1577 specification.

9.2 Supported Communication Devices

Section 9.2.1 and Section 9.2.2 show the communication devices supported on the
OpenVMS operating system.

Local Area Network (LAN) Device Drivers 91

Local Area Network (LAN) Device Drivers

9.2 Supported Communication Devices
9.2.1 OpenVMS VAX LAN Devices
On VAX systems, Table 91 lists the supported devices.
Table 91 Supported OpenVMS VAX Systems LAN Devices
Medium

Bus

Device

Device
Name

DECnet
Name
Device Type

Version

CSMA/CD

XMI

DEMNA

EXc0

MNA

V5.3

CSMA/CD

Local

SGEC

EZc0

ISA

DT$_EZ_SGEC

V5.3

CSMA/CD

Local

LANCE

ESc0

SVA

DT$_ES_LANCE

V4.4

CSMA/CD

TURBOchannel PMAD

ECc0

MXE

DT$_EC_PMAD

V5.5-2HW

CSMA/CD

TURBOchannel DELTA

ECc0

MXE

DT$_EC_PMAD

V5.5-2HW

CSMA/CD

Q-bus

DESQA

ESc0

SVA

DT$_ES_LANCE

V5.0

CSMA/CD

Q-bus

DELQA

XQc0

QNA

DT$_XQ_DELOA

V5.0

CSMA/CD

Q-bus

DEQTA

XQc0

QNA

DT$_XQ_DEQTA

V5.3

CSMA/CD

Q-bus

DEQNA

XQc0

QNA

DT$_DEQNA

V4.0

CSMA/CD

Q-bus

KFE52

EFc0

KFE

DT$_FT_NI

V5.4

CSMA/CD

UNIBUS

DEUNA

XEc0

UNA

DT$_DEUNA

V4.0

CSMA/CD

UNIBUS

DELUA

XEc0

UNA

DT$_DELUA

V4.0

CSMA/CD

BI

DEBNA

ETc0

BNA

DT$_ET_DEBNA

V4.4

CSMA/CD

BI

DEBNK

ETc0

BNA

DT$_ET_DEBNA

V4.4

CSMA/CD

BI

DEBNT

ETc0

BNA

DT$_ET_DEBNA

V4.4

CSMA/CD

BI

DEBNI

ETc0

BNA

DT$_ET_DEBNI

V5.2

FDDI

XMI

DEMFA

FXc0

MFA

DT$_FX_DEMFA

V5.4-3

FDDI

TURBOchannel DEFZA

FCc0

FZA

DT$_FC_DEFZA

V5.5-2HW

FDDI

TURBOchannel DEFTA

FCc0

FZA

DT$_FC_DEFTA

V6.0

FDDI

Q-bus

FQc0

FQA

DT$_FQ_DEFQA

V6.1

DEFQA

DT$_EX_DEMNA

Note
The DEQTA device is also known as the DELQA-YM. Also note that
the device name is the name of the template device that is used by
applications to identify the LAN device. The "c" in the device name
indicates the controller letter, for example, A, B, and so on.

9.2.2 OpenVMS Alpha LAN Devices

On Alpha systems, Table 92 lists the supported devices.

92 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.2 Supported Communication Devices
Table 92 Supported OpenVMS Alpha LAN Devices
Device

Device
Name

DECnet
Name
Device Type

Version

XMI

DEMNA

EXc0

MNA

DT$_EX_DEMNA

V1.0

Local

TGEC

EZc0

ISA

DT$_EZ_TGEC

V1.0

TURBOchannel COREIO

ESc0

SVA

DT$_ES_LANCE

V1.0

CSMA/CD

TURBOchannel PMAD

ECc0

MXE

DT$_EC_PMAD

V1.0

CSMA/CD

TURBOchannel DELTA

ECc0

MXE

DT$_EY_NITC2

V6.1

CSMA/CD

EISA

DE422

ERc0

ERA

DT$_ER_DE422

V1.5

CSMA/CD

EISA

DE425

ERc0

ETA

DT$_ER_TULIP

V6.1

CSMA/CD

ISA

DE200

ERc0

ERA

DT$_ER_LANCE

V6.1

CSMA/CD

ISA

DE201

ERc0

ERA

DT$_ER_LANCE

V6.1

CSMA/CD

ISA

DE202

ERc0

ERA

DT$_ER_LANCE

V6.1

CSMA/CD

ISA

DE203

ERc0

ERA

DT$_ER_LEMAC

V6.2

CSMA/CD

ISA

DE204

ERc0

ERA

DT$_ER_LEMAC

V6.2

CSMA/CD

ISA

DE205

ERc0

ERA

DT$_ER_LEMAC

V6.2

CSMA/CD

Embedded

Tulip

EWc0

EWA

DT$_EW_TULIP

V6.1

CSMA/CD

PCI

DE434

EWc0

EWA

DT$_EW_DE435

V6.1

CSMA/CD

PCI

DE435

EWc0

EWA

DT$_EW_DE435

V6.1

CSMA/CD

PCI

DE436

EWc0

EWA

DT$_EW_DE435

V6.1

CSMA/CD

PCI

DE450

EWc0

EWA

DT$_EW_DE450

V6.2

CSMA/CD

PCI

DE500XA

EWc0

EWA

DT$_EW_DE500

V6.2

CSMA/CD

PCI

DE500AA

EWc0

EWA

DT$_EW_DE500

V6.2

CSMA/CD

PCI

DE500BA

EWc0

EWA

DT$_EW_DE500

V6.2

CSMA/CD

PCI

DE504BA

EWc0

EWA

DT$_EW_DE504

V7.1-1H1

CSMA/CD

PCI

DE500FA

EWc0

EWA

DT$_EW_DE500

V7.1

CSMA/CD

PCI

P2SE

EWc0

EWA

DT$_EW_DE500

V7.2

CSMA/CD

PCI

P2SE+

EWc0

EWA

DT$_EW_DE500

V7.2

CSMA/CD

Embedded

21142

EWc0

EWA

DT$_EW_DE500

V7.2

CSMA/CD

Embedded

21143

EWc0

EWA

DT$_EW_DE500

V7.2

CSMA/CD

PCMCIA

3COM
3C589B

EOc0

CEC

DT$_EO_3C589

V6.2-1H2

CSMA/CD

PCI

DEGPASA

EWc0

EWA

DT$_EW_DEGPA

V7.1-2

CSMA/CD

PCI

DEGPATA

EWc0

EWA

DT$_EW_DEGPA

V7.1-2

CSMA/CD

PCI

DE600

EIc0

EIA

DT$_EI_82558 or
DT$_EI_82559

V7.1-2

Medium

Bus

CSMA/CD
CSMA/CD
CSMA/CD

(continued on next page)

Local Area Network (LAN) Device Drivers 93

Local Area Network (LAN) Device Drivers

9.2 Supported Communication Devices
Table 92 (Cont.) Supported OpenVMS Alpha LAN Devices
Medium

Bus

Device

Device
Name

DECnet
Name
Device Type

Version

CSMA/CD

PCI

DE602

EIc0

EIA

DT$_EI_82558 or
DT$_EI_82559

V7.1-2

CSMA/CD

PCI

Shared
Memory

EBc0

EBA

DT$_EB_SMLAN

V7.1-2

FDDI

XMI

DEMFA

FXc0

MFA

DT$_FX_DEMFA

V1.0

FDDI

FutureBus+

DEFAA

FAc0

FAA

DT$_FA_DEFAA

V1.5

FDDI

TURBOchannel DEFZA

FCc0

FZA

DT$_FC_DEFZA

V1.0

FDDI

TURBOchannel DEFTA

FCc0

FZA

DT$_FC_DEFTA

V1.5

FDDI

EISA

DEFEA

FRc0

FEA

DT$_FR_DEFEA

V1.5-1H1

FDDI

PCI

DEFPA

FWc0

FPA

DT$_FW_DEFPA

V6.2

TokenRing

TURBOchannel DETRA

ICc0

TRA

DT$_IC_DETRA

V6.1

TokenRing

EISA

DW300

IRc0

TRE

DT$_IR_DW300

V6.1

TokenRing

ISA

DW110

IRc0

TRE

DT$_IR_DW300

V6.2

TokenRing

PCI

PBXNPAA

IWc0

TRE

DT$_IW_TI380PCI

V6.2-1H1

TokenRing

PCI

PBXNPDA

IWc0

TRE

DT$_IW_RACORE

V7.1-1H1

ATM

TURBOchannel DGLTA

HCc0
/ELc0

DT$_HC_OTTO

V6.2

ELA

HWc0
/ELc0

DT$_HW_OTTO

V7.1-1H1

ELA

HWc0
/ELc0

DT$_HW_METEOR

V7.1-2

ELA

HWc0
/ELc0

DT$_HW_HE155

V7.2-1

ELA

HWc0
/ELc0

DT$_HW_HE622

V7.2-1

ELA

ATM
ATM
ATM
ATM

PCI
PCI
PCI
PCI

DGLPB
DGLPA
DAPBA
DAPCA

Note
The EL device is the emulated LAN device associated with the physical
ATM device.

9.2.3 Supported Industry Standards

Ethernet drivers support the following features:

Ethernet and IEEE 802.3 packet format

Physical layer identified as type 10Base5 (ThickWire), 10Base2 (ThinWire),

and 10BaseT (twisted pair)

Fast Ethernet and IEEE 802.3u packet format

Fast Ethernet physical layer identified as type 100BaseTX

94 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.2 Supported Communication Devices

Gigabit Ethernet and IEEE 802.3z packet format

Gigabit Ethernets physical layer is identified as type 1000BaseT for

unshielded twisted pair (UTP), 1000Base-SX for multimode fiber-optic
cables.

Gigabit Ethernet maximum frame size of 9018 bytes (limited to 7552 bytes in
OpenVMS Version 7.3-1 and earlier)

FDDI drivers support the following features:

FDDI packet format

Transmission and reception of frame control (FC) priority

Token Ring drivers support the following features:

IEEE 802.5 packet format

ATM drivers over ELAN support the following features:

Ethernet and IEEE 802.3 packet format

UNI Version 3.0 or 3.1 signaling protocol

LAN emulation (LANE) Version 1.0

Maximum frame sizes of 1516, 4544, and 9234 bytes

All LAN drivers support the following features:

802.2 packet format

IEEE 802.2 Class I service including the unnumbered information (UI),

exchange identification (XID) commands and responses, and TEST commands
and responses

IEEE 802.2 Class II service may be specified where the functions are provided
by the user application

6-byte destination and source address fields

Contrary to the IEEE 802.2 Standard, the Global DSAP (FF) must be enabled as
a Group SAP to receive messages with the Global DSAP in the destination SAP
field.
FDDI conforms to the ANSI Standards defined in the following documents:

ANSI X3.139-1987 FDDI Media Access Control (MAC)

ANSI X3.148-1988 FDDI Physical Layer Protocol (PHY)

ANSI X3.166-1990 FDDI Physical Layer Medium Dependent (PMD)

9.3 LAN Controller Characteristics

System software and user applications communicate with other systems through
the LAN controllers using the QIO interface defined by the OpenVMS LAN
driver software. This interface is described later in this chapter. The LAN
driver software allows communication with the different LAN technologies in a
consistent manner.

Local Area Network (LAN) Device Drivers 95

Local Area Network (LAN) Device Drivers

9.3 LAN Controller Characteristics
The LAN controllers implement the Ethernet, FDDI, Token Ring, and ATM
specifications. The Ethernet specification is described in The Ethernet-Data Link
Layer and Physical Specification. The FDDI specifications are available from
ANSI. The Token Ring specifications are available from IEEE. The ATM LAN
Emulation specifications are available from the ATM Forum. The Classical IP
over ATM specification (RFC 1577) is available from the Internet Engineering
Task Force (IETF).
Ethernet includes Fast Ethernet (802.3u) and Gigabit Ethernet (802.3z). See
Section 9.4 and Section 9.5 for more information.
Ethernet, FDDI, Token Ring, and ATM networks can be configured to form
a single extended LAN using FDDI-Ethernet bridges, FDDI and Ethernet
switches, Token Ring bridges and routers, and ATM switches. This allows
applications running on a system connected by a LAN controller of one technology
to communicate with applications running on another system connected by a
different type of LAN controller.

9.4 Fast Ethernet LAN Devices (Alpha Only)

Fast Ethernet (802.3u) is an extension of the IEEE 802.3 standard. It typically
runs over twisted-pair wiring. It increases the data transmission rate from 10
to 100 Mb/s and decreases the maximum length of a network segment. Fast
Ethernet controllers allow either 10 or 100 Mb/s operation for compatibility with
existing 10 Mb/s controllers.
Table 93 shows the types of cabling used for Fast Ethernet.
Table 93 Fast Ethernet Cabling
Cable

Description

100BaseTX

Works with twisted-pair cabling. It provides full-duplex

communication, using only two of the four pairs of wires.

100BaseFX

Uses fiber optic cabling. Used mainly for backbones by connecting

Fast Ethernet repeaters placed around a building. It gives protection
from electromagnetic noise and increases security. It also allows longer
distances between network devices.

9.4.1 Fast Ethernet NICDE500

Table 94 lists and describes the devices and drivers of the Fast Ethernet
adapters on Alpha PCI-based systems that the OpenVMS operating system
supports.
Table 94 DE500 Adapters
Device

Driver

Description

DE500XA

SYS$EWDRIVER.EXE

10,100 Mb UTP, no auto-negotiation

DE500AA

SYS$EWDRIVER.EXE

10,100 Mb UTP

DE500BA

SYS$EWDRIVER_
DE500BA.EXE

10,100 Mb UTP

DE500FA

SYS$EWDRIVER_
DE500BA.EXE

Multimode fiber, 100 Mb

96 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.4 Fast Ethernet LAN Devices (Alpha Only)
9.4.2 Fast Ethernet NICDE600
The Intel 82558 and 82559 are PCI Ethernet chips, which are used in the DE60x
series of Compaq Ethernet NICs. These NICs are equivalent to the Compaq
standard numbered NICs, NC31xx series.
Each NIC is a 10BaseT or 100BaseTX PCI Ethernet NIC. The LAN driver that
controls the NIC is SYS$EIDRIVER.EXE.
Table 95 lists and describes the devices and drivers of each Fast Ethernet
adapter.
Table 95 DE600 Adapters
Device

Driver

Description

DE600AA

SYS$EIDRIVER.EXE

10,100 Mb, UTP

DE602AA

SYS$EIDRIVER.EXE

10,100 Mb, UTP, dual

DE602BA

SYS$EIDRIVER.EXE

10,100 Mb, UTP. dual

DE602BB

SYS$EIDRIVER.EXE

10,100 Mb, UTP, dual

DE602TA

SYS$EIDRIVER.EXE

10,100 Mb, UTP, daughter card

DE602FA

SYS$EIDRIVER.EXE

100 Mbit multimode fiber, daughter card

Embedded
82559ER

SYS$EIDRIVER.EXE

10,100 Mbit UTP

9.5 Gigabit Ethernet LAN Devices (Alpha Only)

Gigabit Ethernet (802.3z) is an extension of the IEEE 802.3 standard. It
runs over fiber-optic cabling and twisted-pair wiring. It increases the data
transmission rate to 1000 Mb/s. The frame formats are identical to Ethernet
and Fast Ethernet which allows good interoperability across these technologies.
Gigabit Ethernet is suitable as a high-speed backbone interconnect but may
be used to connect high-performance workstations or systems that need the
increased bandwidth. Twisted-pair Gigabit controllers allow either 10, 100, or
1000 Mb/s operation for compatibility with existing 10 or 100 Mb/s networks.
Table 96 shows the types of cabling used for Gigabit Ethernet.
Table 96 Gigabit Ethernet Cabling
Cable

Description

1000Base-SX

Works with multimode fiber optic cabling. Used mainly for shorter
backbone applications. It supports distances of up to 550 meters.

1000Base-LX

Works with singlemode fiber optic cabling. Used mainly for longer fiber
backbones and campus backbones. It supports distances of up to 5
kilometers.

1000BaseT

Works with unshielded copper cabling. Used mainly for short distance
applications. It supports a signal transmission over four pairs of
category 5 unshielded twisted pair (UTP), covering distances up to 100
meters, or networks with a diameter of 200 meters.

OpenVMS supports the DEGPA Gigabit Ethernet LAN controller on Alpha

PCI-based systems.

Local Area Network (LAN) Device Drivers 97

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA

9.6 Gigabit Ethernet NICDEGPA

The DEGPA series of Compaq Gigabit Ethernet NICs uses the Tigon2 PCI
Gigabit Ethernet chip. Each NIC is a 10BaseT, 100BaseTX, 1000BaseTX, or
1000BaseSX PCI Ethernet NIC. The LAN driver that controls the DEGPA NIC is
SYS$EW1000A.EXE.
Table 97 lists and describes the devices and drivers of the DEGPA.
Table 97 DEGPA Devices
Device

Driver

Description

DEGPASA

SYS$EW1000A.EXE

Multimode fiber

DEGPATA

SYS$EW1000A.EXE

10,100,1000 Mb UTP

9.6.1 DEGPA Internal Counters

With LANCP, the command SHOW DEVICE/INTERNAL_COUNTERS EWc
displays the entire set of internal counters maintained by the driver. Some
counters are special debug counters. These are not displayed unless the
additional qualifier /DEBUG is specified. The debug counters include the address
of the status block, statistics block, and the contents of significant CSRs. The
significant CSRs are read just prior to returning the internal counters to LANCP
and when the system is shutting down.
The LAN$SDA SDA extension also displays the complete set of internal counters
with the command LAN INTERNAL/DEVICE=EWc. This extension includes the
debug counters.
The following sections present various groupings of internal counters. The
definition of these counters may change from one driver version to the next.

9.6.2 Basic Counters

Table 98 describes the basic counters displayed by the DEGPA Gigabit Ethernet
NIC.
Table 98 DEGPA Status and Counters
Status/Counters

Meaning

Driver version

The driver version number is numbered 1...n that

usually is identical to the xn ID displayed by an
ANA/IMAGE of the driver image. It includes variant
information, if any. The full driver version includes
the target OpenVMS release and is displayed by SDA
LAN/DEV=EWA in the quadword driver version field.

Firmware version

The version number is in hexadecimal; it is read from

right to left.

Device interrupts

The number of times the interrupt service routine was

called.

Events completed

The number of events completed from the event ring.

Link transitions

The total number of link state up and link state down

events.
(continued on next page)

98 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 98 (Cont.) DEGPA Status and Counters
Status/Counters

Meaning

Transmit timeouts

The number of times the driver has timed out a

transmit and has reset the device and completed
outstanding I/O requests with error status.

Initialization timeouts

The number of times the driver has timed out an

initialization request and has reset the device and
completed outstanding I/O requests with error status.

Resets issued

The number of times the driver has reset the device.

Initialization done

The number of times the driver performed the device

initialization procedure (done when the first user is
started).

Initialization (with or without

map registers)

The number of unit initializations executed, since unit

initialization is only executed once, this counter will
be one. Which counter is set depends whether map
registers were used to map the device data structures.

User change requests

The number of user startup and shutdown requests

processed by the driver, generally one or two when a
user starts up, and one when a user stops.

PTE to PFN translations

The number of times a global page was encountered

during a chained transmit request, causing the driver
to convert an invalid PTE to a valid PFN.

Transmits queued

The number of transmit requests queued because the

link was not available or because too many transmit
requests were already outstanding.

Transmit errors (too few

segments)

The number of transmit requests completed with error

status (SS$_INCSEGTRA) because the application did
not specify the transmit buffer completely.

Transmit copies (too many

segments)

The number of transmit requests that exceeded the

maximum number of chain segments that the driver
can handle; the counter then copied some of them to a
temporary buffer so that it could transmit the packet.

Jumbo transmits issued

The number of transmit requests with a packet length

exceeding 1514 bytes, excluding CRC.

Transmits issued (using map

registers)

The number of transmit requests that were described

to the device using map registers because part of the
request existed in memory outside the DMA window.

Jumbo receives issued

The number of jumbo receive buffers allocated and

given to the device.

Receives issued (using map

registers)

The number of receive buffers that were described to

the device using map registers, because part of the
request existed in memory outside the DMA window,
because the receive buffer crossed a page boundary, or
because the receive buffer was a jumbo buffer.

Soft errors

The number of times errors were recovered in the

driver by resetting the device.

Commands outstanding

The number of commands outstanding to the device.

Commands queued

The number of commands that have been queued to

the device.
(continued on next page)

Local Area Network (LAN) Device Drivers 99

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 98 (Cont.) DEGPA Status and Counters
Status/Counters

Meaning

Command pending mask

The commands that the driver has not yet issued to

the device.

Invalid command

The event code of the last event.

Unexpected event

The event code of the last event that was not

recognized.

Rescheduled forks

The number of times that a rescheduled fork was done.

In transmit and receive processing, the driver limits
the amount of time spent in the fork process before
rescheduling.

Standard receive buffers

The number of 1518 byte receive buffers owned by the

device.

Standard receive buffer

deallocations

The number of 1518 byte buffer deallocations done by

the driver because the number of outstanding buffers
exceeded the maximum number allowed by the driver.

Jumbo receive buffers (current)

The number of 7552 byte receive buffers owned by the

device.

Jumbo receive buffers

(minimum)

The minimum number of 7552 byte receive buffers

owned by the device. This is set to 1 initially. After
the first jumbo receive, the driver sets the minimum to
32.

Jumbo receive buffer allocations

The number of jumbo receive buffer allocations done

by the driver.

Jumbo receive buffer

deallocations

The number of 7552 byte buffer deallocations done by

the driver because the number of outstanding buffers
exceeded the maximum number allowed by the driver.

Standard buffer size (bytes)

The size of the standard receive buffers. It is the

CSMA/CD packet size, 1518 bytes including header
and CRC, plus the overhead of the receive buffer
structure (640 bytes).

Standard packet size (bytes)

This is the CSMA/CD size (1518 bytes).

Jumbo buffer size (bytes)

The size of the jumbo receive buffers. The device

allows up to 9018-byte packets, including header
and CRC, plus the 640-byte receive buffer structure
overhead. But the driver limits the buffer size to the
maximum size supported by the pool lookaside lists,
which is 8192 bytes in current and recent OpenVMS
releases. In a future release, the buffer size will be
9018 plus 640 bytes of overhead, rounded up to the
next 64-byte boundary, to accommodate the full jumbo
packet size.

Requested speed

The speed requested by a user.

Requested link value

The link control bits set by the driver to use during

link initialization.

Current link state

The current link state determined by the device.

(continued on next page)

910 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 98 (Cont.) DEGPA Status and Counters
Status/Counters

Meaning

Jumbo packets

The size of jumbo frames, which is 7552 bytes. The

SYSGEN parameter LAN_FLAGS bit 6 or the LANCP
command SET DEV/[NO]JUMBO determines whether
the maximum user data size for VCI applications is
the standard size (1518 bytes less header and CRC) or
jumbo size. The default is disabled, LAN_FLAGS bit 6
set to zero.

Link autonegotiation

Determines whether the link state that the driver

requests the device to use allows autonegotiation.
The SYSGEN parameter LAN_FLAGS bit 5 or the
LANCP command SET DEV/[NO]AUTO determines
the setting. The default is enabled.

DMA operation

Displays the result of the determination by the device

whether it is in a 32-bit or 64-bit PCI bus.

Current PCI state

The current value of the PCI state register

which controls the DMA hardware and other PCI
characteristics.

Transmit coalesce value

Transmit interrupts are generated every 32 coalesce

value transmit completions, but no later than 50
"interrupt delay" microseconds after completion of a
packet.

Receive coalesce value

Receive interrupts are generated every 32 coalesce

value receive completions, but no more than 50
"interrupt delay" microseconds after receipt of a
packet.

Transmit interrupt delay

Transmit interrupts are generated every 32 coalesce

value transmit completions, but no more than 50
interrupt delay microseconds after completion of a
packet.

Receive interrupt delay

Receive interrupts are generated every 32 coalesce

value receive completions, but no more than 50
interrupt delay microseconds after receipt of a
packet.

Current EXE$GL_ABSTIM_
TICS

The current time in 10-millisecond ticks of the

counters request from LANCP.

Statistics EXE$GL_ABSTIM_
TICS

The time in 10-millisecond ticks of the last statistics

update from the device.

9.6.3 Medium Access Control (MAC) Counter Statistics

Table 99 describes the definitions of MACs counter statistics that are derived
from the RFC 1643 standards.
Table 99 MAC Counter Statistics
Counter Statistics

Meaning

Alignment errors

The number of packets received with CRC errors and

that are not an integral number of bytes long. These
packets are discarded and are then counted by the
device.
(continued on next page)

Local Area Network (LAN) Device Drivers 911

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 99 (Cont.) MAC Counter Statistics
Counter Statistics

Meaning

FCS errors

The number of packets received with CRC errors and

that are an integral number of bytes long. These
packets are discarded and are then counted by the
device.

Single collisions

The number of successfully transmitted packets which

encountered exactly one collision during transmission
(successful after retransmit). These occur in halfduplex mode only.

Multiple collisions

The number of successfully transmitted packets

that encountered more than one collision during
transmission (successful after multiple retransmits).
These occur in half-duplex mode only.

SQE test errors

The number of SQE test errors generated after

successful transmission. These are also called
heartbeat errors. Some network hardware does not
support this test function, so this error happens on
every transmit. These occur in half-duplex mode only.

Deferred transmits

The number of successful transmits that were delayed

because the medium was busy. These occur in halfduplex mode only.

Late collisions

The number of times a collision was detected longer

than 512 bit-times into the transmission of a packet.
The transmit fails. These occur in half-duplex mode
only.

Excessive collisions

The number of transmits which failed due to excessive

collisions. These occur in half-duplex mode only.

Internal MAC transmit errors

The number of transmits that failed because of an

internal MAC sublayer error that is not late collision,
excessive collisions, or carrier sense error.

Carrier sense errors

The number of transmits that failed because carrier

was not present during any or all of the transmission
attempt.

Frame too long errors

The number of received frames that were longer than

the jumbo packet size. These packets are discarded
and are then counted by the device.

Internal MAC receive errors

The number of receive packets discarded because of

an internal MAC sublayer error that is not frame too
long, alignment error, or FCS error. These packets are
discarded and are then counted by the device.

9.6.4 Interface Counter Statistics

Table 910 describes the interface counter statistics that are derived from the
RFC 1213 standards. Definitions in quotation marks are extracted from the RFC
1213 standard.

912 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 910 Interface Counter Statistics
Counter Statistics

Meaning

Index

ifIndex: "A unique value for each interface. Its value

ranges between 1 and the value of ifNumber. The value
for each interface must remain constant at least from
one re-initialization of the entitys network management
system to the next re-initialization."

Type

ifType: "The type of interface, distinguished according

to the physical/link protocol(s) immediately below the
network layer in the protocol stack. The value set by the
NIC is 6 ethernet-csmacd."

Mtu

ifMtu: "The size of the largest datagram which can

be sent/ received on the interface, specified in octets.
For interfaces that are used for transmitting network
datagrams, this is the size of the largest network
datagram that can be sent on the interface." This field
is specified by the driver and is set to the jumbo buffer
size previously described.

Speed

ifSpeed: "An estimate of the interfaces current bandwidth

in bits per second. For interfaces which do no vary in
bandwidth or for those where no accurate estimation
can be made, this object should contain the nominal
bandwidth."

Admin requested status

ifAdminStatus: "The desired state of the interface. The

testing(3) state indicates that no operational packets can
be passed." The values are 1Up; 2Down; 3Testing.
This field is always 1 because the driver does not obtain
statistical updates from the NIC in any other state.

Operational status

ifOperStatus: "The current operational state of the

interface. The testing(3) state indicates that no
operational packets can be passed." The values are 1Up;
2Down; 3Testing. This field is always 1 because the
driver does not obtain statistical updates from the NIC in
any other state.

Last change

ifLastChange: "The value of sysUpTime at the time the

interface entered its current operational state. If the
current state was entered prior to the last re-initialization
of the local network management subsystem, then this
object contains a zero value."

Inbound discards

ifInDiscards: "The number of inbound packets which were

chosen to be discarded even though no errors had been
detected to prevent their being deliverable to a higherlayer protocol. One possible reason for discarding such a
packet could be to free up buffer space."

Inbound errors

ifInErrors: "The number of inbound packets that

contained errors preventing them from being deliverable
to a higher-level protocol."

Inbound unknown protos

ifInUnknownProtos: "The number of packets received

via the interface which were discarded because of an
unknown or unsupported protocol."
(continued on next page)

Local Area Network (LAN) Device Drivers 913

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 910 (Cont.) Interface Counter Statistics
Counter Statistics

Meaning

Outbound discards

ifOutDiscards: "The number of outbound packets which

were chosen to be discarded even though no errors had
been detected to prevent their being transmitted. One
possible reason for discarding such a packet could be to
free up buffer space."

Outbound errors

ifOutErrors: "The number of outbound packets that could

not be transmitted because of errors."

Outbound queue length

ifOutQlen: "The length of the output packet queue (in

packets)."

Physical address

ifPhysAddress: "The interfaces address at the protocol

layer immediately below the network layer in the
protocol stack. For interfaces which do not have such
an address (e.g., a serial line), this object should contain
an octet string of zero length."

Description

ifDescr: "A textual string containing information about

the interface. This string should include the name of the
manufacturer, the product name and the version of the
hardware interface." The value set by the NIC is blank.

Bytes received

ifHCInOctets: "The total number of octets received on the

interface, including framing characters. This object is a
64-bit version of ifInOctets."

Unicast packets received

ifHCInUcastPkts: "The number of packets, delivered

by this sub-layer to a higher (sub-) layer, which were
not addressed to a multicast or broadcast address at this
sub-layer. This object is a 64-bit version of ifInUcastPkts."

Multicast packets received

ifHCInMulticastPkts: "The number of packets, delivered

by this sub-layer to a higher (sub-) layer, which were
addressed to a multicast address at this sub-layer. For
a MAC layer protocol, this includes both Group and
Functional addresses. This object is a 64-bit version of
ifInMulticastPkts."

Broadcast packets received

ifHCInBroadcastPkts: "The number of packets, delivered

by this sub-layer to a higher (sub-) layer, which were
addressed to a broadcast address at this sub-layer. This
object is a 64-bit version of ifInBroadcastPkts." It appears
the NIC does not implement the distinctions between
broadcast multicast and nonbroadcast multicast. So this
counter is zero.

Bytes sent

ifHCOutOctets: "The total number of octets transmitted

out of the interface, including framing characters. This
object is a 64-bit version of ifOutOctets."

Unicast packets sent

ifHCOutUcastPkts: "The total number of packets that

higher-level protocols requested be transmitted, and
which were not addressed to a multicast of broadcast
address at this sub-layer, including those that were
discarded or not sent. This object is a 64-bit version of
ifOutUcastPkts."
(continued on next page)

914 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 910 (Cont.) Interface Counter Statistics
Counter Statistics

Meaning

Multicast packets sent

ifHCOutMulticastPkts: "The total number of packets

that higher-level protocols requested be transmitted, and
which were addressed to a multicast address at his sublayer, including those that were discarded or not sent.
For a MAC layer protocol, this includes both Group and
Functional addresses. This object is a 64-bit version of
ifOutMulticastPkts."

Broadcast packets sent

ifHCOutBroadcastPkts: "The total number of packets that

high-level protocols requested be transmitted, and which
were addressed to a broadcast address at this sub-layer,
including those that were discarded or not sent. This
ojbect is a 64-bit version of ifOutBroadcastPkts." The NIC
does not implement the distinction between broadcast
multicast and nonbroadcast multicast. So this counter is
zero.

Link updown trap enable

ifLinkUpDownTrapEnable: "Indicates whether

linkUp/linkDown traps should be generated for this
interface. By default, this object should have the value
enabled (1) for interfaces which do not operate on top of
any other interface (as defined in the ifStackTable), and
disabled (2) otherwise." This value is set to 2 by the NIC.

High speed status

ifHighSpeed: "An estimate of the interfaces current

bandwidth in units of 1,000,000 bits per second. If this
object reports a value of n, then the speed of the interface
is somewhere in the range of n-500,000 to n+499,999.
For interfaces which do not vary in bandwidth or for those
where no accurate estimation can be made, this object
should contain the nominal bandwidth. For a sub-layer
which has no concept of bandwidth, this object should be
zero." This value is set to 1000 by the NIC.

Promiscuous mode status

ifPromiscuousMode: "This object has a value of false

(2) if this interface only accepts packets/frames that
are addressed to this station. This object has a value
of true (1) when the station accepts all packets/frames
transmitted on the media. The value true (1) is only
legal on certain type of media. If legal, setting this
object to a value of true (1) may require the interface
to be reset before becoming effective. The value of
ifPromiscuousMode does not affect the reception of
broadcast and multicast packets/frames by the interface."

Connector present status

ifConnectorPresent: "This object has the value true (1)

if the interface sublayer has a physical connector and the
value false (2) otherwise."

9.6.5 Host Commands Statistics

Table 911 describes statistics that are maintained by the device and the count
commands that are issued by the driver in the command ring.

Local Area Network (LAN) Device Drivers 915

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 911 Host Commands Statistics
Command

Meaning

Host state commands

The number of times the driver changed the host state. It

can be in one of two states, up or down. The driver issues
a host state up command when the first user starts, and a
host state down when the last user stops.

FDR filtering commands

Unused.

Set receive producer index

commands

Unused.

Update GENCOMM statistics

commands

Unused.

Reset jumbo ring commands

Unused.

Add mcast address

commands

The number of times the driver issued a multicast address

add command to the device to add a new multicast
address to the multicast filtering table. The driver
maintains its own multicast address table and updates
the device whenever its table changes.

Del mcast address commands

The number of times the driver issued a multicast address

delete command to the device to delete a multicast
address from the multicast filtering table. The driver
maintains its own multicast address table and updates
the device whenever its table changes.

Set promiscuous mode

commands

The number of times the driver enabled or disabled

promiscuous receive mode. The driver issues these
commands whenever a user enables or disables
promiscous mode.

Link negotiate commands

The number of times the driver issued a link negotiate

command to the device to cause it to set up the link
again. The driver issues this command only when a
device-specific (debug) command is issued via LANCP to
explicitly set a new link value.

Set MAC address commands

The number of times the driver issues a set MAC address

command to change the MAC address of the device.
Typically, this is issued by the driver once when DECnet
starts.

Clear profile commands

Unused.

Set multicast mode

commands

The number of times the driver enabled or disabled

all multicast receive mode. The driver issues these
commands whenever a user enables or disables all
multicast mode.

Clear statistics commands

The number of clear statistics commands the driver issued

to the device, on device startup. Normally, there is one
clear statistics command for every reset that is done, plus
any device-specific (debug) commands issued via LANCP
to explicitly clear the counters.

Set receive jumbo producer

index commands

Unused.

Set receive mini producer

index commands

Unused.

Refresh statistics commands

Unused.
(continued on next page)

916 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 911 (Cont.) Host Commands Statistics
Command

Meaning

Unknown commands

The number of commands issued by the driver that were

not recognized by the device.

9.6.6 Event Statistics

Table 912 describes event statistics.
Table 912 Event Statistics
Event

Meaning

FW operational events

The number of TG_EVENT_FIRMWARE_

OPERATIONAL events generated.

Statistics updated events

The number of TG_EVENT_LINK_STATE_CHANGED

events generated.

Error events

The number of TH_EVENT_ERROR events generated.

MCast list updated events

The number of TG_EVENT_MULTICAST_LIST_

UPDATED events generated.

Reset jumbo ring events

The number of TG_EVENT_RESET_JUMBO_RING

events generated.

Set send producer index events

The number of times the NIC has seen updates to the

send producer index.

Set send consumer index events

The number of times the send consumer index was

updated.

Set receive return producer

index events

The number of times the receive return producer index

was updated.

9.6.7 Interrupt Statistics

Table 913 describes interrupt statistics.
Table 913 Interrupt Statistics
Interrupt Statistics

Meaning

Interrupts generated

The number of interrupts generated by the NIC.

Interrupts avoided

The number of interrupts avoided by the NIC (because of

interrupt mitigation).

Event threshold hit

The number of times the event max coalesce BD threshold

was reached.

Send BD threshold hit

The number of times the BD_FLAG_COAL_NOW flag

was set or that the send max coalesce BD threshold was
reached.

Receive BD threshold hit

The number of times the receive max coalesce BD

threshold was reached. When this happens, the firmware
updates the receive return producer index to the host.

Local Area Network (LAN) Device Drivers 917

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
9.6.8 DMA Statistics
Table 914 describes the DMA statistcs.
Table 914 DMA Statistics
DMA Statistics

Meaning

DMA read overrun errors

The number of times DMA read overrun error occurred.

DMA read underrun errors

The number of times DMA read underrun error occurred.

DMA write overrun errors

The number of times DMA write overrun error occurred.

DMA write underrun errors

The number of times DMA write underrun error occurred.

DMA write master abort

errors

The number of times DMA read Master Abort error

occurred.

DMA read master abort

errors

The number of times DMA write Master Abort error

occurred.

9.6.9 Ring Statistics

Table 915 describes the counters track descriptor and buffer usage by the
firmware in the device.
Table 915 Ring Counters
Ring Counters

Meaning

DMA write ring full

The number of times the DMA write ring was full.

DMA read ring full

The number of times the DMA read ring was full.

Event ring full

The number of times the device event ring was full.

Event producer ring full

The number of times the DMA write ring was full

trying to write either the DMA event or event producer
to host memory.

MAC transmit descriptor ring

full

The number of times the MAC transmit descriptor

ring was full.

Transmit buffer space full

The number of times the transmit buffer space was

full.

No more DMA write descriptors

The number of times the device ran out of DMA write

descriptors.

No more receive BDs

The number of times the device ran out of receive

buffer descriptors.

No space in return ring

The number of times the device could not place a

buffer descriptor in the return ring because it was full.

Send BDs owned by NIC

The number of send buffer descriptors currently being

processed by the device.

Receive BDs owned by NIC

The number of standard (1518 bytes) receive buffer

descriptors owned by the device.

Jumbo receive BDs owned by

NIC

The number of jumbo receive buffer descriptors owned

by the device.

Mini receive BDs owned by NIC

Unused, always zero.

(continued on next page)

918 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 915 (Cont.) Ring Counters
Ring Counters

Meaning

Total receive BDs owned by NIC

The total number of receive buffer descriptors owned

by the device.

Jumbo frames split into multiple

standard BDs

The number of times a jumbo frame was split into

multiple standard buffer descriptors.

Bus hang cleared

The number of times an SBus DMA bug was worked

around.

Posting an event was delayed

The number of times posting an event was delayed.

9.6.10 Internal MAC Receive Statistics

Table 916 describes the counters that monitor the receive processing by the
NIC.
Table 916 Internal MAC Receive Statistics
Internal MAC Receive Statistics

Meaning

Packets dropped due to late collisions

The number of receive packets dropped

because of late collisions. These occur in
half-duplex mode only.

Packets dropped because of loss of link

The number of receive packets dropped

because of loss of link, such as a cable
disconnect, broken cable, NIC hardware
failure, or link partner hardware failure.

Packets dropped because of PHY decode errors

The number of receive packets dropped

because of PHY decode errors, such as a
hardware failure that generates so much
noise that the PHY cannot recognize the
signal, or some other hardware failure.

Packets aborted by MAC because of remote

errors

The number of receive packets aborted

by MAC because of remote errors, such
as receiving a packet smaller than 64
bytes, a PHY decode error, a collision
detected during receipt, or an error
occurring during gigabit half-duplex
frame extension.

Frames dropped due to lack of NIC internal

resources

The number of receive packets dropped

because of lack of NIC internal
resource, such as memory space or MAC
descriptors. This usually occurs because
the bus is too slow.

Unicast packets droppedDA doesnt match

The number of receive packets dropped

because the destination address in the
packet does not match our address.
This happens regularly on full-duplex
repeaters or during switch flooding.

Multicast packets droppedDA doesnt match

The number of receive packets dropped

because the destination address in the
packet does not match the multicast
address list.
(continued on next page)

Local Area Network (LAN) Device Drivers 919

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 916 (Cont.) Internal MAC Receive Statistics
Internal MAC Receive Statistics

Meaning

Flow control packets received

The number of flow control packets

received.

Packets dropped because of lack of space

The number of receive packets dropped

because of lack of space. This usually
occurs because the bus is too slow.

Packets dropped because of collisions

The number of receive packets dropped

because of collisions. This is caused
by two nodes sending messages
simultaneously. These occur in halfduplex mode only.

MAC receive attentions

The number of MAC receive attentions,

including receive descriptor attention,
receive buffer attention, flow control XON
sent, flow control XOFF sent, and FIFO
overrun.

Link state change attentions

The number of link state change

attentions, including auto-negotiation
changed, link state error, and link ready
changed.

Sync lost attentions

The number of sync lost attentions.

Link config attentions

The number of link config attentions,

possibly caused by the link partner
changing its link configuration. This
does not indicate hardware failure unless
the actual number of link configuration
changes is smaller than this counter.

MAC resets

The number of times the MAC was reset.

This is caused by link lost and trying to
reestablish the link.

Receive BD attentions

Unused.

Receive buffer attentions

The number of receive buffer descriptor

attentions which is triggered by the
number of received buffer descriptors
reaching a predefined threshold.

No frame cleanups after receive buffer

attention

The number of times the receive buffer

got cleaned up when it was full and the
frame received count was zero. This
indicates that the data in the receive
buffer is garbage and can happen if
the remote mode sent continuous error
frames.

One frame cleanups after receive buffer

attention

The number of times the receive buffer

got cleaned up when it was full and
the frame received count was one. This
can happen if the remote node sent
continuous error frames.
(continued on next page)

920 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.6 Gigabit Ethernet NICDEGPA
Table 916 (Cont.) Internal MAC Receive Statistics
Internal MAC Receive Statistics

Meaning

Multiple frame cleanups after receive buffer

attention

The number of times the receive buffer

got cleaned up when it was full and the
frame received count was greater than 1.
This can happen if the remote node sent
continuous error frames.

Receive buffer cleanups by time

The number of times the device set up a

timer to wait for receive buffer space to
be freed up when the receive buffer was
full. This can happen if the remote node
sent continuous error frames.

DMA cleanups due to DMA attentions

The number of times the DMA buffer got

cleaned up when the receive buffer was
full. This can happen if the remote node
sent continuous error frames.

9.6.11 Internal MAC Transmit Statistics

The following counters monitor the transmit processing by the NIC:
MAC TRANSMIT 1..15
collisions

Transmit collision histogram. These are updated in half-duplex

mode only.

Transmit attentions

Total number of transmit attentions.

9.7 Gigabit Ethernet NICDEGXA

The Broadcom 5703 (Tigon3) based Gigabit Ethernet NIC is an intelligent
NIC that performs all of its primary functions using a set of hardware state
machines. This functionality is contained in the Broadcom 5703 application
specific integrated circuit (ASIC).
The Broadcom 5703 ASIC contains two DMA engines, one read, one write; it
also contains a 10/100/1000 MAC, a set of hardware state machines, and two 133
Mhz processors. The NIC includes initialization firmware and PXE boot ROM
firmware.
The Broadcom 5703 is PCI 2.2 and PCIX 1.0 compatible.
Table 917 lists and describes the devices and drivers of the DEGXA.
Table 917 DEGXA Devices
Device

Driver

Description

DEGXAUA

SYS$EW5700.EXE

10,100,1000 Mb UTP

DEGXASA

SYS$EW5700.EXE

Multimode fiber

DEGXALA

SYS$EW5700.EXE

Singlemode fiber

DEGXATA

SYS$EW5700.EXE

10,100,1000 Mb UTP

Embedded
5703c

SYS$EW5700.EXE

10,100,1000 Mb UTP

Local Area Network (LAN) Device Drivers 921

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
9.7.1 DEGXA Internal Counters
With LANCP, the command SHOW DEVICE/INTERNAL_COUNTERS EWc
displays the entire set of internal counters maintained by the driver. Some
counters are special debug counters. These are not displayed unless the
additional qualifier /DEBUG is specified. The debug counters include the address
of the status block, statistics block, and the contents of significant CSRs. The
significant CSRs are read just prior to returning the internal counters to LANCP
and when the system is shutting down.
The LAN$SDA SDA extension also displays the complete set of internal counters
with the command LAN INTERNAL/DEVICE=EWc. This extension includes the
debug counters.
The following sections present various groupings of internal counters. The
definition of these counters may change from one driver version to the next.

9.7.2 Basic Counters

Table 918 describes the basic counters displayed by the DEGXA Gigabit
Ethernet NIC.
Table 918 DEGXABasic Counters
Counter

Meaning

Driver version

The driver version number is numbered 1...n that

usually is identical to the xn ID displayed by an
ANA/IMAGE of the driver image. The full driver
version includes the target OpenVMS release and is
displayed by SDA LAN/DEV=EWA in the quadword
driver version field.

Firmware version

The version of the firmware embedded in the driver

and loaded into the device at initialization time.
Version 0 indicates that no firmware is loaded.

Device revision

The hardware revision level identified by the

Broadcom 5700 chip revision. It is given as A0, A1,
B0, B1, B2, C0, C1, C2. If the version is later than
the driver recognizes, it is given as >C2, for example.
The actual revision is located in bits <31:16> of the
Misc Host Control register displayed in the Registers
section.

Actual PHY ID

The actual PHY ID found on the device. Bits <31:10>

is the OUI, bits <9:4> is the Model number and bits
<3:0> is the revision.

Current PHY ID

The current PHY ID that the driver is using.

Device interrupts

The number of interrupts generated by the NIC and

fielded by the driver.

Link checks

The number of times the driver checked the current

link status.

Link transitions

The number of link transitions seen by the driver.

Transmit timeouts

The number of times the driver has timed out a

transmit and has reset the device and completed
outstanding I/O with error status.

Resets issued

The number of times the driver has reset the device.

(continued on next page)

922 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 918 (Cont.) DEGXABasic Counters
Counter

Meaning

Initialization done

The number of times the driver performed the device

initialization procedure (done when the first user is
started).

Initializations (with or without

map registers)

The number of unit initializations executed, since unit

initialization is only executed once, this counter will
be one. Which counter is set depends whether map
registers were used to map the device data structures.

User change requests

The number of user startup and shutdown requests

processed by the driver, generally one or two when a
user starts up, and one when a user stops.

PTE to PFN translations

The number of times a global page was encountered

during a chained transmit request, whereupon the
driver converted an invalid PTE to a valid PFN.

Transmits queued

The number of transmit requests queued either

because the link was not available or because too
many transmit requests were outstanding already.

Transmit errors (too few

segments)

The number of transmit requests completed with error

status (SS$_INCSEGTRA) because the application did
not completely specify the transmit buffer.

Transmit copies (too many

segments)

The number of transmit requests which exceeded the

maximum number of chain segments that the driver
can handle; it then copied some of them to a temporary
buffer so that it could transmit the packet.

Jumbo transmits issued

The number of transmit requests with a packet length

exceeding 1514 bytes (excluding CRC).

Jumbo receives issued

The number of jumbo receive buffers allocated and

given to the device.

Receives issued (using map

registers)

The number of receive buffers which described to the

device using map registers, because part of the request
existed in memory outside the DMA window, because
the receive buffer crossed a page boundary, or because
the receive buffer was a jumbo buffer.

Soft errors

The number of times errors were recovered in the

driver by resetting and reinitializing the device.

Rescheduled forks

The number of times that a rescheduled fork was done.

In transmit and receive processing, the driver limits
the amount of time spent in the fork process before
rescheduling.

Standard receive buffers

The number of 1518-byte receive buffers owned by

the device. The device may actually own fewer than
this if the driver has not processed some of the receive
buffers that the device has completed.

Standard receive buffer

deallocations

The number of 1518-byte buffer deallocations done by

the driver because the number of outstanding buffers
exceeded the maximum number allowed by the driver.
(continued on next page)

Local Area Network (LAN) Device Drivers 923

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 918 (Cont.) DEGXABasic Counters
Counter

Meaning

Jumbo receive buffers (current)

The number of jumbo receive buffers owned by the

device. The device may actually own fewer than this
if the driver has not processed some of the receive
buffers that the device has completed.
When this count goes below "jumbo receive buffers
(minimum)," the driver immediately supplies more to
the device. In addition, driver ensures the number
of buffers owned by the device is in the range of
minimum to maximum receive buffers that can be set
by the LANCP command.

Jumbo receive buffers

(minimum)

The minimum number of jumbo receive buffers owned

by the device. This is set to 32 initially. After the first
jumbo receive, the driver sets the minimum to 128.

Jumbo receive buffer allocations

The number of jumbo receive buffer allocations done

by the driver.

Jumbo receive buffer

deallocations

The number of jumbo buffer deallocations done by

the driver because the number of outstanding buffers
exceeded the maximum number allowed by the driver.

Standard buffer size (bytes)

The size of the standard receive buffers. It is the

CSMA/CD packet size, 1518 bytes including header
and CRC, plus the overhead of the receive buffer
structure which is 640 bytes.

Standard packet size (bytes)

The CSMA/CD packet size (1518 bytes).

Jumbo buffer size (bytes)

The size of the jumbo receive buffers. The device

allows up to 9018-byte packets, including header
and CRC, plus the 640-byte receive buffer structure
overhead. But the driver limits the buffer size to the
maximum size supported by the pool lookaside lists,
which is 8192 bytes in current and recent OpenVMS
releases. In a future release, the buffer size will be
9018 plus 640 bytes of overhead rounded up to the
next 64-byte boundary, to accommodate the full jumbo
packet size.

Jumbo packet size (bytes)

The size of the jumbo receive buffers. It is 7552 or

9018 bytes, depending whether the pool lookaside lists
support the larger buffer size.

Requested link settings

The speed and duplex mode requested by a user. For

the DEGXASA (fiber), the only speed is 1000 Mb/s.
For the DEGXATA (UTP), a user may request 10,
100, or 1000 Mb/s via SETMODE QIO or LANCP
command.

Current link settings

The current link state.

DMA width (bits)

The device determines whether it is in a 32-bit or

64-bit PCI bus, and the result of that determination is
displayed.

BUS speed (Mhz)

The device determines whether it is in a low speed

(33-Mhz PCI or 66-Mhz PCIX bus) or high speed
(66-Mhz PCI or 133-Mhz PCIX bus), and the result of
that determination is displayed.
(continued on next page)

924 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 918 (Cont.) DEGXABasic Counters
Counter

Meaning

BUS type

The device determines whether it is in a PCI or PCIX

bus, and the result of that determination is displayed.

MSI status

Contents of the MSI_CONTROL register that gives

MSI status. If MSI is enabled, bit <0> is set. Bits
<3:1> are the number of requested messages (always
set to 3 by the device). Bits <6:4> are the number of
messages allocated to the device by the system. If the
/DEBUG qualifier is specified, more MSI context is
displayed, such as MSI Address and Data registers.

Transmit coalesce value

Transmit interrupts are generated every 32 "coalesce

value" transmit completions, but no more than 50
"interrupt delay" microseconds after completion of a
packet.

Receive coalesce value

Receive interrupts are generated every 32 "coalesce

value" receive completions, but no more than 50
"interrupt delay" microseconds after receipt of a
packet.

Transmit interrupt delay

Transmit interrupts are generated every 32 "coalesce

value" transmit completions, but no more than 50
"interrupt delay" microseconds after completion of a
packet.

Receive interrupt delay

Receive interrupts are generated every 32 "coalesce

value" receive completions, but no more than 50
"interrupt delay" microseconds after receipt of a
packet.

Initialization delay

The total time (in microseconds) waiting for the device

during initialization including shutdown. This is
displayed if the /DEBUG qualifier is specified.

Link setup delay

The total time (in microseconds) waiting for the device

during setup of the link. This is displayed if the
/DEBUG qualifier is specified.

Current EXE$GL_ABSTIM_
TICS

The current time in 10-millisecond ticks of the

counters request from LANCP.

Status block VA

The system virtual address of the status block. It is

included as a matter of convenience for looking at the
status block in SDA. This is displayed in the /DEBUG
qualifier is specified.

Statistics block VA

The system virtual address of the statistics block. It

is included as a matter of convenience for looking at
the Statistics block in SDA. This is displayed if the
/DEBUG qualifier is specified.

9.7.3 Status Block

Table 919 lists and describes fields that are part of the 128-byte status and ring
indexes written to host memory after each interrupt.

Local Area Network (LAN) Device Drivers 925

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 919 Status Block Fields
Field

Meaning

Reserved1

Unused.

Status

After an interrupt, this longword is nonzero. The

driver fork process clears the status longword so the
driver can recognize whether there is pending work to
be done (checking the ring indexes for completions, or
checking the link status). The bits in the longword are
defined as follows:
Bit 1Link changed status
Bit 2Status block updated flag

Receive mini consumer index

Unused.

Receive jumbo consumer index

Current position of the NIC in the jumbo receive buffer

ring.

Receive standard consumer

index

Current position of the NIC in the standard receive

buffer ring.

Unused1

Unused.

Receive ring 0 producer index

Current position of the NIC in the receive return ring.

Send ring 0 consumer index

Current position of the NIC in the send ring.

9.7.4 Statistics Block

The NIC updates the statistics once a second. The driver maintains the bytes
and packets that are transmitted and received but obtains the error counters
from this statistics block. The block includes many counters that are useful in
diagnosing device and system operations. The statistics are displayed in sections
according to the type of counter.
9.7.4.1 Statistics: Receive MAC
Table 920 lists and describes the receive MAC statistics.
Table 920 Receive MAC Statistics
Counter

Meaning

Bytes received

The total number of bytes successfully received.

Runt packets received (bad CRC)

The number of runt packets less than 64 bytes long

received and discarded.

Unicast packets received

The number of packets successfully received that were

not addressed to a multicast or broadcast address.

Multicast packets received

The number of packets successfully received that

were addressed to a multicast address, but not the
broadcast address.

Broadcast packets received

The number of packets successfully received that were

addressed to the broadcast address.

FCS errors

The number of packets received with CRC errors and

that are an integral number of bytes long. These
packets are discarded and are counted by the device.
(continued on next page)

926 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 920 (Cont.) Receive MAC Statistics
Counter

Meaning

Alignment errors

The number of packets received with CRC errors and

that are not an integral number of bytes long. These
packets are discarded and are counted by the device.

MAC control XON frames

received

The number of XON frames received. An XON frame

is a MAC control frame with a pause command and a
length equal to zero.

MAC control XOFF frames

received

The number of XOFF frames received. An XOFF

frame is a MAC control frame with a pause command
and a length greater than zero.

MAC control other frames

received

The number of other MAC control frames received.

These are MAC control frames with no pause
command.

Transmitting disabled (xoff)

The number of times the transmitter was disabled

because of a receive of an XOFF frame.

Frame too long errors

The number of received frames that were longer than

the jumbo packet size. These packets are discarded
and are counted by the device.

Frame exceed jabber time errors

The number of frames received that are longer than

the specified maximum frame time, for example, a
jabber frame.

Runt packets received (good

CRC)

The number of frames received with a size less than

64 bytes (including a correct CRC field).

Length errors (length field neq

actual)

The number of frames received where the 802 length

field does not match the total frame size.

Length errors (type field 15231535)

The number of frames received where the field is in

the range of 1523 to 1535, for example, an invalid type
field and a length error.

9.7.4.2 Statistics: Transmit MAC

Table 921 lists and describes the counters for the transmit MAC statistics.
Table 921 Transmit MAC Statistics
Counter

Meaning

Bytes sent

The total number of bytes successfully transmitted.

Collisions experienced

The total number of collisions experienced.

XON packets sent

The number of XON packets sent in support of flow

control.

XOFF packets sent

The number of XOFF packets sent in support of flow

control.

Flow control sequences done

The number of flow control sequences done.

Internal MAC transmit errors

The number of transmits that failed because of an

internal MAC sublayer error that is not late collision,
excessive collisions, or carrier sense error.
(continued on next page)

Local Area Network (LAN) Device Drivers 927

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 921 (Cont.) Transmit MAC Statistics
Counter

Meaning

Single collisions

The number of successfully transmitted packets that

encountered exactly one collision during transmission
(successful after retransmit). These occur in halfduplex mode only.

Multiple collisions

The number of successfully transmitted packets

that encountered more than one collision during
transmission (successful after multiple retransmits).
These occur in half-duplex mode only.

Deferred transmits

The number of successful transmits that were delayed

because the medium was busy. These occur in halfduplex mode only.

Excessive collisions

The number of transmits that failed because of

excessive collisions. These occur in half-duplex mode
only.

Late collisions

The number of times a collision was detected longer

than 512 bit-times into the transmission of a packet.
The transmit fails. These occur in half-duplex mode
only.

MAC transmit 2..15 collisions

The number of successfully transmitted packets

which encountered n collisions during transmission
(successful after n retransmits). These occur in halfduplex mode only.

Unicast packets sent

The total number of successfully transmitted packets

that were not addressed to a multicast or broadcast
address.

Multicast packets sent

The total number of successfully transmitted packets

that were addressed to a multicast address but not the
broadcast address.

Broadcast packets sent

The total number of successfully transmitted packets

that were addressed to a broadcast address.

Carrier sense errors

The number of transmits that failed because carrier

was not present during any or all of the transmission
attempts.

Outbound discards

The number of outbound packets that were chosen to

be discarded even though no errors had been detected
to prevent their being transmitted. One possible
reason for discarding such a packet could be to free up
buffer space.

Outbound errors

The number of outbound packets that could not be

transmitted because of errors.

9.7.4.3 Statistics: Receive List Placement State Machine

Table 922 lists and describes the counters for the receive list placement state
machine.

928 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 922 Receive List Placement State Machine
Counter

Meaning

Frames received onto return ring 1..16

The number of frames received onto each of the

return rings.

Frames discarded using filters

The number of frames received but discarded

after validation by the receive filters.

DMA write queue full

The number of times the DMA write queue was

full.

DMA high priority write queue full

The number of times the DMA write highpriority queue was full.

No more receive BDs

The number of times the NIC ran out of receive

buffer descriptors.

Inbound discards

The number of inbound packets that were

chosen to be discarded even though no errors
had been detected to prevent their being
deliverable to a higher-layer protocol. One
possible reason for discarding such a packet
could be to free up buffer space.

Inbound errors

The number of inbound packets that contained

errors that prevented them from being
deliverable to a higher-layer protocol.

Receive threshold hit

The number of times the receive max coalesce

frames threshold was reached, resulting in a
status block update and interrupt.

9.7.4.4 Statistics: Send Data Initiator State Machine

Table 923 lists and describes the counters for the send data initiator state
machine.
Table 923 Send Data Initiator State Machine
Counter

Meaning

Frames sent from send ring 1..16

The number of frames sent from each of the

send rings.

DMA read queue full

The number of times the DMA read queue was

full.

DMA high priority read queue full

The number of times the DMA read highpriority queue was full.

Send data completion queue full

The number of times the send data completion

flow-thorough-queue (FTQ) was full.

9.7.4.5 Statistics: Host Coalescing State Machine

Table 924 lists the counters for the host coalescing state machine statistics.

Local Area Network (LAN) Device Drivers 929

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Table 924 Host Coalescing State Machine
Counter

Meaning

Send producer index updates

The number of times the NIC has seen updates to any

send producer ring index.

Ring status updates

The number of times the status block was updated

(written to host memory). If the driver is not currently
in its interrupt service routine, an interrupt is
generated after the update.

Interrupts generated

The number of interrupts generated by the NIC.

Interrupts avoided

The number of interrupts avoided by the NIC (because

of interrupt mitigation).

Send threshold hit

The number of times the send max coalesce frames

threshold was reached, resulting in a status block
update and interrupt.

9.7.5 Fork Delay Debug Data

To help determine whether the buffering requirements of the driver and the NIC
are sufficient for the system configuration, the driver records the amount of time
from fork scheduled to the time the fork is actually run. The data is recorded in
10-millisecond increments from 10 to 310 milliseconds.
This data can be used in conjunction with the number of packets discarded
because there were insufficient buffers to determine whether the buffering
settings of the driver (minimum and maximum receive buffers) and the amount
of buffering on the NIC are sufficient for normal operation. If packets are being
discarded, the buffering should be increased until the number of packets lost is
minimal.

9.7.6 Driver Messages

The following is the last 32 driver messages broadcast to the console, describing
events such as link transitions, changes to jumbo packet settings, changes to
autonegotiation settings, and startup messages.
Driver messages are issued for the following:

Initialization failures:
Failed
Failed
Failed
Failed

to enable interrupts
during map register allocation
to enable interrupts
to read MAC address

LAN_FLAGS SYSGEN parameter changes:

Auto-negotiation disabled per SYSGEN parameter LAN_FLAGS <bit 5>
Auto-negotiation enabled per SYSGEN parameter LAN_FLAGS <bit 5>
Jumbo frames enabled per SYSGEN parameter LAN_FLAGS <bit 6>
Jumbo frames disabled per SYSGEN parameter LAN_FLAGS <bit 6>
Flow control changed per SYSGEN parameter LAN_FLAGS <bit 7>
Flow control change disallowedfull-duplex mode required
Flow control enabled per SYSGEN parameter LAN_FLAGS <bit 7>
Flow control disabled per SYSGEN parameter LAN_FLAGS <bit 7>

LANCP speed, duplex mode, auto-negotiation, and flow control changes:

Link set to speed, duplex, flow control setting

930 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.7 Gigabit Ethernet NICDEGXA
Link set to auto-negotiate speed, duplex, flow control setting

Driver detected link state change:

Link state changelink up: speed, duplex, flow control setting
Link state changelink down

9.7.7 Device-Specific Functions

The driver allows some device-specific parameters to be adjusted. These
adjustments are useful for debug purposes or for performance tuning.
You specify device specific functions by using the following LANCP command:
LANCP> SET DEVICE/DEVICE_SPECIFIC=(FUNCTION="func", VALUE=n) EWc
Like other LANCP commands which affect a device, this command requires the
SYSPRV privilege.
Table 925 lists and describes the device-specific LANCP commands.
Table 925 LANCP Device-Specific Commands
Command

Meaning

FUNCTION="CCOU"

Clears all device and driver counters. The value, if

supplied, is ignored.

FUNCTION="DXMT", VALUE=n

Changes the transmit delay value, which is the

number of microseconds after completion of a
transmit request that an interrupt is generated.
The current setting is displayed in the internal
counters. This function is applicable to Gigabit
Ethernet NICs.

FUNCTION="DRCV", VALUE=n

Changes the receive delay value, which is the

number of microseconds after completion of a
receive that an interrupt is generated.
The current setting is displayed in the internal
counters. This function is applicable to Gigabit
Ethernet NICs.

FUNCTION="CXMT",VALUE=n

Changes the transmit coalesce value, which is

the number of transmit buffer descriptors that
are processed before an interrupt is generated.
An interrupt may be generated earlier if the
transmit delay threshold is reached or when an
interrupt on behalf of receive or a link state change
is generated.
The current setting is displayed in the internal
counters. This function is applicable to Gigabit
Ethernet NICs.

FUNCTION="CRCV", VALUE=n

Changes the receive coalesce value, which is the

number of receive buffer descriptors that are filled
in before an interrupt is generated. An interrupt
may be generated earlier if the receive delay
threshold is reached or when an interrupt on behalf
of transmit or a link state change is generated.
The current setting is displayed in the internal
counters. This function is applicable to Gigabit
Ethernet NICs.

Local Area Network (LAN) Device Drivers 931

Local Area Network (LAN) Device Drivers

9.8 FDDI LAN Devices

9.8 FDDI LAN Devices

The PDQ chip is used for a series of FDDI NICs, paired with a different bus
interface to cover all of the Alpha I/O buses. Table 926 lists the buses, devices,
and drivers.
Table 926 PDQ FDDI NICs
Bus

Device

Driver

TurboChannel

DEFTA

SYS$FCDRIVER,EXE

FutureBus+

DEFFA

SYS$FADRIVER.EXE

EISA

DEFEA

SYS$FRDRIVER.EXE

PCI

DEFPA

SYS$FWDRIVER.EXE

9.9 TMS380 Token LAN Devices

The TMS380 chip is used for a series of Token Ring NICs, paired with a different
bus interface to cover all of the Alpha I/O buses. Table 927 lists the buses,
devices, and drivers.
Table 927 TMS380 Token Ring NICs
Bus

Device

Driver

TurboChannel

DETRA

SYS$ICDRIVER.EXE

EISA

DW300

SYS$IRDRIVER.EXE

ISA

DW110 (P1392+)

SYS$IRDRIVER.EXE

PCI

Racore

SYS$IWDRIVER.EXE

PCI

TC4048

SYS$IWDRIVER.EXE

9.10 LAN ATM Network Support

Asynchronous transfer mode (ATM) is a cell-oriented switching technology that
uses fixed-length packets to carry different types of data.
The ATM protocol communicates by first establishing endpoints between two
computers with a virtual circuit (VC) through one or more ATM switches. ATM
then provides a physical path for data flow between the endpoints by either a
permanent virtual circuit (PVC), or a switched virtual circuit (SVC).
Permanent Virtual Circuits (PVCs)
Permanent Virtual Circuits are set up and torn down by prior arrangement.
They are established manually by a user before the sending of any data between
endpoints on a network. Some PVCs are defined directly on the switch; others
are predefined for use in managing switched virtual circuits (SVCs).
Switched Virtual Circuits (SVC)
Switched virtual circuits require no operator interaction to create and manage
connections between endpoints. Software sets up and tears down connections
dynamically as they are needed through the request of an endpoint.

932 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.10 LAN ATM Network Support
OpenVMS has deployed ATM networks based on the ATM LANE standards
and Classical IP over ATM (RFC 1577). The following ATM adapters on Alpha
systems are supported by OpenVMS with the ATM LANE standards:
DGLTA
DGLPB
DGLPA
DAPBA
DAPCA
The following ATM adapters on Alpha systems are supported by OpenVMS with
Classical IP over ATM (RFC 1577):
DGLTA
DBLPB
DGLPA

9.10.1 LAN Emulation over an ATM Network

LAN emulation over an ATM network allows existing applications to run
essentially unchanged while also allowing the applications to run on computers
directly connected to the ATM network. The LAN emulation hides the underlying
ATM network at the media access control (MAC) layer, which provides device
driver interfaces.
Table 928 shows the four components that make up a LAN emulation over ATM
network. Of the four components, OpenVMS supports only the LAN emulation
client (LEC).
Table 928 Components of LAN Emulation over ATM Network
Component

Function

LAN emulation client (LEC)

Provides a software driver that runs on a network client

and enables LAN clients to connect to an ATM network.

LAN emulation server (LES)

Maintains a mapping between LAN and ATM addresses

by resolving LAN media access control (MAC) addresses
with ATM addresses.

Broadcast and Unknown

Server (BUS)

Maintains connections with every LAN emulation client

(LEC) in the network. For broadcast messages, the BUS
sends messages to every attached LEC. The LECs then
forward the message to their respectively attached LANs.
For multicast messages, the BUS sends messages to only
those LECs that have devices in the multicast group.
For a LEC that wants to send a regular message whose
destination MAC address is unknown, the BUS can be
used to determine this address.

LAN emulation Configuration

Server (LECS)

Provides a service for LAN emulation clients by helping

to determine which emulated LAN each of the LECs
registered users should join, since each client can specify
which emulated LAN to join.

The LEC exists on all ATM-attached computers that participate in the LAN
emulation configuration. LEC provides the ATM MAC-layer connectionless
function that is transparent to the LAN-type applications. The LEC, LES, and
BUS can exist on one ATM-attached computer or on separate computers. The
server functions usually reside inside an ATM switch, but can be implemented on
client systems.

Local Area Network (LAN) Device Drivers 933

Local Area Network (LAN) Device Drivers

9.10 LAN ATM Network Support
9.10.2 LAN Emulation Topology
Figure 91 shows the topology of a typical emulated LAN over ATM.
Figure 91 Emulated LAN Topology

Ethernet

Workstation

ATM/Ethernet
Switch

Ethernet

Workstation

LEC

Ethernet

Workstation

OpenVMS Server

OpenVMS Server

LEC

LEC
155 Mbps

LES

BUS

155 Mbps

ATM Switch

ATM Switch

NT Workstation

UNIX Server
155 Mbps

LES

LEC

BUS

155 Mbps
LEC

VM-0733A-AI

9.10.3 Classical IP Over an ATM Network

Classical IP (CLIP) implements a data-link level device that has the same
semantics as an Ethernet interface (802.3). This interface is used by a TCP/IP
protocol to transmit 802.3 (IEEE Ethernet) frames over an ATM network. The
model that OpenVMS Alpha follows for exchanging IP datagrams over ATM is
based on RFC 1577 (Classical IP over ATM).
For information on using LANCP commands to manage Classical IP, refer to the
OpenVMS System Management Utilities Reference Manual: AL.

934 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.11 Supporting and Configuring LAN Emulation over ATM

9.11 Supporting and Configuring LAN Emulation over ATM

OpenVMS provides LAN Emulation Client (LEC) support over ATM. The LAN
Emulation Client software supports IEEE/802.3 Emulated LANs, and UNI 3.0 or
UNI 3.1 and the following maximum frame size (in bytes): 1516, 4544, and 9234.
The DAPBA (155 Mb/s) and the DAPCA (622 Mb/s) are ATM adapters for
PCI-bus systems that are supported by SYS$HWDRIVER4.EXE. The following
requirement applies to the DAPBA and DAPCA adapters:
Both adapters require a great deal of non-paged pool, and therefore, care should
be taken when configuring them. For each DAPBA, Compaq recommends
increasing the SYSGEN parameter NPAGEVIR by 3000000. For each DAPCA,
Compaq recommends increasing NPAGEVIR by 6000000. To do this, add the
ADD_NPAGEVIR parameter to MODPARAMS.DAT and then run AUTOGEN.
For example, add the following command to MODPARAMS.DAT on a system with
two DAPBAs and one DAPCA:
ADD_NPAGEVIR = 12000000
The following restrictions apply to the DAPBA and DAPCA adapters:
The adapter cannot be located on a PCI bus that is located behind a
PCI-to-PCI bridge. Systems that have this configuration are the following:
Digital Personal AlphaWorkstation 600 (MIATA GL)
AlphaStation 1000A (Noritake)
COMPAQ Professional Workstation XP1000 (MONET)
Alphaserver 2000 and 2100 (SABLE)
SYS$LAN_ATM4.EXE provides OpenVMS ATM infrastructure for the DAPBA
and DAPCA adapters. SYS$ELDRIVER4.EXE provides the Emulated LAN
support for the DAPBA and DAPCA adapters.
The DGLPB (155 Mb/s) is an ATM device for PCI-bus systems that is supported
by SYS$HWDRIVER.EXE.
The DGLPA (155 Mb/s) is an ATM device for PCI-bus systems that is supported
by SY$ATMWORKS351.EXE.
The DGLTA (155 Mb/s) is an ATM device for TURBOchannel systems with the
exception of the DEC 3000-300 that is supported by SYS$HCDRIVER.EXE.
SYS$LAN_ATM.EXE provides the OpenVMS ATM infrastructure for the DGLPB,
DGLPA, and DGLTA adapters. SYS$ELDRIVER.EXE provides the Emulated
LAN support for the DGLPB, DGLPA, and DGLTA adapters.
The Emulated LAN driver provides the means for communicating over the LAN
ATM. The device type for the Emulated LAN device is DT$_EL_ELAN.
The device name for the Emulated LAN is:
ELcu
where c is the controller and u is the unit number (for example, ELA0).

9.11.1 Specifying the User to Network Interface (UNI)

The ATM software is set to autosense the UNI version by default. Setting bit 3 of
the system parameter, LAN_FLAGS, to 1 enables UNI 3.0 over all ATM adapters.
Setting bit 4 of the system parameter, LAN_FLAGS, to 1 enables UNI 3.1 over all
ATM adapters.

Local Area Network (LAN) Device Drivers 935

Local Area Network (LAN) Device Drivers

9.11 Supporting and Configuring LAN Emulation over ATM
9.11.2 Enabling SONET/SDH
The ATM drivers have the capability of operating with either synchronous optical
network (SONET) or synchronous digital hierarchy (SDH) framing. Setting bit
0 of the system parameter, LAN_FLAGS, to 1 enables SDH framing. Setting bit
0 of the system parameter, LAN_FLAGS, to 0 enables SONET framing (default).
For this to take affect, the system parameter must be specified correctly before
the ATM adapter driver is loaded.

9.11.3 Booting
OpenVMS Alpha does not support ATM adapters as boot devices.

9.11.4 Configuring an Emulated LAN (ELAN)

The LANCP utility sets up an Emulated LAN (ELAN). If the ELAN is defined
in the permanent database, these settings take affect at boot time. To define
the commands in the permanent database for specific adapters, you invoke the
DEFINE DEVICE commands. Once these commands define the adapters in the
permanent database, the ELAN can be started during system startup.
You can also invoke the LANCP SET commands to start up an ELAN after the
system is booted.
The following example shows the DEFINE DEVICE commands that define the
adapter in the permanent database.
$ mcr lancp
LANCP> define device ela0/elan=create
LANCP> define device ela0/elan=(parent=hwa0,type=csmacd,size=1516)
LANCP> define device ela0/elan=(descr="An ATM ELAN")
LANCP> define device ela0/elan=enable=startup
LANCP> list dev ela0/param
Device Characteristics,
Value
----HWA0
"An ATM ELAN"
1516
CSMA/CD
Yes
LANCP> exit
$

Permanent Database, for ELA0:

Characteristic
-------------Parent ATM device
Emulated LAN description
Emulated LAN packet size
Emulated LAN type
Emulated LAN enabled for startup

The following example shows the SET DEVICE commands required for setting
up an ELAN with the desired parameters. Note that some of the commands
generate a console message.
$ mcr lancp
LANCP> set dev ela0/elan=create
%%%%%%%%%%% OPCOM 26-MAR-2001 16:57:12.89 %%%%%%%%%%%
Message from user SYSTEM on ALPHA1
LANACP LAN Services
Found LAN device ELA0, hardware address 00-00-00-00-00-00
LANCP> set dev ela0/elan=(parent=hwa0,type=csmacd,size=1516)
LANCP> set dev ela0/elan=(descr="An ATM ELAN")
LANCP> set dev ela0/elan=enable=startup
%ELDRIVER, LAN Emulation event at 26-MAR-1996 16:57:28.78
%ELDRIVER, LAN Emulation startup: Emulated LAN 1 on device ELA0
LANCP> sho dev ela/char

936 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.11 Supporting and Configuring LAN Emulation over ATM
Device Characteristics ELA0:
Value Characteristic
----- -------------Normal Controller mode
External Internal loopback mode
CSMA/CD Communication medium
16 Minimum receive buffers
32 Maximum receive buffers
No Full duplex enable
No Full duplex operational
Unspecified Line media
10 Line speed (megabits/second)
CSMA/CD Communication medium
"HWA0" Parent ATM Device
"An ATM ELAN" Emulated LAN Description
3999990000000008002B LAN Emulation Server ATM Address
A57E80AA000302FF1300
Enabled Emulated LAN State
LANCP> exit
$
For information about using LANCP and system manager commands with
qualifiers for LAN emulation over ATM networks, refer to the OpenVMS System
Management Utilities Reference Manual: AL, and OpenVMS System Managers
Manual.

9.12 Ports and LAN Configuration

A port in a LAN configuration consists of a protocol type, a service access point
(SAP) or protocol identifier, and a controller. There are as many ports on a LAN
controller as there are protocol types, SAPs, and protocol identifiers. Each port is
independent of other ports running on the same LAN controller.
Application programs use either the LAN drivers QIO interface or VCI interface
to perform I/O operations to and from other nodes on the LAN. This chapter
describes the QIO interface. Figure 92 shows the relationship of most Ethernet
controllers to the processor and to the user application program.

Local Area Network (LAN) Device Drivers 937

Local Area Network (LAN) Device Drivers

9.12 Ports and LAN Configuration
Figure 92 Typical Ethernet Configuration

Transceiver

Transceiver
Transceiver
Cable

Transceiver
Ethernet 1,024
Transceivers in
Parallel

Ethernet Controller
(DE205, DE450, and so on)

ISA, PCI, and so on

CPU
a. Hardware Interface

Application
Program

User

Port
1

Port
2

Port
3

Port
4

Port
n

LAN Driver
(ERDRIVER, EWDRIVER, and so on)

Ethernet Controller
(DE205, DE450, and so on)
b. Software Interface
ZK1129GE

9.12.1 Driver Initialization and Operation

The following sequence initializes and starts a port on a LAN device driver:
1. Use the Assign I/O Channel ($ASSIGN) system service to assign I/O channels
to one or more of the LAN device names and devices specified in Table 91
and Table 92. $ASSIGN creates a new unit control block (UCB), to which
the channel for the port is assigned.
2. Start up the port with the set mode function and startup function modifier
(see Section 9.20.3.1). You must supply the required P2 buffer parameters
listed in Table 939.

938 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.12 Ports and LAN Configuration
3. Perform read, write, and sense mode operations as needed.
4. Shut down the port with the set mode function and shutdown function
modifier (see Section 9.20.3.4).
5. Use the Deassign I/O Channel ($DASSGN) system service to deassign the I/O
channel.
The sample programs described in Section 9.22.2 illustrate how to perform these
procedures for Ethernet and IEEE 802 ports.

9.13 Ethernet Addresses

The LAN is a medium for creating a network; it is not a network by itself. The
LAN controller and the local system constitute a node. Nodes on the LAN are
identified by unique Ethernet addresses. A message can be sent to one, several,
or all nodes on the LAN simultaneously, depending on the Ethernet address used.
You do not have to specify the Ethernet address of your own node to communicate
with other nodes on the same Ethernet; however, you do need to know the
Ethernet address of the node with which you want to communicate.

9.13.1 Format of Ethernet Addresses

An Ethernet address is 48 bits in length. Ethernet addresses are represented by
the Ethernet standard as six pairs of hexadecimal digits (six bytes), separated
by hyphens (for example, AA-01-23-45-67-FF). The bytes are displayed from left
to right in the order in which they are transmitted; bits within each byte are
transmitted from right to left. In this example, byte AA is transmitted first; byte
FF is transmitted last. (See the description of NMA$C_PCLI_PHA in Table 939,
Section 9.20.3.1, for the internal representation of addresses.)
Upon application, IEEE assigns a block of addresses to a producer of LAN nodes.
Thus, every manufacturer has a unique set of addresses to use. Normally, one
address out of the assigned block of physical addresses is permanently associated
with each controller (usually in read-only memory). This address is known as
the hardware address of the controller. Each individual controller has a unique
hardware address.

9.13.2 Ethernet Address Classifications

An Ethernet address can be a physical address of a single node or a multicast
address, depending on the value of the low-order bit of the first byte of the
address (this bit is transmitted first). Following are the two types of node
addresses:

Physical addressThe unique address of a single node on a LAN. The least

significant bit of the first byte of a physical address is 0. (For example, in
physical address AA-00-03-00-FC-00, byte AA in binary is 1010 1010, and the
value of the low-order bit is 0.)

Multicast addressA multidestination address of one or more nodes on a

given LAN. The least significant bit of the first byte of a multicast address
is 1. (For example, in the multicast address 0B-22-22-22-22-22, byte 0B in
binary is 0000 1011, and the value of the low-order bit is 1. This is the first
bit of the address as transmitted over the wire.)

Contrary to the Ethernet specification and the IEEE 802.3 Standard, the
broadcast address (FF-FF-FF-FF-FF-FF) must be enabled as a multicast address
to receive messages addressed to it.

Local Area Network (LAN) Device Drivers 939

Local Area Network (LAN) Device Drivers

9.13 Ethernet Addresses
9.13.3 Selecting an Ethernet Physical Address
The OpenVMS interface to the LAN controllers allows you to set a physical
address of the controller. The selection of the physical address of a LAN controller
is different for CSMA/CD (Ethernet and 802.3) and FDDI.
For CSMA/CD, all users of the controller must agree on this address. The first
user of the controller chooses the physical address; any additional users of the
controller must specify either the same physical address, no physical address,
or change the address (if allowed). When all channels to the controller are
shut down, the next user to start a channel chooses the physical address. The
controllers physical address is always chosen on the first successful startup when
there are no active ports. If the address is not chosen at this time, the controllers
hardware address is used as the physical address.
For CSMA/CD, the Can Change Address parameter allows the physical address
to be changed even though there are active users. If all current users of the
controller have set the NMA$C_PCLI_CCA parameter to NMA$C_STATE_ON,
then the physical address can be changed.
For FDDI, each port using a controller may specify its own unique physical
address. Any combination of sharing of physical addresses is also allowed across
the ports of an FDDI controller. For example, ports A, B, and C may use one
unique physical address and ports D and E may use another unique address.

9.13.4 Ethernet Physical and Multicast Address Values

The following are multicast addresses assigned for use in cross-company
communications:
Value

Meaning

FF-FF-FF-FF-FF-FF

Broadcast

CF-00-00-00-00-00

Loopback assistance

The following are commonly used multicast addresses:

Value

Meaning

AB-00-00-01-00-00

Dump/load assistance

AB-00-00-02-00-00

Remote console

AB-00-00-03-00-00

Level 1 and Level 2 routers

AB-00-00-04-00-00

All end nodes

09-00-2B-02-00-00

Level 2 routers

AB-00-00-05-00-00
through
AB-00-03-FF-FF-FF

Reserved for future use

AB-00-03-00-00-00

LAT

AB-00-04-00-00-00
through
AB-00-04-00-FF-FF

For use by Compaq customers for their own applications

AB-00-04-01-00-00
through
AB-00-04-01-FF-FF

Local area VMScluster

940 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.13 Ethernet Addresses
Value

Meaning

AB-00-04-02-00-00
through
AB-00-04-FF-FF-FF

Reserved for future use

09-00-2B-01-00-00

Bridge management

09-00-2B-01-00-01

Bridge hello multicast

9.13.5 Token Ring Functional Address Mapping

Except for the global broadcast address (FF-FF-FF-FF-FF-FF), Token Ring
hardware does not support the 802 standard group LAN address mechanism.
Instead, it uses functional addresses. These functional addresses are locally
administered group addresses (multicast addresses). The first two bytes of
the address are always 03-00 (canonical format), and the remaining four bytes
contain a bit mask that specifies which of the 32 possible combination masks is
being described.
Because most OpenVMS LAN applications use standard multicast addresses, a
mechanism has been designed to map functional addresses to globally and locally
administered multicast addresses. This allows applications to use the same
multicast addresses that are used in the other LAN media.
Table 929 shows the default mapping used by the OpenVMS Alpha Token Ring
drivers:

Local Area Network (LAN) Device Drivers 941

Local Area Network (LAN) Device Drivers

9.13 Ethernet Addresses
Table 929 Address Mappings of Token Ring Drivers
Multicast Address

Functional Address

Bit-Reversed

Description

09-00-2B-00-00-04

03-00-00-00-02-00

C0:00:00:00:40:00

ISO 9542 All End-system

Network Entites

09-00-2B-00-00-05

03-00-00-00-01-00

C0:00:00:00:80:00

ISO 9542 All Intermediate

System Network Entities

CF-00-00-00-00-00

03-00-00-08-00-00

C0:00:00:10:00:00

Loopback Assistance

AB-00-00-01-00-00

03-00-02-00-00-00

C0:00:40:00:00:00

MOP Dump/Load

AB-00-00-02-00-00

03-00-04-00-00-00

C0:00:20:00:00:00

MOP Remote Console

AB-00-00-03-00-00

03-00-08-00-00-00

C0:00:10:00:00:00

DNA L1 Routers

09-00-2B-02-00-00

03-00-08-00-00-00

C0:00:10:00:00:00

DNA L2 Routers

09-00-2B-02-01-0A

03-00-08-00-00-00

C0:00:10:00:00:00

DECnet Phase IVTRNAll

Phase IVTRN Routers

AB-00-00-04-00-00

03-00-10-00-00-00

C0:00:08:00:00:00

DNA End nodes

09-00-2B-02-01-0B

03-00-10-00-00-00

C0:00:08:00:00:00

Phase IV Prime Unknown

09-00-2B-00-00-07

03-00-20-00-00-00

C0:00:04:00:00:00

PCSA NETBIOS Emulatn

09-00-2B-00-00-0F

03-00-40-00-00-00

C0:00:02:00:00:00

Local Area Transport (LAT)

09-00-2B-02-01-04

03-00-80-00-00-00

C0:00:01:00:00:00

LAT Directory Service Solicit

(to slave)

09-00-2B-02-01-07

03-00-00-02-00-00

C0:00:00:40:00:00

LAT Directory Service

SolicitX Service Class

09-00-2B-04-00-00

03-00-00-04-00-00

C0:00:00:20:00:00

LAST

09-00-2B-02-01-00

03-00-00-00-08-00

C0:00:00:00:10:00

DNA Naming Service

Advertisement

09-00-2B-02-01-01

03-00-00-00-10-00

C0:00:00:00:08:00

DNA Naming Service

Solicitation

09-00-2B-02-01-02

03-00-00-00-20-00

C0:00:00:00:04:00

DNA Time Service

03-00-00-00-00-01

03-00-00-00-00-01

C0:00:00:00:00:80

NETBUI Emulation

If an application needs to change or add mappings, QIOs exist for performing

such operations. If the system or network manager has a requirement regarding
mapping of the functional addresses, the LAN control program (LANCP) utility
may be used to manage the mapping. The following example maps the multicast
address AB-01-01-01-02-03 to functional address 03-00-00-01-00-00 on Token Ring
device ICA0:.
$MCR LANCP
LANCP>SET DEVICE/MAP= _LANCP> (MULTICAST=AB-01-01-01-02-03,_LANCP> FUNCTIONAL=00-01-00-00) ICA0:
Note that it is possible for more than one multicast address to map to the same
functional address. In all cases, the use of the functional address is associated
with an individual applications protocol.

942 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.14 Configuring ISA Devices

9.14 Configuring ISA Devices

On Alpha systems, the way to configure an ISA LAN device is to type isacfg at
the console prompt (>>>). For complete information on using isacfg from your
console prompt, refer to the hardware documentation associated with your system
for more information.
To help with your configuration, become familiar with the concepts listed
in Table 930. Refer to your LAN hardware documentation for configuring
information on how to set the jumper settings for those features in Table 930.
Table 930 ISA Configuration Definitions
Concept

Explanation

ISA Slot Number

Also called node. The ISA slot number of the device.

Writing OpenVMS Alpha Device Drivers in C describes
how to number ISA slots.

IRQ

Interrupt request line. Used to establish the interrupt

level. Boards support IRQs between 1 and 15. Since
OpenVMS does not support shared IRQs, every ISA
device must have its own IRQ value reserved for it by the
console ISACFG utility.

Port Address

I/O base control status registers (CSR) address. Boards

usually have I/O addresses associated with their CSR
locations. These locations must not be used by any other
device on the system.

Memory Address

Also called shared memory. This address range is used

to share memory resident on the adapter card between
the host CPU and the LAN device on the adapter card.
If the device uses shared memory, the I/O addresses for
accessing this memory must be reserved. These locations
must not be used by any other device on the system.

DMA Channel

If the device performs direct memory access (DMA), either

slave or bus mastering, a DMA channel is required.
Channels are numbered 1 through 7, but channel 4 is
always reserved for the system. Refer to your adapter
documentation for DMA channels supported by the device.

9.14.1 OpenVMS LAN Devices Requiring Configuration

The DE203, DE204, and DE205 Ethernet and DW110 Token Ring devices require
configuration using isacfg. The following information and examples show how
this is done.
9.14.1.1 DE203 Ethernet
The DE203 is a shared memory Ethernet device. Example 91 shows how to
configure the OpenVMS software to use the DE203 device. The following example
illustrates a configuration of:

Slot 1

IO Base at %x300

IRQ 5

Local Area Network (LAN) Device Drivers 943

Local Area Network (LAN) Device Drivers

9.14 Configuring ISA Devices
Example 91 Using the isacfg at Console Prompt with the DE203
>>> isacfg -slot 1 -etyp 1 -ena 1 -irq0 5 -iobase0 %x300
-membase0 %xd0000 -memlen0 %x1000 -handle "DE20" -mk
The command ("-mk") makes an isacfg entry for an ISA device at slot 1. It is a
Single port type of device (-etyp 1). The -handle parameter tells the operating
system what type of device it is.

Shared memory at %xd0000 with length of %x10000

Note
The DE204 and DE205 devices are variants of the same adapter and are
configured in the same way as the DE203 device.

9.14.1.2 DW110 Token Ring

The DW110 is a bus mastering DMA device on the ISA bus. In addition to
setting up the ISA I/O parameters, you may configure ring speed (4 or 16 Mbits)
and media (UTP or STP). By using LANCP you can also configure ring speed and
media during system startup. Example 92 shows how to configure the OpenVMS
software to use the DW110 device.
The following example illustrates a configuration of:

Slot 4

IRQ 10

DMA channel 7

Base %x4e20

Shielded Twisted Pair (STP)

Ring speed of 16

Example 92 Using the isacfg at Console Prompt with the DW110

>>> isacfg -slot 4 -etyp 1 -ena 1 -irq0 %xa -dmachan0 7
-iobase0 %x4e20 -handle "DW11,STP,16" -mk
The command ("-mk") makes an isacfg entry for an ISA device at slot 4. It is a
Single port type of device (-etyp 1). The -handle parameter tells the operating
system that this is a DW110 device, that STP media is to be used, and the ring
speed is 16.

9.15 Configuring the Ethernet Media Type from the Console

On Alpha systems prior to OpenVMS Version 7.1, the LAN device driver
autosenses the media connection when needed.
With OpenVMS Version 7.1, the drivers for the Tulip, DE500, DE600, and
DEGXA use the setting of a console environment variable to select the proper
media connection. For each device recognized by the console there is a console
environment variable called Edx0_MODE, where x is the controller letter (e.g. A,

944 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.15 Configuring the Ethernet Media Type from the Console
B, C), and d is the device letter. The console environment variable is set with the
command:
>>>SET Edx0_MODE media_selection
For the DE500 and DE600, the media_selection is one of the following:
Twisted-Pair
Full Duplex, Twisted-Pair
AUI
BNC
Fast
FastFD (Full Duplex)
Auto-Negotiate
For the DEGXA, the media_selection is one of the following:
Auto
10_mbps
10_mbps_full_duplex
100_mbps
100_mbps_full_duplex
1000_mbps
1000_mbps_full_duplex
During the OpenVMS device configuration a message is sent to the operators
console that shows which media was set by the console and handed to the device
driver. For example, if the EWA0_MODE console environment variable was set to
Fast, the following message would be broadcast at the console:
%EWA0, Fast(100baseT) mode set by console
If a console environment variable has been set with an unsupported media type
for the corresponding device, then the driver selects a default media type.
An Alpha system console may assign a controller letter to an adapter differently
from OpenVMS. In this case, the letter designation in the message broadcast to
the console by the driver may not agree with the console setting.

9.16 Frame Formats

Several different LAN physical layer protocols are supported by OpenVMS with
some differences in frame formats. The following sections describe the similarities
and differences in these frame formats. Despite differences, the QIO interface to
the LAN drivers is designed to allow applications to run over the different media
with few changes to the application.
The frame formats available in the LAN media are shown in Figure 93.

Local Area Network (LAN) Device Drivers 945

Local Area Network (LAN) Device Drivers

9.16 Frame Formats
Figure 93 LAN Frame Formats
CSMACD with Ethernet header
Ethernet Header

DATA

CRC

CSMACD with 802.3 header

802.3 Header

802.2/802.1 Header

DATA

CRC

802.2/802.1 Header

DATA

CRC

802.2/802.1 Header

DATA

CRC

FDDI
FDDI Header
Token Ring
Token Ring Header

ATM ELAN with Ethernet Header

LEH

DATA

Ethernet Header

ATM ELAN with 802.3 Header

LEH

802.3 Header

802.2/802.1 Header

DATA

CRC: Cyclic Redundancy Check

LEH: LAN Emulation Header
ZK3901AGE

Note that CSMA/CD provides two frame formats and the FDDI provides one
frame format. The 802.1 header is an optional extension to the 802.2 header.

9.16.1 CSMA/CD Frames

There are two headers for CSMA/CD frames:

Ethernet header

IEEE 802.3 header

Figure 94 illustrates a CSMA/CD frame with an Ethernet header.

946 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.16 Frame Formats
Figure 94 CSMA/CD Frame with Ethernet Header
DA

SA

PTY

DATA

CRC

46=>1500

Minimum total length 64 bytes

Maximum total length 1518 bytes
DA:

Destination Address

SA:

Source Address

PTY:

Ethernet Protocol Type

DATA: Users data (can include 2byte length field)

CRC: Cyclic Redundancy Check
ZK3743AGE

The Ethernet header consists of the DA, SA, and PTY fields. Ethernet frames
must be at least 64 bytes in length, which means that the minimum data length
is 46 bytes. Applications select Ethernet format by specifying NMA$C_LINFM_
ETH (the default) as the value for NMA$C_PCLI_FMT in their P2 characteristics
buffer. If the amount of actual data to be transmitted is less than 46 bytes, the
CSMA/CD drivers transmit extra bytes of zero after the application data.
Figure 95 illustrates a CSMA/CD frame with an IEEE 802.3 header.
Figure 95 CSMA/CD Frame with IEEE 802.3 Header
DA

SA

LEN

DATA

CRC

46=>1500

DA:

Destination Address

SA:

Source Address

LEN:

The length of data portion only. It can

be less than 46 if the user supplied less than
46 bytes of data, but the frame is then
padded to meet minimum length requirements.

DATA: Users data

CRC:

Cyclic Redundancy Check

ZK3745AGE

The IEEE 802.3 format is similar to the Ethernet format, except the PTY field is
replaced by the LEN field.

Local Area Network (LAN) Device Drivers 947

Local Area Network (LAN) Device Drivers

9.16 Frame Formats
9.16.2 FDDI Frames
Figure 96 illustrates the format of FDDI frames.
Figure 96 FDDI Frame Format
FC

DA

SA

DATA

CRC

0=>4478

FC:

Frame Control contains a "priority" field that

can be used to determine if the frame originated
on the FDDI or on the Ethernet.

DA:

Destination Address

SA:

Source Address

DATA: Users data

CRC: Cyclic Redundancy Check
ZK3742AGE

The FDDI header consists of the FC, DA, and SA fields.

9.16.3 Token Ring Frames (Alpha Only)

Figure 97 illustrates the format of Token Ring frames.
Figure 97 Token Ring Frame Format (Alpha Only)
AC FC DA SA
1

[RI]

DATA

030 0=>4476

CRC
4

AC: Access Control contains priority for the frame.

FC: Frame Control contains the type of frame.
DA: Destination Address
SA: Source Address
RI: Optional Routing Information. Only valid with
packets that are source routed.
DATA: Users data
CRC: Cyclic Redundancy Check
ZK6679AGE

9.16.4 ATM ELAN Frames (Alpha Only)

Figure 98 illustrates the format of LAN emulation data frame format for the
IEEE 802.3 and Ethernet Header.

948 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.16 Frame Formats
Figure 98 LAN Emulation Data Frame Format with IEEE 802.3/Ethernet Header
LEH

DA

SA

PTY/LEN

DATA

46=>*

* 1500 For an 802.3 LAN emulation of size 1516

4528 For an 802.3 LAN emulation of size 4544
9218 For an 802.3 LAN emulation of size 9234
LEH: LAN Emulation Header
DA:

Destination Address

SA:

Source Address

PTY/LEN: For frames with the IEEE 802.3 header,

PTY is the Ethenet Protocol Type. For
frames with the Ethernet header, LEN is
the length of the data portion only. It can
be less than 46 if the user supplied less than
46 bytes of data, but the frame is then
padded to meet minimum requirements.
DATA: Users data
ZK8990AGE

9.16.5 802.2/802.1 Headers

The 802.2 header follows the 802.3 header in a CSMA/CD frame and follows the
FDDI header in an FDDI frame.
The 802.2 header is illustrated in Figure 99.
Figure 99 802.2 Header
Size of
Field
(Bytes)
DSAP

SSAP

CTL

12
ZK4799GE

This 802.2 header is followed by the 802.1 header illustrated in Figure 910 if the
DSAP field is the SNAP SAP (AA hex), the SSAP field is the SNAP SAP, and the
CTL field is UI (03 hex).

Local Area Network (LAN) Device Drivers 949

Local Area Network (LAN) Device Drivers

9.16 Frame Formats
Figure 910 802.1 Header
PID
5
PID: Users Protocol Identifier
ZK3904AGE

The PID field consists of two subfields: the company portion of the PID and the
implementation-specific portion of the PID (see Figure 911).
Figure 911 802.1 Header Subfields
COPID

IPID

COPID: Company Protocol Identifier

IPID: Implementation Specific Protocol Identifier
ZK3906AGE

9.16.6 Token Ring Source Routing Header (Alpha Only)

Figure 912 details the field of the source routing header.
Figure 912 Source Routing Field (Alpha Only)
RC S1 S2
2

Sn
2

ZK6680AGE

The routing control (RC) contains the information about how the packet is to be
routed.
The Sn contains the segment identifier for the hop. Each segment identifier
contains a ring number and bridge number used in the hop.

9.17 Format Parameter

Each port (or user) of a LAN controller either specifies a value for the format
characteristic of the port or assumes the default. The format characteristic has
three valid values: Ethernet, 802, and 802E. This section describes the actual
frame formats for each medium for each format parameter value.
For a format parameter value of NMA$C_LIMFM_ETH (the default), the frame
formats are shown in Figure 913. Note that a name given to the FDDI frame
with the Ethernet format is a mapped Ethernet frame.

950 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.17 Format Parameter
Figure 913 Frames with Ethernet Format
For CSMA/CD
DA SA
6

PTY

DATA

CRC

461500

For FDDI
FC

DA

SA

DSAP

SSAP

CTL

COPID

IPID

DATA

CRC

04470

For Token Ring

AC

FC

DA

SA

DSAP

SSAP

CTL

COPID

IPID

DATA

CRC

04418

SA

PTY

DATA

For ATM ELAN

LEH DA
2

461500 (1516 ELAN)

464528 (4544 ELAN)
469218 (9234 ELAN)

LEH: LAN Emulation Header

DSAP: SNAP SAP (hex AA)
SSAP: SNAP SAP
CTL: UI (hex 03)
COPID: Mapped Ethernet (000000)
IPID, PTY: Protocol Type
ZK3905AGE

For a format parameter value of NMA$C_PCLI_802, the frame formats are shown
in Figure 914.

Local Area Network (LAN) Device Drivers 951

Local Area Network (LAN) Device Drivers

9.17 Format Parameter
Figure 914 Frames with 802 Format
For CSMA/CD
DA

SA

LEN

DSAP

SSAP

CTL DATA
12

CRC

For FDDI
FC

DA

SA

DSAP

SSAP

CTL DATA
12

CRC

For Token Ring

AC

FC

DA

SA

DSAP SSAP CTL DATA CRC

1

12

DSAP: Destination Service Access Point

SSAP: Source Service Access Point
CTL:
Control Field
DATA length 43 <= N <= 1497 (1 byte CTL)
42 <= N <= 1496 (2 byte CTL)
DATA length 0 <= Z <= 4475 (1 byte CTL)
0 <= Z <= 4474 (2 byte CTL)
DATA length 0 <= Y <= 4423 (1 byte CTL)
DATA length 0 <= Y <= 4424 (2 byte CTL)
For ATM ELAN
LEH DA
2

SA
6

LEN DSAP SSAP CTL

2

12

DATA
X

DATA length 43 <=X<= 1497 (1 byte CTL 1516 ELAN)

42 <=X<= 1496 (2 byte CTL 1516 ELAN)
43 <=X<= 4525 (1 byte CTL 4544 ELAN)
42 <=X<= 4524 (2 byte CTL 4544 ELAN)
43 <=X<= 9215 (1 byte CTL 9234 ELAN)
42 <=X<= 9214 (2 byte CTL 9234 ELAN)
ZK3902AGE

For a format parameter value of NMA$C_PCLI_802E, the frame formats are

shown in Figure 915.

952 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.17 Format Parameter
Figure 915 Frames with 802E Format
For CSMA/CD
DA SA LEN DSAP SSAP CTL PID
6

DATA CRC

For FDDI
FC DA
1

SA

DSAP SSAP CTL PID DATA CRC

For Token Ring

AC FC DA SA DSAP SSAP CTL PID DATA CRC
1

DSAP: SNAP SAP (hex AA)

SSAP: SNAP SAP
CTL: UI (hex 03)
PID:
Users Protocol Identifier
DATA length 38 <= M <= 1492
DATA length 0 <= Y <= 4470
DATA length 0 <= Z <= 4418
ZK3903AGE

9.18 Features of Packet Formats

The Ethernet controllers can transmit and receive both Ethernet and 802.2/802.3
packets. Each port on a controller is able to transmit and receive either Ethernet
or 802 packets. Ethernet and 802 ports can be assigned on the same controller at
the same time.
The FDDI controllers can transmit and receive FDDI frames. There is a mapped
Ethernet frame format that is comparable to the Ethernet packets sent and
received by the Ethernet controllers.
At the time each port on the controller is started, one of three packet formats can
be specified: Ethernet (default), standard 802 (referred to as 802 packet format),
and extended 802. If no format is specified, the default format is used.
Each port on the controller must be unique on that controller. For each packet
format, there is a parameter that distinguishes the port from all other ports with
the same packet format. For Ethernet packet format ports, the 2-byte protocol
type parameter defines the port. For 802 packet format ports, the 1-byte SAP
defines the port. For extended 802 format ports, the 5-byte protocol identifier
defines the port.
Sections 9.18.1, 9.18.2, and 9.18.3 describe the three packet formats and the
characteristics unique to each format.

Local Area Network (LAN) Device Drivers 953

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
9.18.1 Ethernet Packet Format
The Ethernet format specifies a two-byte protocol type field followed by an
optional length field. The length field is included in transmit packets and
expected in receive packets with the PAD parameter is enabled. The following
sections describe these features.
9.18.1.1 Ethernet Protocol Types
Every Ethernet frame has a 2-byte protocol-type field. This field is used to
determine the port to which a packet belongs. Protocol types are independent
of addresses; unique protocol designations can be assigned by Xerox a particular
station starts an Ethernet port, that user must specify the protocol type to be
used on that port. Messages sent over that port always have the protocol type
attached to them by the device driver, and messages rece that protocol type are
delivered to the starter of that port. Valid protocol types are in the range 05-DD
through FF-FF.
Following are the cross-company protocol types:
Value

Meaning

08-00

IP protocol (ARPAnet)

08-06

Address resolution protocol (ARPAnet)

90-00

Ethernet Loopback protocol

Some commonly used protocol types are as follows:

Value

Meaning

60-01

DNA Dump/load (MOP)

60-02

DNA Remote Console (MOP)

60-03

DNA Routing

60-04

Local Area Transport (LAT)

60-05

Diagnostics

60-06

Customer use

60-07

System Communication Architecture (SCA)

80-38

Bridge

80-3C

DNA Naming Service

80-3D

CSMA/CD Encryption

80-3E

DNA Time Service

80-3F

LAN Traffic Monitor

80-40

NETBIOS Emulator (PCSG)

80-41

Local Area System Transport (LAST)

9.18.1.2 Ethernet Packet Padding

This section describes the PAD parameter NMA$C_PCLI_PAD, which is used only
in the Ethernet packet format.
All CSMA/CD frames must be at least 64 bytes in length. This includes the
Ethernet header, the user data, and the CRC. If the user data, CRC, and Ethernet
header together are less than 64 bytes, zero padding bytes are inserted between

954 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
the user data and the CRC to make a 64-byte packet. This packet padding cannot
be turned off.
The PAD parameter directs the LAN drivers to place a data-size field in the
packet between the standard header and the user data. If padding is on
(NMA$C_STATE_ON is specified), a 2-byte length field is inserted after the
Protocol Type field and before the user data.
If the PAD parameter is off (NMA$C_STATE_OFF is specified), Ethernet packets
have the following characteristics:

Packets transmitted are padded with null bytes as needed (CSMA/CD only).

Packets transmitted do not include the size field.

The length of user data in the packets received is always between 46 and
1500 bytes for CSMA/CD, and 0 to 4470 for FDDI. For example, if a 10-byte
packet is transmitted, it is received as 46 bytes because the driver cannot
determine the amount of user data in the packetonly the amount of user
data plus padded null bytes.

If the PAD parameter is on (NMA$C_STATE_ON is specified), Ethernet packets

have the following characteristics:

Packets transmitted are padded with null bytes as needed (CSMA/CD only).

Packets transmitted include the size field.

The length of user data in the packets received is always between 0 and 1498
bytes for CSMA/CD, and 0 to 4468 bytes for FDDI. The driver uses the size
field to determine the amount of user data in the packet. The size field is not
included in the data returned to the user.

9.18.1.3 Protocol Type Sharing

Protocol types are usually nonshareable; however, an application may benefit
from a shared protocol implementation. The protocol access parameter (NMA$C_
PCLI_ACC) allows a protocol type to be opened in either of two shareable modes:
shared-default (NMA$C_ACC_SHR) and shared-with-destination (NMA$C_ACC_
LIM). The LAN drivers also provide the nonshareable exclusive mode (NMA$C_
ACC_EXC). (See Table 939.) The rules and requirements for using each mode
are as follows:

The exclusive mode is the default if no access mode is supplied as a P2 buffer

parameter. This mode of operation does not allow the protocol to be shared by
other users. Any attempt to start up another protocol of the same type results
in an error status of SS$_BADPARAM.

The shared-with-destination mode is a protocol type/destination address

pairing that allows multiple users to share a protocol type and to
communicate with a different node.
For a given shared protocol type, there can be many shared-with-destination
users; each user communicates with a different destination address. Any
attempt to start a port with a destination address that is in use results in an
error status of SS$_BADPARAM.
When a shared-with-destination user passes the set mode P2 buffer,
the buffer must contain a destination address in the NMA$C_PCLI_DES
parameter. This destination address is used as the destination address in all
messages transmitted, and the user receives messages only from this address.

Local Area Network (LAN) Device Drivers 955

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats

The shared-default mode is the default user of a shared protocol type. There
can be only one such user for each shared protocol type. A shared-default
user does not have to exist if a protocol type is shared, but there can be no
more than one such user per shared protocol type.
The shared-default user receives all messages for the shared protocol type,
but not for any of the shared-with-destination users. The shared-default
user also receives all messages matching both the shared protocol type and
any multicast address enabled by the shared-default user.
The shared-default user can only transmit to multicast addresses and
physical addresses that are not enabled by any of the shared-withdestination users sharing the same protocol type.
If there is no shared-default user of a protocol type, incoming messages from
nodes not among the shared-with-destination users for that protocol type
are ignored.

9.18.2 IEEE 802 Packet Format

The IEEE 802 packet formats accepted for a port depend on the service enabled
on that port. All 802 packet formats have an 802.2 header. The service on the
port determines the valid values for the 802.2 fields.
When a port is started, the NMA$C_PCLI_SRV parameter in the P2 buffer selects
the service on that port. A value of NMA$C_LINSR_CLI specifies Class I service
and a value of NMA$C_LINSR_USR specifies user-supplied service (the default).
9.18.2.1 Class I Service Packet Format
For Class I service, only three packet formats are transmitted and received: UI,
XID, and TEST. Figure 916 shows the 802.2 header format for Class I service.
Figure 916 Class I Service 802.2 Header
Size of
Field
(Bytes)
DSAP

SSAP

1
ZK4798GE

The control field for an 802 packet is always an unnumbered control field. The
unnumbered control field, which is always 1 byte in length, is passed by the P4
argument of the write QIO and can be one of the following binary values:

UI command (00000011)
This is the unnumbered information command. It is the method used to
transmit data from one user to another and is the most widely used control
field value.
The UI command can be specified by using NMA$C_CTLVL_UI.

XID command (101p1111)

956 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
This is the exchange identification command. It is used to convey information
about the port. The p bit is the poll bit and can be either 0 or 1. This
command can be specified by using NMA$C_CTLVL_XID for a 0 poll bit or
NMA$C_CTLVL_XID_P for a 1 poll bit.

XID response (101f1111)

The XID response is a response to an XID command. The f bit is the final
bit and will match the poll bit from the XID command.

TEST command (111p0011)

The TEST command is used to test a connection. The p bit is the poll bit
and can be either 0 or 1. This command can be specified by using NMA$C_
CTLVL_TEST for a 0 poll bit or NMA$C_CTLVL_TEST_P for a 1 poll bit.

TEST response (111f0011)

The TEST response is a response to a TEST command. The f bit is the final
bit and will match the poll bit from the TEST command.

An 802 format port with Class I service is allowed to transmit UI, XID, and TEST
commands. An 802 format port with Class I service is allowed to receive UI
commands and XID and TEST responses.
Refer to the IEEE 802.2 Standard for more information on these control field
values and response messages.
9.18.2.2 User-Supplied Service Header Format
Figure 917 shows the 802.2 header format for user-supplied service.
Figure 917 User-Supplied Service 802.2 Header
Size of
Field
(Bytes)
DSAP

SSAP

CTL

12
ZK4799GE

The user provides the control field values, which are documented in the IEEE
802.2 Standard. The user-supplied packet format is the generic packet format
as specified in the IEEE 802.2 Standard. Class I packets (see Section 9.18.2.1)
are a subset of this generic packet format; therefore, if the control field value of
the user-supplied packet is UI, XID, or TEST, the packet is the same as a Class
I packet. Note that Class II packets, as defined in the IEEE 802.2 Standard,
include the UI, XID, and TEST command/response formats.

Local Area Network (LAN) Device Drivers 957

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
9.18.2.3 Service Access Point (SAP) Use and Restrictions
The IEEE 802.2 Standard places restrictions on both user SAPs and source SAPs
(SSAPs). All SAPs are 8 bits long. Figure 918 shows the format of destination
SAPs (DSAPs) and SSAPs.
Figure 918 DSAP and SSAP Format
7
DSAP

0
DDDDDDDI/G

7
SSAP

0
SSSSSSSC/R
ZK4800GE

Definition of the least significant bit depends on whether the SAP is a source
SAP (SSAP) or a destination SAP (DSAP). For a DSAP field, the least significant
bit distinguishes group SAPs (bit 0 = 1) from individual SAPs (bit 0 = 0). For
an SSAP field, the least significant bit distinguishes commands (bit 0 = 0)
from responses (bit 0 = 1). Because these two bits are located at the same bit
position within the SAP field, a group SAP cannot be used as an SSAP. If this
were allowed, a group SAP would be interpreted as an individual SAP with
the command/response bit set to 1, thus implying a response. The IEEE 802.2
Standard reserves for its own definition all SAP addresses with the second least
significant bit set to 1. You should use these SAP values for their intended
purposes, as defined in the IEEE 802.2 Standard.
Up to four group SAPs can be enabled on each 802 port. The group SAPs enabled
on a controller do not have to be unique for each port; for example, two 802 format
ports can have the same group SAP enabled. This allows a single packet coming
into the controller to be duplicated and passed to each port on the controller that
has the group SAP enabledassuming the packet has a DSAP value that is a
group SAP. If the received packet has an individual SAP for a DSAP, the packet
goes to, at most, one port.

9.18.3 IEEE 802 Extended Packet Format

The 802E format uses the 802.2 and 802.1 headers, as shown in Figure 919.

958 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
Figure 919 802 Extended Header
Size of
Field
(Bytes)
DSAP

SSAP

CTL

PID

5
ZK5791GE

For an 802E packet format, the DSAP and SSAP fields are always set to the
SNAP SAP (AA hex). The SNAP SAP value is a special SAP value reserved for
802 extended format packets. The SNAP SAP value distinguishes an 802 packet
from an 802 extended packet. The only valid control field value for 802 extended
packets is UI (unnumbered information).
9.18.3.1 Protocol Type PID Sharing (Alpha Only)
On Alpha systems, the 802E format allows users protocol identifier (PID) sharing.
PIDs are usually nonshareable; however, an application may benefit from a
shared protocol implementation. The protocol access parameter (NMA$C_PCLI_
ACC) allows a PID to be opened in either of two shareable modes: shared-default
(NMA$C_ACC_SHR) and shared-with-destination (NMA$C_ACC_LIM). The LAN
drivers also provide the nonshareable exclusive mode (NMA$C_ACC_EXC). (See
Table 939.) The rules and requirements for using each mode are as follows:

The exclusive mode is the default if no access mode is supplied as a P2 buffer

parameter. This mode of operation does not allow the protocol to be shared by
other users. Any attempt to start up another protocol of the same type results
in an error status of SS$_BADPARAM.

The shared-with-destination mode is a PID/destination address pairing that

allows multiple users to share a PID and to communicate with a different
node.
For a given shared protocol type, there can be many shared-with-destination
users; each user communicates with a different destination address. Any
attempt to start a port with a destination address that is in use results in an
error status of SS$_BADPARAM.
When a shared-with-destination user passes the set mode P2 buffer,
the buffer must contain a destination address in the NMA$C_PCLI_DES
parameter. This destination address is used as the destination address in all
messages transmitted, and the user receives messages only from this address.

The shared-default mode is the default user of a shared PID. There can be
only one such user for each shared PID. A shared-default user does not have
to exist if a PID is shared, but there can be no more than one such user per
shared PID.

Local Area Network (LAN) Device Drivers 959

Local Area Network (LAN) Device Drivers

9.18 Features of Packet Formats
The shared-default user receives all messages for the shared PID, but not
for any of the shared-with-destination users. The shared-default user
also receives all messages matching both the shared PID and any multicast
address enabled by the shared-default user.
The shared-default user can only transmit to multicast addresses and
physical addresses that are not enabled by any of the shared-withdestination users sharing the same PID.
If there is no shared-default user of a PID, incoming messages from nodes
not among the shared-with-destination users for that PID are ignored.

9.19 LAN Device Information

You can obtain information on controller characteristics by using the
Get Device/Volume Information ($GETDVI) system service. (Refer to the
OpenVMS System Services Reference Manual.)
$GETDVI returns controller characteristics when you specify the item code
DVI$_DEVCHAR. Table 931 lists these characteristics, which are defined by the
$DEVDEF macro and in the file SYS$LIBRARY:DEVDEF.H.
Table 931 Ethernet Controller Device Characteristics
Characteristic

Meaning
Static Bits (Always Set)

DEV$M_AVL

Device is available.

DEV$M_IDV

Input device.

DEV$M_NET

Network device.

DEV$M_ODV

Output device.

DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and device

class names, which are defined by the $DCDEF macro and in the file
SYS$LIBRARY:DCDEF.H. The device class name for the LAN Ethernet
controllers listed in Section 9.2.1 and Section 9.2.2 is always DC$_SCOM.
DVI$_DEVBUFSIZ returns the maximum message size. The maximum send
or receive message size depends on the packet format and whether padding
(NMA$C_PCLI_PAD) is enabled (see Sections 9.20.1 and 9.20.2). DVI$_
DEVDEPEND returns the unit and line status bits and the error summary
bits in a longword field as shown in Figure 920.
Figure 920 DVI$_DEVDEPEND Returns
24 23

31
Not Used

16 15
Error
Summary

8 7
Unit and Line
Status

0
Not Used

ZK5932GE

960 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.19 LAN Device Information
Table 932 lists the status values and their meanings. These values are defined
by the $XMDEF macro. XM$M_STS_ACTIVE is set when the port is started.
XM$M_STS_BUFFAIL and XM$M_STS_TIMO are dynamically set and cleared
by the LAN driver.
Table 932 Ethernet Controller Unit and Line Status
Status

Meaning

XM$M_STS_ACTIVE

Port is active.

XM$M_STS_BUFFAIL

Attempt to allocate a system receive buffer failed.

XM$M_STS_TIMO

Timeout occurred.

The error summary bits are set when an error occurs. They are read-only bits.
If an error is fatal, the Ethernet port is shut down. Table 933 lists the error
summary bit values and their meanings.
Table 933 Error Summary Bits
Error Summary Bit

Meaning

XM$M_ERR_FATAL

Hardware or software error occurred on the controller.

9.20 LAN Function Codes

The LAN drivers can perform logical, virtual, and physical I/O operations. The
basic functions are read, write, set mode, set characteristics, sense mode, and
sense characteristics. Table 934 lists these functions and their codes. The
following sections describe these functions in greater detail.
Table 934 LAN I/O Functions
Arguments

Type1

Function
Modifiers

Function

P1,P2,[P5]

IO$M_NOW

Read logical block.

IO$_READVBLK

P1,P2,[P5]

IO$M_NOW

Read virtual block.

IO$_READPBLK3

P1,P2,[P5]

IO$M_NOW

Read physical block.

P1,P2,[P4],P5

IO$M_RESPONSE

Write logical block.

P1,P2,[P4],P5

IO$M_RESPONSE

Write virtual block.

P1,P2,[P4],P5

IO$M_RESPONSE

Write physical block.

Function Code
IO$_READLBLK

IO$_WRITELBLK

IO$_WRITEVBLK
IO$_WRITEPBLK
1V

= virtual, L = logical, P = physical (There is no functional difference in these operations.)

3 On

OpenVMS Alpha, P1, and P5 support 64-bit addresses.

4 On

OpenVMS Alpha, P1, P4, and P5 support 64-bit addresses.

(continued on next page)

Local Area Network (LAN) Device Drivers 961

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 934 (Cont.) LAN I/O Functions
Function Code

Arguments

Type1

Function
Modifiers

Function

IO$_SETMODE

P1,[P2],P3

IO$M_CTRL
IO$M_STARTUP
IO$M_SHUTDOWN
IO$M_ATTNAST
IO$M_SET_MAC
IO$M_UPDATE_MAP
IO$M_ROUTE

Set controller
characteristics and
controller state for
subsequent operations.

IO$_SETCHAR

P1,[P2],P32

IO$M_CTRL
IO$M_STARTUP
IO$M_SHUTDOWN
IO$M_ATTNAST
IO$M_SET_MAC
IO$M_UPDATE_MAP
IO$M_ROUTE

Set controller
characteristics and
controller state for
subsequent operations.

IO$_SENSEMODE

[P1],[P2]

IO$M_CTRL
IO$M_SENSE_MAC
IO$M_SHOW_MAP
IO$M_SHOW_ROUTE

Sense controller
characteristics and return
them in specified buffers.

IO$_SENSECHAR

[P1],[P2]

IO$M_CTRL
IO$M_SENSE_MAC
IO$M_SHOW_MAP
IO$M_SHOW_ROUTE

Sense controller
characteristics and return
them in specified buffers.

1V

= virtual, L = logical, P = physical (There is no functional difference in these operations.)

2 The

P1 and P3 arguments are only for attention AST QIOs.

Although the LAN device drivers do not differentiate among logical, virtual, and
physical I/O functions (all are treated identically), you must have the required
privilege to issue the request. (Logical I/O functions do not require I/O privilege.)

9.20.1 Read
Read functions directly transfer data from a packet received from another port
on the Ethernet into the virtual memory address space of the user process. The
operating system provides the following function codes:

IO$_READLBLKRead logical block

IO$_READVBLKRead virtual block

IO$_READPBLKRead physical block

Received messages are buffered in system memory and then copied to the users
buffer when a read operation is performed.
The read functions take the following device- or function-dependent arguments:

P1The starting virtual address of the buffer that is to receive data. On

OpenVMS Alpha systems, P1 can be a 64-bit address.

P2The size of the receive buffer in bytes.

P5The address of a buffer where the LAN driver returns packet header
information. This is an optional argument. The information returned
depends on the packet format enabled with the set mode QIO. The size of the
buffer must be 14 bytes for an Ethernet format packet, 16 bytes for an IEEE

962 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
802 format packet, and 20 bytes for an 802 extended format packet. Note
that the information returned is not the entire packet header but the header
information less any length or size fields. The IOSB, if specified, is where the
packet length information is returned. For FDDI, if received access control
(RAC) is on, then 1 byte must be added to these sizes.
On Alpha systems, Token Ring requires that this buffer be at least 54 bytes
long due to a possible variable length source routing header.
If NMA$C_PCLI_PRM (see Table 939) is enabled, the P5 buffer must be at
least 20 bytes for CSMA/CD and 21 bytes for FDDI. Figure 921 shows the
format of the three buffers. On OpenVMS Alpha systems, P5 can be a 64-bit
address.

Local Area Network (LAN) Device Drivers 963

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Figure 921 Read Function P5 Buffer
Ethernet Format:
0
2

6Byte Destination
Address (Physical or
Multicast)

4
6
8

6Byte Source Address

(Physical)

10
12

2Byte Protocol Type

IEEE 802 Format:
0
2

6Byte Destination
Address (Physical or
Multicast)

4
6
8

6Byte Source Address

(Physical)

10
12

SSAP

DSAP
14
1 or 2Byte CTL Field

802 Extended Format:

0
2

6Byte Destination
Address (Physical or
Multicast)

4
6
8

6Byte Source Address

(Physical)

10
12

SSAP

DSAP
14
1Byte CTL Field
16
5Byte Protocol Identifier

18

ZK1126GE

The P1 and P2 arguments must always be specified; the P5 argument is optional.

However, if P5 is not specified, you will be unable to determine the source of the
received message.

964 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
If the size of the user data in a receive message is larger than the value of the
NMA$C_PCLI_BUS parameter, the message is not given to the user, even if there
is sufficient space in the users receive buffer.
If the size of the user data in a receive message is larger than the size specified in
P2 (and less than or equal to the value of the NMA$C_PCLI_BUS parameter), the
P1 buffer is filled and SS$_DATAOVERUN is returned in the I/O status block.
Table 935 lists the maximum user data sizes that can be received for CSMA/CD,
FDDI, and Token Ring protocols.
Table 935 Maximum User Data Sizes for CSMA/CD, FDDI, and Token Ring
Packet Format

CSMA/CD

FDDI

Token Ring

Ethernet format without padding

1500

4470

4418

Ethernet format with padding

1498

4468

4416

802 format with 1-byte CTL field

1497

4475

4423

802 format with 2-byte CTL field

1496

4474

4422

802E format

1492

4470

4418

Alpha specific.

On Alpha systems, Table 936 lists the maximum user data sizes that can be
received for LAN emulation over ATM protocol.
Table 936 Maximum User Data Sizes for LAN Emulation over ATM (Alpha Only)
Packet Format

ATM ELAN size:

1516

4544

9234

Ethernet format without padding

1500

4528

9218

Ethernet format with padding

1498

4526

9216

802 format with 1-byte CTL field

1497

4525

9215

802 format with 2-byte CTL field

1496

4524

9214

802E format

1492

4520

9210

For 802 format packets, the P5 buffer always contains the DSAP and SSAP in the
bytes at offset 12 and 13. The next one or two bytes (offsets 14 and 15) following
the SSAP contain the control field value. For Class I service, the control field
value is always 1 byte in length and will always be placed in the byte at offset 14
of this buffer. For user-supplied service, you have to determine the length of the
control field value according to the IEEE 802.2 Standard.
On Alpha systems with Token Ring, if received access control (RAC) is on, the
first byte of the P5 buffer contains the frame control (FC) field.
For FDDI, if RAC is on, the first byte of the P5 buffer contains the FC field.
The read functions can take the following function modifier:
IO$M_NOWComplete the read operation immediately with a received
message (if no message is currently available, return a status of SS$_
ENDOFFILE in the I/O status block).

Local Area Network (LAN) Device Drivers 965

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
9.20.2 Write
Write functions provide for the direct transfer of data from the virtual memory
address space of the user process to the communications medium. The operating
system provides the following function codes:

IO$_WRITELBLKWrite logical block

IO$_WRITEVBLKWrite virtual block

IO$_WRITEPBLKWrite physical block

Transmitted messages are copied from the buffer of the requesting process to a
system buffer for transmission.
The write function takes the following device- or function-dependent arguments:

P1The starting virtual address of the buffer containing the data to be

transmitted. On OpenVMS Alpha systems, P1 can be a 64-bit address.

P2The size of the buffer in bytes.

P4The address of a quadword that points to a buffer that contains the

DSAP and CTL field values (optional). (See Section 9.18.2.3.) The first
longword is the buffer length; the second longword is the address of the
buffer. This argument is used only for ports with the 802 packet format. The
format of the buffer is:

23

8
CTL

0
DSAP
ZK4801GE

On OpenVMS Alpha systems, P4 can be a 64-bit address.

P5The address of a 6-byte buffer that contains the destination address

(either physical or multicast). For FDDI, if XFC is specified as zero on
startup, the first byte of the P5 buffer contains the low-order 3 bits of the
FC field to be transmitted. On OpenVMS Alpha systems, P5 can be a 64-bit
address.
If the device is in promiscuous mode (NMA$C_PCLI_PRM; see Table 939),
you must pass a larger buffer with additional information positioned after
the destination address. For Ethernet packet format, the buffer must be 8
bytes with the 2-byte protocol type following the destination address. For
802 packet format, the buffer must be 7 bytes with the 1-byte source SAP
following the destination address. For 802 extended packet format, the buffer
must be 11 bytes with the 5-byte protocol identifier following the destination
address. The individual Source SAP cannot be a group SAP or the SNAP
SAP. Figure 922 shows the format of the P5 buffer. For FDDI with XFC
specified as zero on startup, 1 byte must be added to these sizes for the FC
field.

966 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Figure 922 Write Function P5 Buffer
0
2

6Byte Destination
Address (Physical or
Multicast)

4
6

2Byte Protocol Type, 1Byte Source SAP,

or 5Byte Protocol Identifier *
*Only if the channel is in promiscuous mode.
ZK1211GE

Table 937 lists the maximum user data sizes that can be specified by P2 and
received for CSMA/CD, FDDI, and Token Ring protocols.
Table 937 Maximum Message Sizes for CSMA/CD, FDDI, and Token Ring
Packet Format

CSMA/CD

FDDI

Token Ring

Ethernet format without padding

1500

4470

4418

Ethernet format with padding

1498

4468

4416

802 format with 1-byte CTL field

1497

4475

4423

802 format with 2-byte CTL field

1496

4474

4422

802E format

1492

4470

4418

Alpha specific.

On Alpha systems, Table 938 lists the maximum user data sizes that can be
specified by P2 and received for LAN emulation over ATM protocol.
Table 938 Maximum Message Sizes for LAN Emulation over ATM (Alpha Only)
Packet Format

ATM ELAN size:

1516

4544

9234

Ethernet format without padding

1500

4528

9218

Ethernet format with padding

1498

4526

9216

802 format with 1-byte CTL field

1497

4525

9215

802 format with 2-byte CTL field

1496

4524

9214

802E format

1492

4520

9210

If P2 specifies a message size larger than that allowed, the driver returns the
status SS$_IVBUFLEN in the I/O status block.
If the P4 buffer is specified, it must be at least 3 bytes long. The first byte is
always the DSAP; the next two bytes are used to determine the CTL field value.
The DSAP value cannot be the SNAP SAP.

Local Area Network (LAN) Device Drivers 967

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
The CTL field value is either a 1-byte or 2-byte value. If the two least significant
bits of the low-order byte of the CTL field contain the bit values 11, just the
low-order byte of the CTL field is used as the CTL field value. Otherwise, both
bytes of the CTL field are used as the CTL field value.
If the driver uses only the low-order byte of the CTL field, you still must pass at
least a 3-byte buffer. In this case, the driver uses the low-order byte of the CTL
field and ignores the high-order byte.
If Class I service is enabled, only 1-byte CTL field values can be passed. If usersupplied service is enabled, then both 1- and 2-byte CTL field values are valid. If
Class I service is enabled, the CTL field value must be one of the three command
values: UI, XID, or TEST.
Regarding 802 ports, you can receive packets for the SAP enabled with the
IO$_SETMODE or IO$_SETCHAR QIOs and can transmit packets destined for
a different SAP. This is similar to an Ethernet port receiving packets for one
protocol type and transmitting packets with a different protocol type (which is
not possible with the current Ethernet $QIO interface). It is expected that most
802 format applications will want to process only receive packets from a source
SAP that matches the SAP enabled on their port. To do this, the read function
(see Section 9.20.1) has been enhanced to return the source SAP to you. To verify
that the source SAP of an incoming packet matches the SAP enabled on the port,
you need only match the source SAP returned by the read function with the SAP
enabled on the port.
The write functions can take the following function modifier:
IO$M_RESPONSETransmit a response packet (sets the low-order bit in
the SSAP field). This allows users with user-supplied service enabled to
respond to certain 802 format command packets. IO$M_RESPONSE can be
specified only when you have the 802 packet format enabled. The 802 packet
format ports, with Class I service enabled, result in an error if you attempt
to transmit a response message with a CTL field value of unnumbered
information (UI).

9.20.3 Set Mode and Set Characteristics

The operating system provides the following two function codes:
IO$_SETMODE
IO$_SETCHAR
Other than the privilege check, these two function codes are treated the same by
the LAN drivers. This section refers to the IO$_SETMODE function code only,
even though applications can use either function code.
The set mode function code is used to perform many different functions. These
different functions are distinguished by the modifiers set with the function code.
The LAN drivers support the following set mode requests:

IO$_SETMODE!IO$M_CTRLSet or modify port attributes

IO$_SETMODE!IO$M_CTRL!IO$M_STARTUPSet port attributes and start

port

IO$_SETMODE!IO$M_SET_MACSet medium attributes

IO$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWNShutdown port

IO$_SETMODE!IO$M_ATTNASTEnable attention AST

968 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
On Alpha systems, the LAN drivers also support the following set mode requests
for Token Ring:

IO$M_SETMODE!IO$M_UPDATE_MAPUpdate functional address

mapping table

IO$M_SETMODE!IO$M_ROUTE Update source routing cache table

The following sections describe these functions in detail.

9.20.3.1 Set Controller Mode
Once a port is created using the $ASSIGN system service, you can set the port
attributes and start the port using the requests listed in the previous section.
Note that in most cases only IO$_SETMODE!IO$M_CTRL!IO$M_STARTUP is
issued because it sets the port attributes and starts the port with one request.
IO$_SETMODE!IO$M_CTRL is most often used to modify port attributes after
the port has been started.
If the function modifier IO$M_STARTUP is specified, the LAN port is started. If
IO$M_STARTUP is not specified, the specified characteristics are modified.
This function takes the following device- or function-dependent argument:
P2The address of a quadword descriptor for an extended characteristics
buffer. The first longword of the descriptor is the buffer length; the second
longword is the address of the buffer. The P2 argument is optional.
The P2 buffer consists of a series of 6-byte or counted string entries. The
first word of each entry contains the parameter identifier (ID) of an attribute,
followed by either a longword that contains one of the (binary) values that can
be associated with the parameter ID or a counted string. Counted strings consist
of a word that contains the size of the character string followed by the character
string. Figure 923 shows the format for this buffer.
Figure 923 P2 Extended Characteristics Buffer

Parameter ID
Longword Value or Counted String
Parameter ID
Longword Value or Counted String

etc.
ZK1177GE

Table 939 is an alphabetic listing of the parameter IDs and values that
can be specified in the P2 buffer. These parameter IDs are applicable to
all LAN controllers, except where otherwise noted. The $NMADEF macro
defines these values. The $NMADEF macro is included in the macro library
SYS$LIBRARY:LIB.MLB. (Table 940 lists the parameters that can be used with
Local Area Network (LAN) Device Drivers 969

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
each of the packet formats, and indicates which are required, which are optional,
and which generate the SS$_BADPARAM error.)
If the status SS$_BADPARAM is returned in the first word of the I/O status
block, the second longword contains the parameter ID of the parameter in error.

Table 939 P2 Attributes

Parameter ID

Meaning

NMA$C_PCLI_ACC

Protocol access mode. This optional parameter determines the access mode for
the protocol type. NMA$C_PCLI_ACC is valid only for ports using Ethernet
packet format.
NMA$C_PCLI_ACC is valid for ports using 802E packet format.
One of the following values can be specified:
NMA$C_ACC_EXC Exclusive mode (default)
NMA$C_ACC_SHR Shared-default user mode
NMA$C_ACC_LIM Shared-with-destination mode
Section 9.18.1.3 provides a description of protocol type sharing.
Section 9.18.3.1 provides a description of protocol type PID sharing.
NMA$C_PCLI_ACC is passed as a longword value.

NMA$C_PCLI_BFN

Number of receive buffers to preallocate (default = 1). NMA$C_PCLI_BFN

can have a maximum value of 255. This optional parameter is specified on a
per-port basis.
NMA$C_PCLI_BFN is passed as a longword value.
NMA$C_PCLI_BFN represents the number of receive messages the LAN driver
will hold for a port when the port has no read QIOs posted to the driver.

NMA$C_PCLI_BUS

Maximum allowable port receive data size, that is, message length (default =
512 bytes). NMA$C_PCLI_BUS can have a maximum value of 9234.
This optional parameter is specified on a per-port basis. It is passed as a
longword value.
Any message received for this port that is larger than this parameter value is
discarded.

NMA$C_PCLI_CCA

Can change address. This optional parameter enables applications to start

before DECnet starts. DECnet may attempt to set the physical address of the
controller when it starts. CSMA/CD devices support only one physical address,
and so all applications that are using the same device must also use the same
physical address. If applications that do not use the DECnet address start
before DECnet, DECnet is not able to start on that controller unless the other
applications that have already started have all specified NMA$C_PCLI_CCA to
be ON.
This parameter is not applicable to FDDI because FDDI devices can run with
more than one physical address; however, no error is returned if this parameter
is supplied for FDDI devices.
The application receives no indication whatsoever that the physical address has
changed.
This parameter is passed as a longword. One of the following values can be
specified:
NMA$C_STATE_ON The physical address can be changed.
NMA$C_STATE_OFF The physical address cannot be changed (default).

(continued on next page)

970 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID
NMA$C_PCLI_CON

Meaning
1

Controller mode. This optional parameter determines whether transmit packets

are to be looped back at the controller. One of the following values can be
specified:
NMA$C_LINCN_NOR Normal mode (default)
NMA$C_LINCN_LOO Loopback mode
The only messages looped back are those acceptable to the controller as receive
messages, that is, those messages that possess at least one of the following
characteristics:

Matching physical address (see Section 9.13)

Matching multicast address (see Section 9.13)

Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state

Destination address is a multicast address and all multicasts are enabled

(NMA$C_PCLI_MLT is in the ON state)

NMA$C_PCLI_CON affects all ports on a single controller. It is passed as a

longword value.
For the DELUA, DEBNA, DEBNI, DEQTA, PMAD, DEMNA, and DESVA, the
following list shows the maximum amount of user data that can be looped:
Ethernet format without padding 18 bytes
Ethernet format with padding 16 bytes
802 format with 1-byte CTL field 15 bytes
802 format with 2-byte CTL field 14 bytes
802 extended format10 bytes
When the DEUNA is in loopback mode, the driver always enables echo mode
(NMA$C_PCLI_EKO is in the ON state).
Not all devices support loopback mode. If normal mode is not specified, the
request is completed with SS$_BADPARAM status.
NMA$C_PCLI_CRC1

Cyclic redundancy check (CRC) generation state for transmitted messages

(optional). One of the following values can be specified:
NMA$C_STATE_ON Controller generates a CRC (default).
NMA$C_STATE_OFF Controller does not generate a CRC.
NMA$C_PCLI_CRC affects all ports on a single controller. There is no effect on
checking a receive messages CRC (it is always checked). NMA$C_PCLI_CRC is
passed as a longword value.
If NMA$C_PCLI_CRC is turned off, all users of the controller must supply the
4-byte CRC value for all messages transmitted. The CRC is passed at the end
of the P1 transmit buffer; the additional 4 bytes are included in the size of the
P1 buffer. The CRC value is not checked for correctness.
For the DEQNA, DELQA, and Token Ring devices, the NMA$C_PCLI_CRC
parameter cannot be turned off.
Not all devices support user-supplied CRC. If a controller-generated CRC is
specified, the request is completed with SS$_BADPARAM status.

1 If the LAN controller is active and you do not specify this parameter, the parameter defaults to the current setting. If
the LAN controller is not active, this parameter defaults to the default value indicated.

(continued on next page)

Local Area Network (LAN) Device Drivers 971

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_DES

Shared protocol destination address. Passed as a counted string that consists

of a modifier word (NMA$C_LINMC_SET or NMA$C_LINMC_CLR) followed
by a 6-byte (48-bit) physical destination address. The size of the counted string
must always be 8. NMA$C_PCLI_DES only has meaning when protocol access
(NMA$C_PCLI_ACC) is defined as shared-with-destination mode (NMA$C_
ACC_LIM). The destination address specified must be a physical addressnot
a multicast addressand it must be unique among all ports sharing the same
protocol. NMA$C_PCLI_DES is required when the access mode is defined as
shared-with-destination.
NMA$C_PCLI_DES should not be specified on a port where the 802 or 802E
packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802 or
NMA$C_LINFM_802E). For 802 packet format, the concept of shared protocol
type is handled by using group SAPs.
NMA$C_PCLI_DES should not be specified on a port where the 802 packet
format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). For 802
packet format, the concept of shared protocol type is handled by using group
SAPs.
Section 9.18.1.3 provides a description of protocol type sharing.
Section 9.18.3.1 provides a description of protocol type PID sharing.

NMA$C_PCLI_EKO

Echo mode. Applicable only to the DEUNA device driver.

If echo mode is on, transmitted messages are returned to the sender. This
optional parameter controls the condition of the half-duplex bit in the DEUNA
mode register. One of the following values can be specified:
NMA$C_STATE_ON Echoes transmit messages
NMA$C_STATE_OFF Does not echo transmit messages (default)
If NMA$C_STATE_ON is specified, the only transmitted messages echoed are
those acceptable to the DEUNA as receive messages, that is, those messages
that have at least one of the following characteristics:

Matching physical address (see Section 9.13)

Matching multicast address (see Section 9.13)

Promiscuous mode (NMA$C_PCLI_PRM) is in the ON state

Destination address is a multicast address and all multicasts are enabled

(NMA$C_PCLI_MLT is in the ON state)

If the DEUNA is placed in loopback mode (NMA$C_LINCN_LOO is specified in

the NMA$C_PCLI_CON parameter), the driver enables echo mode.
NMA$C_PCLI_EKO affects all ports on a single controller. It is passed as a
longword value.
1 If the LAN controller is active and you do not specify this parameter, the parameter defaults to the current setting. If
the LAN controller is not active, this parameter defaults to the default value indicated.

(continued on next page)

972 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_FMT

Packet format. This optional parameter specifies the packet format as either
Ethernet, IEEE 802, or 802 extended. This characteristic is passed as a
longword value and affects single ports on a single controller. One of the
following values can be specified:
NMA$C_LINFM_ETH Ethernet packet format (default)
NMA$C_LINFM_802 802 packet format
NMA$C_LINFM_802E 802 extended packet format
NMA$C_PCLI_PTY, NMA$C_PCLI_ACC, and NMA$C_PCLI_DES should only
be specified on those ports where the Ethernet packet format (NMA$C_LINFM_
ETH) is selected.
NMA$C_PCLI_SRV, NMA$C_PCLI_SAP, and NMA$C_PCLI_GSP should only
be specified on those ports where the 802 packet format (NMA$C_LINFM_802)
is selected.
NMA$C_PCLI_PID should only be specified on those ports where the 802
extended packet format (NMA$C_LINFM_802E) is selected.

NMA$C_PCLI_GSP

Group SAP. This is an optional parameter if the 802 packet format is selected
(NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). If the Ethernet or 802
extended packet format is selected, NMA$C_PCLI_GSP cannot be specified.
Group SAPs can be shared among multiple ports on the same controller. If the
802 packet format is selected, NMA$C_PCLI_GSP defines up to four 802 group
SAPs that are to be enabled for matching incoming packets to complete read
operations on this port. By default, no group SAPs are enabled.
NMA$C_PCLI_GSP is passed as a longword value and is read as four 8-bit
unsigned integers. Each integer must be either a group SAP or zero. To enable
a single group SAP on a port, you need only specify the group SAP value to
be enabled in one of the four integers and place a value of zero in the three
remaining integers. To disable group SAPs on the port, you need only place a
value of zero in all four integers and issue the QIO.
If this characteristic is correctly specified, any group SAPs that were previously
enabled on the port are now replaced by the SAPs specified by the current
request.

NMA$C_PCLI_ILP1

Internal loopback mode. This optional parameter places the device in internal
loopback mode (not for the DEUNA, DEQNA, or DELQA devices). One of the
following values can be specified:
NMA$C_STATE_ON Internal loopback mode
NMA$C_STATE_OFF Not in internal loopback mode (default)
If NMA$C_STATE_ON is specified, the NMA$C_PCLI_CON parameter must be
in loopback (NMA$C_LINCN_LOO) mode.
When the controller is in loopback mode (generally for testing), it can loop
packets in external loopback or internal loopback. This parameter places the
controller in one of these loopback modes. NMA$C_PCLI_ILP is passed as a
longword value and affects all ports on the controller.
Not all devices support loopback mode. If NMA$C_STATE_OFF is not specified,
the request is completed with SS$_BADPARAM status.

1 If the LAN controller is active and you do not specify this parameter, the parameter defaults to the current setting. If
the LAN controller is not active, this parameter defaults to the default value indicated.

(continued on next page)

Local Area Network (LAN) Device Drivers 973

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_MCA

Multicast address (optional). Passed as a counted string that consists of a

modifier word followed by a list of 6-byte (48-bit) multicast addresses. The value
specified in the modifier word determines whether the addresses are set or
cleared. If NMA$C_LINMC_CAL is specified, all multicast addresses in the list
are ignored.
The following mode values can be specified in the low byte of the modifier word:
NMA$C_LINMC_SET Set the multicast addresses.
NMA$C_LINMC_CLR Clear the multicast addresses.
NMA$C_LINMC_CAL Clear all multicast addresses.
The driver filters all multicast addresses on a per-port basis; therefore, only
messages received with the ports physical address or the multicast addresses
enabled on the port are used to complete the users read operations.
Note that each LAN controller supports a limited number of multicast
addresses. If this limit is exceeded, the LAN driver enables the accept all
multicast feature on the controller and all multicast packets on the LAN must
be filtered by the LAN driver. This may cause a minor performance loss.
NMA$C_PCLI_MCA is specified on a per-port basis.

NMA$C_PCLI_MLT

Multicast address state. This optional parameter instructs the controller

hardware whether to accept all multicast addresses for this port. One of the
following values can be specified:
NMA$C_STATE_ON Accept all multicast addresses.
NMA$C_STATE_OFF Do not accept all multicast addresses (default).
NMA$C_PCLI_MLT can be enabled on more than one port. It only affects those
ports on which it is enabled.
NMA$C_PCLI_MLT allows you to receive all multicast address packets that
also match the ports protocol type, SAP, or protocol identifier.
Generally, you enable only your individual set of multicast addresses using the
NMA$C_PCLI_MCA parameter, and leave the NMA$C_PCLI_MLT parameter
in the off state.
There could be a minor performance loss when the NMA$C_PCLI_MLT
parameter is in the ON state because the LAN driver may have to process
all multicast addresses on the medium; the number of multicast addresses on
the line determines the amount of processing required.
The NMA$C_PCLI_MLT parameter is passed as a longword value.

NMA$C_PCLI_PAD

Use message size field on transmit and receive messages (optional). One of the
following values can be specified:
NMA$C_STATE_ON Insert message size field (default)
NMA$C_STATE_OFF No size field
(continued on next page)

974 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning
NMA$C_PCLI_PAD affects only the protocol type that issued the set mode
request. It is passed as a longword value.
On CSMA/CD, if padding is enabled on Ethernet format packets, the driver
adds a 2-byte count field to the transmitted data. This field allows short
packets (packets fewer than 46 bytes long) to be received with the proper
length returned by the driver. The minimum Ethernet packet contains 46 bytes
of user data. When fewer than 46 bytes are sent, the packet is padded and
the receiver always receives 46 bytes of data. When padding is enabled, the
maximum message size for transmit or receive operations is 1498 bytes and
the minimum is zero bytes. See Section 9.18.1.2 for additional information.
NMA$C_PCLI_PAD should be specified only on a port where the Ethernet
packet format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_ETH).
For FDDI, the same 2-byte count field is added; however, because FDDI packets
can be as short as 22 bytes, FDDI transmit requests are never padded.

NMA$C_PCLI_PHA1

Physical address (optional). It is passed as a counted string that consists of a

modifier word followed by the 48-bit physical address. If the request is to clear
the physical address or to set the physical address to the default address, the
physical address (if present) is not read.
One of the following mode values can be specified in the low byte of the modifier
word:
NMA$C_LINMC_SET Set the string value.
NMA$C_LINMC_CLR Clear the physical address.
NMA$C_LINMC_SDF Set the physical address to the default address.
For CSMA/CD, the default address is constructed by appending the loworder word of the system parameter SCSSYSTEMID to the constant
DECnet header (AA-00-04-00). If SCSSYSTEMID is zero, and NMA$C_
LINMC_SDF is specified, the hardware address is used as the default.
For FDDI, the default address is the hardware address.
If not specified for CSMA/CD, the default is the current address set by a
previous set mode function on this controller, or the hardware address if no
address was defined by a previous set mode function. If not specified for FDDI,
the default is the hardware address.
The physical address must be passed as a 6-byte (48-bit) quantity. The first
byte is the least significant byte. A return value of -1 on a sense mode request
implies that a physical address is not defined.
The NMA$C_PCLI_PHA parameter affects all ports on a single controller. If the
address specified is already being used on the extended LAN, SS$_IVADDR is
returned.

NMA$C_PCLI_PID

Protocol identifier. This parameter is required for, and valid only on, ports that
use 802 extended format packets. NMA$C_PCLI_PID is passed as a counted
5-byte string, which is the unique protocol identifier required for each 802
extended format user.
All protocol identifiers specified on a controller must be unique except when the
PID is being shared.
NMA$C_PCLI_PID may only be specified on a port when the 802 extended
packet format is selected; that is, NMA$C_PCLI_FMT is set to NMA$C_
LINFM_802E.

1 If the LAN controller is active and you do not specify this parameter, the parameter defaults to the current setting. If
the LAN controller is not active, this parameter defaults to the default value indicated.

(continued on next page)

Local Area Network (LAN) Device Drivers 975

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_PRM

Promiscuous mode (optional). One of the following values can be specified:

NMA$C_STATE_ON Promiscuous mode enabled
NMA$C_STATE_OFF Promiscuous mode disabled (default)
Only one port on each controller can be active with promiscuous mode enabled.
Enabling promiscuous mode requires PHY_IO privilege.
The NMA$C_PCLI_PRM parameter is passed as a longword value.
Compaq does not recommend promiscuous mode for normal usage.
Some Token Ring devices do not support real promiscuous access to the ring.
See Section 9.22.1 for additional information.

NMA$C_PCLI_PTY

Protocol type. This value is read as a 16-bit unsigned integer and must be
unique on the controller except when the protocol type is being shared. For
Ethernet format ports, this is a required parameter.
Valid protocol types are in the range 05-DD through FF-FF.
NMA$C_PCLI_PTY may only be specified on a port where the Ethernet packet
format is selected (NMA$C_PCLI_FMT is set to NMA$C_LINFM_ETH).
NMA$C_PCLI_PTY is passed as a longword value; however, only the low-order
word is used.

NMA$C_PCLI_RAC

Receive access control (Token Ring only). This optional parameter specifies
whether the application receives a copy of the access control (AC) field for each
Token Ring frame received. It is passed as a longword value. It must be passed
with one of the following values:

NMA$C_STATE_ON Application gets a copy of the AC for each Token

Ring frame received.

NMA$C_STATE_OFF Application does not get a copy of the AC for each

Token Ring frame received.

The AC is returned in the P5 buffer. The P5 buffer size for Token Ring should
always be a minimum of 54 bytes. This is due to the variable size of the Token
Ring header.
(continued on next page)

976 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_RES

Restart. This optional parameter allows the user to enable the automatic port
restart feature of the LAN drivers. One of the following values can be specified:
NMA$C_LINRES_DIS Disable automatic restart (default)
NMA$C_LINRES_ENA Enable automatic restart
The LAN drivers shut down all users of a controller if there is a fatal error on
the controller or if the LAN driver determines that the controller has stopped
functioning. All outstanding I/O operations on the LAN driver are completed
with either an SS$_ABORT or SS$_TIMEOUT status.
All ports that have the NMA$C_PCLI_RES parameter enabled (set to NMA$C_
LINRES_ENA) have the port automatically restarted by the LAN driver
approximately one second after it has been shut down due to a fatal error.
If the user issues read or write QIOs to the port during the time the port is shut
down, the driver completes the QIOs with an SS$_OPINCOMPL status.
All ports that have the automatic restart feature disabled must be restarted
by the application program when the port is shut down by the LAN driver.
The application program should wait approximately 2 seconds to allow the
LAN driver to stabilize. Once the LAN driver shuts down a port, it attempts
a maximum of 30 consecutive automatic restarts. If there are 30 consecutive
failures to restart the port, the port remains shut down.
Note that it is unusual to have fatal errors on a LAN controller or to have a
LAN driver detect that a LAN controller has stopped functioning. Having the
ability to automatically restart a users port makes the program easier to design
because the program does not have to take into account the possibility of the
LAN driver shutting down the port.

NMA$C_PCLI_RFC

Receive frame control (FDDI only). This optional parameter specifies whether
the application receives a copy of the Frame Control (FC) field for each FDDI
frame received. It is passed as a longword value; however, only the low-order
byte is used. It must be passed with one of the following values:

NMA$C_STATE_ON Application gets a copy of the FC for each FDDI

frame received.

NMA$C_STATE_OFF Application does not get a copy of the FC for

received FDDI frames (default).

For $QIO Read operations, the FC is passed to the application in the P5 buffer.
The following are the sizes required for the P5 buffer for various packet formats
and settings of NMA$C_PCLI_RFC:

Ethernet (NMA$C_LINFM_ETH) 14 if NMA$C_STATE_OFF is specified,

15 if NMA$C_STATE_ON is specified.

802 (NMA$C_LINFM_802) 16 if NMA$C_STATE_OFF is specified, 17 if

NMA$C_STATE_ON is specified.

802E (NMA$C_LINKFM_802E) 20 if NMA$C_STATE_OFF is specified,

21 if NMA$C_STATE_ON is specified.

Receiving the FC requires one additional byte of space in the P5 buffer. The FC
is the first byte in the P5 buffer, immediately preceding the 6-byte destination
address. The size of the P5 buffer required does not change from the CSMA/CD
sizes if NMA$C_PCLI_RFC is set to NMA$C_STATE_OFF.
(continued on next page)

Local Area Network (LAN) Device Drivers 977

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_SAP

802 format SAP. This parameter is required if the 802 packet format is selected
(NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). NMA$C_PCLI_SAP
defines an 802 SAP and is read as an 8-bit unsigned integer. The least
significant bit of the SAP must be zero and the SAP cannot be the null SAP
(all 8 bits equal zero) or the SNAP SAP. NMA$C_PCLI_SAP is passed as a
longword value; however, only the low-order byte is used.
The SAP specified by NMA$C_PCLI_SAP is the SAP used to match incoming
packets to complete read requests. It is used as the source SAP (SSAP) in all
transmissions (write QIOs). Because it is illegal to transmit using a group SAP
as the source SAP, the SAP specified by this NMA$C_PCLI_SAP cannot be a
group SAP. NMA$C_PCLI_GSP describes how to set up group SAPs on a port.
All individual SAPs specified on a controller must be unique on that controller;
therefore, the SAP specified using the NMA$C_PCLI_SAP parameter is checked
for uniqueness on the controller.

NMA$C_PCLI_
SRMODE

Sets the source routing (SR) mode for the $QIO user (Token Ring only).
This optional parameter allows the application to perform the source routing
discovery. It must be passed with one of the following values:

NMA$C_SR_TRANSPARENT Application source routing is transparent.

This is the default when this parameter is not specifiied.

NMA$C_SR_SELF This shuts off the automatic route discovery

exploration messages for this user.

The $QIOs exist to further manipulate the source routing cache. Compaq
recommends that applications use the NMA$C_SR_TRANSPARENT mode.
NMA$C_PCLI_SRV

Port service. This optional parameter specifies the service supplied by the
driver for the port. It can only be specified if the 802 packet format is selected
(NMA$C_PCLI_FMT is set to NMA$C_LINFM_802). This characteristic is
passed as a longword value. One of the following values can be specified:
NMA$C_LINSR_USR User-supplied service (default)
NMA$C_LINSR_CLI Class I service
See Section 9.18.2.1 for a description of Class I service and Section 9.18.2.2 for
a description of user-supplied service.

NMC$C_PCLI_XAC

Transmit access control (Token Ring only). This is an optional parameter that
enables applications to control the setting of the priority bits in the access
control (AC) for frames being transmitted in a $QIO write operation. When set
to the wanted value, all subsequent transmits use this AC value.
(continued on next page)

978 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 939 (Cont.) P2 Attributes
Parameter ID

Meaning

NMA$C_PCLI_XFC

Transmit frame control (FDDI only). NMA$C_PCLI_XFC is an optional

parameter that enables applications to control the setting of the priority bits
in the FC for frames being transmitted in a $QIO write operation. NMA$C_
PCLI_XFC is passed as a longword parameter that has many valid settings.
If specified with a value of zero, the application supplies an FC value on each
$QIO write operation. The FC value to be used in this case is supplied in the P5
buffer for the $QIO write operation. If the parameter is specified with a value
other than zero, that value is inserted into the FC field of every transmit by the
FDDI drivers. No FC is present in the P5 buffer for the $QIO write in this case.
If this parameter is not specified, the default setting (zero) of the priority bits is
used.
Regardless of how the FC is supplied, the value specified must be valid. The
allowable values for FC are between 50 hexadecimal and 57 hexadecimal. If
NMA$C_PCLI_XFC is specified with a nonzero value outside the valid range,
the application receives a SS$_BADPARAM error. The priority bits are the
three low-order bits.

9.20.3.2 Set Mode Parameters for Packet Formats

Table 940 summarizes the use of the set mode parameters for the Ethernet, 802,
and 802 extended (802E) packet formats.
Table 940 Set Mode Parameters for Packet Formats
Parameter ID

Ethernet

IEEE 802

802E

FMT

DEF

REQ

REQ

PTY

REQ

SAP

REQ

PID

REQ

ACC

OPT

DES

OPT

PAD

OPT

SRV

OPT

GSP

OPT

VAX specific. On Alpha systems, however, the ACC and DES parameters are OPT.
Legend
DEFDefault. If not specified, this is the default parameter for this packet format.
REQRequired. This parameter must be specified for this packet format.
OPTOptional. This parameter is optional for this packet format; it may be specified.
EError. This parameter cannot be specified for this packet format. If the parameter is specified,
it generates an SS$_BADPARAM error.

(continued on next page)

Local Area Network (LAN) Device Drivers 979

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 940 (Cont.) Set Mode Parameters for Packet Formats
Parameter ID

Ethernet

IEEE 802

802E

BFN, BUS,
CCA, CON,
CRC, EKO,
ILP, MCA,
MLT, PHA,
PRM, RAC,
RES, RFC,
SRMODE, XAC,
XFC

OPT

OPT

OPT

Alpha specific.
Legend
DEFDefault. If not specified, this is the default parameter for this packet format.
REQRequired. This parameter must be specified for this packet format.
OPTOptional. This parameter is optional for this packet format; it may be specified.
EError. This parameter cannot be specified for this packet format. If the parameter is specified,
it generates an SS$_BADPARAM error.

9.20.3.3 Set Mode Parameter Validation

When starting a LAN port, the LAN driver checks that the mode of the new port
is compatible with the mode of the LAN ports already started. There are two
sets of compatibility checks: one for ports running in shared mode and one for all
ports.

980 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
The following parameters must match for all ports on the same controller:
NMA$C_PCLI_CON
NMA$C_PCLI_CRC
NMA$C_PCLI_EKO
NMA$C_PCLI_ILP
NMA$C_PCLI_PHA (need only match for CSMA/CD controllers)
On VAX systems, the following parameters must match for all shared-default and
shared-with-destination users of the same protocol type:
NMA$C_PCLI_BFN
NMA$C_PCLI_BUS
NMA$C_PCLI_CCA
NMA$C_PCLI_MLT
NMA$C_PCLI_PAD
NMA$C_PCLI_PTY
NMA$C_PCLI_RAC
NMA$C_PCLI_RES
NMA$C_PCLI_RFC
NMA$C_PCLI_XAC
NMA$C_PCLI_XFC
Once a port is started, only the following parameters can be changed:
NMA$C_PCLI_GSP
NMA$C_PCLI_MCA
9.20.3.4 Shutdown Controller
The shutdown controller function shuts down the LAN port. On completion of a
shutdown request all outstanding I/O requests are completed. This port cannot be
used again until another startup request has been issued (see Section 9.20.3.1).
The following function code is used to shut down a port:
IO$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWNShut down port
The shutdown controller function takes no device- or function-dependent
arguments.
9.20.3.5 Enable Attention AST
This function requests that an attention AST be delivered to the requesting
process when a status change occurs on the assigned port. An AST is queued
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.
The following function code and modifier is used to enable an attention AST:

IO$_SETMODE!IO$M_ATTNASTEnable attention AST

This function takes the following device- or function-dependent arguments:

P1The address of an AST service routine or 0 for disable

P2Ignored

P3Access mode to deliver AST

Local Area Network (LAN) Device Drivers 981

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
The enable attention AST function enables an attention AST to be delivered
to the requesting process once only. After the AST occurs, it must be explicitly
reenabled by the function before the AST can occur again. The function is subject
to AST quotas.
The AST service routine is called with an argument list. The first argument is the
current value of the second longword of the I/O status block (see Section 9.21).
9.20.3.6 IO$M_SET_MAC Functional Modifier to IO$M_SETMODE
The IO$M_SET_MAC qualifier, when used with IO$_SETMODE, is used to
set medium specific parameters. The Token Ring parameters require PHY_IO
privilege to set. Table 941 shows the parameters that may be set for Ethernet.
Table 942 shows the parameters that may be set for FDDI. Table 943 shows the
parameters that may be set for Token Ring, and Table 944 shows the parameters
that may be set for ATM.
Table 941 Medium Specific Parameters of IO$M_SET_MAC for Ethernet (Alpha Only)
Parameter ID

Meaning

MA$C_PCLI_FDE

Enables or disables full duplex operation. The values for this parameter
are NMA$C_STATE_ON or NMA$C_STATE_OFF.

NMA$C_PCLI_LINEMEDIA

Sets the connection media type for the Ethernet adapter. Valid values
for this parameter are:
NMA$C_MEDIA_AUTO
NMA$C_MEDIA_AUI
NMA$C_MEDIA_BNC
NMA$C_MEDIA_TP

NMA$C_PCLI_LINESPEED

Sets the speed of the Ethernet adapter. Valid values for this parameter
are:
0Used to autosense the speed.
10Sets the speed to 10 Mb/s.
100Sets the speed to 100 Mb/s.
65636Used to autonegotiate with a maximum speed of 100 Mb/s.
65546Used to autonegotiate with a maximum speed of 10 Mb/s.

Table 942 Medium Specific Parameters of IO$M_SET_MAC for FDDI

Parameter ID

Meaning

NMA$C_PCLI_TREQ

Requested value for token rotation timer, ANSI MAC T_req parameter.
Units are in 80 nanoseconds, default is 8000, minimum is 4000, and
maximum is 167772.

NMA$C_PCLI_TVX

Maximum time between arrivals of a valid frame or unrestricted token,

ANSI MAC TVX parameter. Units are in 80 nanoseconds, default is
2621, minimum is 2500, and maximum is 5222.

NMA$C_PCLI_REST_TTO

Restricted token timeout which limits how long a single restricted mode
dialog may last before being terminated. Units are in milliseconds,
default is 1000, minimum is 0, and maximum is 10000.

NMA$C_PCLI_RPE

Ring purge enable. If 1 (TRUE), this link will particpate in the Ring
Purger election and, if elected, perform the Ring Purger function.
(continued on next page)

982 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 942 (Cont.) Medium Specific Parameters of IO$M_SET_MAC for FDDI
Parameter ID

Meaning

NMA$C_PCLI_NIF_TARG

Neighbor information frame target.

NMA$C_PCLI_SIF_CONF_
TARG

Station information frame configuration target. A 6-byte string

specifying the LAN address of the target. Used only by DECnet/OSI.

NMA$C_PCLI_SIF_OP_TARG

Station information frame operation target. A 6-byte string specifying

the LAN address of the target. Used only by DECnet/OSI.

NMA$C_PCLI_ECHO_TARG

Echo test target. A 6-byte string specifying the LAN address of the
target. Used only by DECnet/OSI.

NMA$C_PCLI_ECHO_DAT

Data pattern to use for the echo test. Used only by DECnet/OSI.

NMA$C_PCLI_ECHO_LEN

Length of the echo packet. Used only by DECnet/OSI.

Table 943 Medium Specific Parameters of IO$M_SET_MAC for Token Ring

Parameter ID

Meaning

NMA$C_PCLI_RNG_SPD

Sets the speed of the ring. This longword may be either:

NMA$C_LINRNG_FOURUsed for 4 Mb/s rings.
NMA$C_LINRNG_SIXTNUsed for 16 Mb/s rings.
The default is NMA$C_LINRNG_SIXTN.

NMA$C_PCLI_LINEMEDIA

Sets the connection media type for the Token Ring adapter. Valid values
for this longword parameter are:
NMA$C_MEDIA_STP
NMA$C_MEDIA_UTP
The default is NMA$C_MEDIA_STP.

NMA$C_PCLI_ETR

Controls the Early Token release feature of the Token Ring hardware.
This feature can greatly improve throughput, and is only valid on
16 Mb/s rings. The values for this longword parameter are NMA$C_
STATE_ON or NMA$C_STATE_OFF. The default is NMA$C_STATE_
ON.

NMA$C_PCLI_MONCONTEND

Specifies whether the controller participates in the monitor contention

process when another adapter detects the need for contention and
initiates the process. The values for this longword parameter are
NMA$C_STATE_ON or NMA$C_STATE_OFF. The default is NMA$C_
STATE_OFF.

NMA$C_PCLI_CACHE_ENT

The number of source routing (SR) entries to make available for

caching. The default is 200, minimum is 20, and maximum is 2000.
Each cache entry consumes 64 bytes.

NMA$C_PCLI_ROUTEDIS

The source routing discovery timer. This is the amount of seconds to

wait after the transmission of ring explorer packets before declaring the
route of a path to be unknown. The default is 2 seconds, minimum is 1,
and maximum is 255.

NMA$C_PCLI_A_TIM

The source routing aging timer. After traffic is neither received from
nor sent to a given node for this number of seconds, the entry is marked
stale. After the entry is marked stale, rediscovery is required to
communicate with the node. The default is 60 seconds, minimum is
1, and maximum is 65535.
(continued on next page)

Local Area Network (LAN) Device Drivers 983

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 943 (Cont.) Medium Specific Parameters of IO$M_SET_MAC for Token Ring
Parameter ID

Meaning

NMA$C_PCLI_SRC_ROU

Enables and disables source routing. The values for this longword
parameter are NMA$C_LINSRC_ENA or NMA$C_LINSRC_DIS. The
default is NMA$C_LINSRC_ENA.

NMA$C_PCLI_AUTH_PR

Specifies the highest priority that a user may transmit a frame. The
priority is set within the NMA$C_PCLI_XAC parameter. The default
for this parameter is 3, minimum is 0, and maximum is 6.

Table 944 Medium Specific Parameters of IO$M_SET_MAC for ATM

Parameter ID

Meaning

NMA$C_PCLI_MED

Medium. This longword parameter defaults to and may only be set to

NMA$C_LINMD_CSMACD.

NMA$C_PCLI_BUS

Buffer size. This longword parameter specifies the requested maximum

packet size of the emulated LAN. The value may be either 1516, 4544,
or 9234.

NMA$C_PCLI_ELAN_PAR

Parent device name. This is a 3- or 4-character string parameter that

specifies the name of the ATM device to associate with this emulated
LAN.

NMA$C_PCLI_NET

ELAN name. This is a string of up to 64 characters that specifies the

name of the emulated LAN to join.

NMA$C_PCLI_ELAN_DESC

ELAN description. This is a string of up to 64 characters long that

provides additional description of the emulated LAN for status displays.

NMA$C_PCLI_LES_HWA

LES ATM address. This is specified as a 40-character string as the

hexadecimal representation of a 20-byte ATM address.

NMA$C_PCLI_ELAN_STATE_
REQ

ELAN change state request value. This longword parameter directs the
driver to either start or shutdown the emulated LAN. Start is specified
by a value of 2. Shutdown is specified by a value of 4.

NMA$C_PCLI_EVENT_REQ

Event mask request. If set to 1, this longword parameter directs the

driver to set the event reporting mask to the value given by the event
parameter.

NMA$C_PCLI_EVENT

Event mask value. This is a longword bit mask that controls the
event reporting done by the driver. A bit set in the mask enables the
reporting of corresponding event(s).

9.20.3.7 IO$M_UPDATE_MAP Functional Modifier to IO$_SETMODE

Using Token Ring only, the IO$M_UPDATE_MAP qualifier, when used with
IO$_SETMODE, manipulates the adapters functional address mapping table.
Figure 924 shows the format of the P2 buffer for this operation. This QIO
requires PHY_IO privilege.

984 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Figure 924 Format of IO$M_UPDATE_MAP Setmode P2 Buffer (Alpha Only)
31

15

Length
(bytes following this field)

NMA$C_PCLI_MAP

MC Addr 1

Subfunction

MC Addr 3

MC Addr 2

FUNCTIONAL Address 2

FUNCTIONAL Address 1

ZK6791AGE

The subfunction is one of the following:

NMA$C_MAP_CHANGEThis function adds or changes a mapping in the

functional address table. If the specified multicast entry does not exist, an
entry is created with the specified functional address mask. If the specified
multicast entry does exist, the corresponding functional address mask is
changed to the specified mask. All users who currently have the multicast
enabled when the functional mask is changed will automatically update the
functional address table as part of this operation.
Possible errors returned include the following:
SS$_DEVICEFULLThis error indicates that there is insufficient space
in the mapping table to complete the request. The multicast to functional
address mapping table has 200 entries.

NMA$C_MAP_DELETEThis function deletes the specified MC address in

the table. For this function, the functional address mask is not required to
pass the P2 buffer. If the functional address mask is passed, its contents are
ignored.
Possible errors returned include the following:
SS$_BADPARAM This error indicates that the specified multicast
address cannot be found in the table.

The following example maps multicast address AB-01-01-01-02-03 to the

functional address 03-00-00-01-00-00 for device ICA0:.
LANCP>SET DEVICE/MAP= _LANCP>(MULTICAST=AB-01-01-01-02-03, _LANCP>FUNCTIONAL=00-01-00-00) ICA0:
The following example deletes the mapping of the multicast address of AB-01-0101-02-03 for the device ICA0:.
LANCP>SET DEVICE/NOMAP=(MULTICAST=AB-01-01-01-02-03) ICA0:

Local Area Network (LAN) Device Drivers 985

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
9.20.3.8 IO$M_ROUTE Functional Modifier to IO$_SETMODE
On Alpha systems using Token Ring only, the IO$M_ROUTE qualifier, when used
with IO$_SETMODE, manipulates the source routing cache table. This command
is successful only when source routing is enabled. Source routing is enabled with
the set mac qualified set mode QIO. Figure 925 shows the format of the P2
buffer. This QIO requires the PHY_IO privilege.
Figure 925 Format of the IO$M_ROUTE P2 Buffer (Alpha Only)
31

15

Length
(bytes following this field)

NMA$C_PCLI_MAP

MC Addr 1

Subfunction

MC Addr 3

MC Addr 2

Routing Information String

030 bytes.

RI_Size

ZK6792AGE

The subfunction is one of the following:

NMA$C_SR_ADDThis function adds or changes a source routing cache

entry. It enters the LAN address into the table with the enclosed routing
information. The routing information string format is documented in
Section 9.16.6. If RI_size is passed as 0, the entry is created (or modified)
to be in the EXPLORING state (this is useful for users who are doing their
own source routing). If the RC Lth field is zero, the LAN address is entered
in the table as being in the local state.
Possible errors returned include:
SS$_INSFMEMThe source routing cache is full.
SS$_BADPARAMAn invalid RI string was passed or invalid sizes were
passed.
SS$_IVMODESource routing is not enabled.

NMA$C_SR_DELETEThis function deletes a source routing cache entry.

The RI_size and the routing information string are not required for this QIO.
If one or both of the fields are passed for this operation, they are ignored. The
result of this command is to put the entry into the deleted state. When the
entry goes into the deleted state, it is deleted within 10 minutes.

986 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Possible errors returned include the following:
SS$_BADPARAMThe requested entry could not be found.

9.20.4 Sense Mode and Sense Characteristics

The sense mode function returns the port attributes in the specified buffers.
These attributes include the device characteristics described in Section 9.19 and,
with the exceptions noted below, the attributes listed in Table 939.
The following combinations of function code and modifier are provided:

IO$_SENSEMODE!IO$M_CTRLRead characteristics

IO$_SENSECHAR!IO$M_CTRLRead characteristics

IO$_SENSEMODE!IO$M_SENSE_MACMedium specific characteristics

On Alpha systems, the following combinations of function code and modifier for
Token Ring are provided:

IO$_SENSEMODE!IO$M_SHOW_MAPReturns current functional address

to multicast address mapping

IO$_SENSEMODE!IO$M_SHOW_ROUTEReturns current source routing

cache table

These functions take the following device- or function-dependent arguments:

P1The address of a two-longword buffer where the device characteristics

are stored. (Figure 926 shows the format for, and Section 9.19 describes the
contents of, the P1 buffer.) The P1 argument is optional.

P2The address of a quadword descriptor where the attributes buffer is

stored. The first longword of the descriptor is the buffer length; the second
longword is the address of the buffer. The P2 argument is optional.
The P2 buffer is not read by the LAN driver. The driver stores the ports
attributes in the buffer, which contains multiple entries. The format of each
entry depends on whether a longword or a counted string is returned, as
shown in Figure 927. Each parameter ID contains a string indicator bit (bit
12) that describes whether the data item is a string or a longword.

Except for the following differences, P2 returns the same attributes as those
listed in Table 939:

All parameters that are valid for the enabled packet format are returned (see
Table 940).

The sense-mode P2 buffer does not return the modifier word for the NMA$C_
PCLI_PHA, NMA$C_PCLI_MCA, and NMA$C_PCLI_DES parameter IDs.

The NMA$C_PCLI_DES parameter is only returned on Ethernet ports whose

access mode is set to shared with destination.

In addition to the parameter IDs listed in Table 939, the sense-mode P2

buffer contains the following parameter IDs:

Local Area Network (LAN) Device Drivers 987

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Parameter ID

Meaning

NMA$C_PCLI_FCA

List of the currently enabled functional addresses (Token

Ring only). Each 32-bit entry corresponds respectively with
the items returned under NMA$C_PCLI_MCA.

NMA$C_PCLI_HWA

Hardware address. Describes the value for the hardware

address. The hardware address is the default physical
address when no physical address has been specified and
there are no active users on the controller. NMA$C_PCLI_
HWA is returned in the same format as NMA$C_PCLI_PHA.

NMA$C_PCLI_MBS

Maximum packet length. NMA$C_PCLI_MBS is a longword,

read-only parameter. The value returned reflects the largest
data packet that the application can receive for its packet
format and type of LAN, measured in bytes. The values for
CSMA/CD, FDDI, and Token Ring are:
Packet format

CSMA/CD

FDDI

Token Ring

Ethernet format without padding

1500

4470

4418

Ethernet format with padding

1498

4468

4416

802 format with 1-byte CTL field

1497

4475

4423

802E format

1492

4470

4418

The values for LAN emulation over ATM are:

ATM ELAN
size:

Packet Format

NMA$C_PCLI_MED

1516 4544 9234

Ethernet format without padding

1500 4528 9218

Ethernet format with padding

1498 4526 9216

802 format with 1-byte CTL field

1497 4525 9215

802E format

1492 4520 9210

Type of medium to which the device is attached. Current

media supported are NMA$C_LINMD_FDDI (FDDI),
NMA$C_LINMD_CSMACD (Ethernet and IEEE 802.3),
and NMA$C_LINMD_TR (Token Ring). This is a longword
parameter.

Figure 926 Sense Mode P1 Characteristics Buffer

31

24 23

16 15

Maximum Message Size

Not Used

Error Summary

8 7

Type

Class

Status

Not Used
ZK1178GE

It is suggested that a size of 250 bytes be used for the P2 buffer. This will
allow space for additional parameters that may be returned in future releases of
OpenVMS.

988 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
All attributes that fit into the buffer specified by P2 are returned; however, if
all the attributes cannot be stored in the buffer, the I/O status block returns the
status SS$_BUFFEROVF. The second word of the I/O status block contains the
number of bytes used in the P2 buffer (see Section 9.21).
Figure 927 Sense Mode Attribute Buffer
Longword Parameter:
0

15 14 13 12 11
0

Parameter ID
Longword of
Value

* Not Used
String Parameter:
15 14 13 12 11
0

Parameter ID
Word of String Count
String

* Not Used
ZK1210GE

9.20.4.1 IO$M_SENSE_MAC Functional Modifier to IO$_SENSEMODE

The IO$M_SENSE_MAC qualifier, when used with IO$_SENSEMODE, returns
the parameters specified in Section 9.20.3.6. In addition to the set mac
parameters, Table 945 shows the returns of the following parameters:
Table 945 Parameters of IO$M_SENSE_MAC
Parameter ID

Meaning

NMA$C_PCLI_T_NEG

The negotiated value of the token rotation timer (ANSI MAC parameter T_neg)
(FDDI only).

NMA$C_PCLI_DAT

The duplicate address test flag (FDDI only). If set, this indicates that there is
another station on the ring with the same hardware LAN address.

NMA$C_PCLI_UNA

Upstream neighbors address (FDDI and Token Ring). This is a string

parameter specifying the 6-byte LAN address of the upstream neighbor. Not
all devices may support this feature.

NMA$C_PCLI_OLD_
UNA

The old (previous) upstream neighbor address (FDDI only). Neighbor addresses
change as nodes insert and deinsert into the ring.

NMA$C_PCLI_UN_DAT

The upstream neighbors duplicate address test flag (FDDI only).

NMA$C_PCLI_DNA

The downstream neighbors LAN address (FDDI only).

(continued on next page)

Local Area Network (LAN) Device Drivers 989

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 945 (Cont.) Parameters of IO$M_SENSE_MAC
Parameter ID

Meaning

NMA$C_PCLI_OLD_
DNA

The old (previous) downstream neighbors LAN address (FDDI only).

NMA$C_PCLI_RPS

The current ring purger state (FDDI only). This longword parameter is one of
the following values:
0Off
1Candidate
2Non-purger
3Purger

NMA$C_PCLI_RER

The latest ring error reason (FDDI only). This longword parameter is one of the
following values:
0No Error
5Ring Init initiated
6Ring Init received
7Ring beaconing initiated
8Duplicate address detected
9Duplicate token detected
10Ring purger error
11FCI strip error
12Ring op oscillation
14PC trace initiated
15PC trace received

NMA$C_PCLI_NBR_
PHY

Neighbors PHY type (FDDI only). This longword parameter is one of the
following values:
0A
1B
2S
3M
4Unknown

NMA$C_PCLI_RJR

Ring reject reason (FDDI only). This longword parameter is one of the following
values:
0None
1Local LCT
2Remote LCT
3LCT both sides
4LEM reject
5Topology error
6Noise reject
7Remote reject
8Trace in progress
9Trace received-disabled
10Standby
11LCT protocol error

NMA$C_PCLI_LEE

Link error estimate (FDDI only). The longword value is a negative exponent of
10 representing the Link error rate. For example, the value of X represents the
error rate of 10^X.
(continued on next page)

990 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 945 (Cont.) Parameters of IO$M_SENSE_MAC
Parameter ID

Meaning

NMA$C_PCLI_RNG_
NUM

The longword value contains the ring number that the controller is running on
(Token Ring only). It is only valid for a controller that is started, and also only
valid for rings that have a ring parameter server that is configured for providing
this information.

9.20.4.2 IO$M_SHOW_MAP Functional Modifier to IO$_SENSMODE

On Alpha systems using Token Ring only, the IO$M_SHOW_MAP qualifier,
when used with IO$_SENSEMODE, returns the current setting of the mapping
table. The P2 buffer is filled with the current multicast to functional address
mapping information. The entries are 16 bytes long and are in the format shown
in Figure 928. This QIO requires PHY_IO privilege.
Figure 928 Format of IO$M_SHOW_MAP P2 Buffer
31

15

Multicast 2

Multicast 1

Reserved

Multicast 3

Functional address mark

Reserved

Reserved

ZK6793AGE

The multicast address and functional address mask are returned in canonical
format (that is, not bit-reversed). The following errors may occur:

SS$_BUFFEROVFThe passed buffer is not large enough to hold all the data
required for the operation.

SS$_BADPARAMNot able to get read access to buffer or zero length buffer

passed.

9.20.4.3 IO$M_SHOW_ROUTE Functional Modifier to IO$_SENSEMODE

On Alpha systems with Token Ring only, the IO$M_SHOW_ROUTE qualifier,
when used with IO$_SENSEMODE, returns the current value of the source
routing cache table. Each entry is 64 bytes long. Figure 929 shows the format of
the returned P2 buffer.

Local Area Network (LAN) Device Drivers 991

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Figure 929 Format of IO$M_SHOW_ROUTE P2 Buffer (Alpha Only)
31

15

LAN Addr 2

LAN Addr1

Reserved

LAN Addr3

State of Entry
Routing Information String Size
Segment Descriptor

Routing Control Field

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Segment Descriptor

Last Transmit Timer

Last Receive Timer

Stale Timer

Discovery Timer

ZK6794AGE

992 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.20 LAN Function Codes
Table 946 shows possible states of the entry.
Table 946 State of the Entry
Value

Name

Description

LOCAL

Address is reachable on the attached ring.

STALE

Entry is stale (inactive).

UNKNOWN

Route to the address is unknown.

DELETED

Entry is marked for deletion.

KNOWN

Route is known and the route is stored in the routing

information string.

EXPLORING

Route to the address is currently being explored.

The LAN address is returned in canonical format (that is, not bit-reversed). The
timers are recorded as seconds before expiration. The transmit and receive timers
are initialized from the NMA$C_PCLI_A_TIM parameter, the discovery timer is
initialized from the NMA$C_PCLI_ROUTEDIS parameter, and the stale timer is
initialized to 10 minutes (600 seconds). The following errors may occur:

SS$_BUFFEROVFThe passed buffer is not large enough to hold all the data
required for the operation.

SS$_BADPARAMNot able to get read access to buffer or zero length buffer

passed.

9.21 I/O Status Block

The I/O status block (IOSB) for all LAN driver functions is shown in Figure 930.
Appendix A lists the completion status returned for these functions. (The
OpenVMS system messages documentation provides explanations and suggested
user actions for these status codes.)
Figure 930 IOSB Contents
+2

Transfer Size

Completion Status
+4

Not
Used

Error
Summary

Status

Not
Used

Byte of Value
ZK1179GE

The first longword of the IOSB returns, in addition to the completion status,
either the size (in bytes) of the data transfer or the size (in bytes) of the attribute
buffer (P2) returned by a sense mode function. The second longword returns the
unit and line status bits listed in Table 932 and the error summary bits listed in
Table 933.

Local Area Network (LAN) Device Drivers 993

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes

9.22 Application Programming Notes

This section contains information to assist you in writing application programs
that use the LAN device drivers. Section 9.22.1 discusses the additional rules
required for application programs that you intend to run in promiscuous mode.
Section 9.22.2 describe the Ethernet and 802 sample programs.

9.22.1 Promiscuous Mode

The LAN drivers allow only one port per controller to enable promiscuous
mode (NMA$C_PCLI_PRM specified as NMA$C_STATE_ON). A port running in
promiscuous mode usually places an additional load on the CPU because the LAN
device is configured to deliver all packets on the LAN to the LAN driver.
Table 947 details additional rules for ports running in promiscuous mode.
Table 947 Rules for Promiscuous Mode Operation
I/O Function

Rule

IO$_SETMODE
IO$_SETCHAR

It is not necessary to specify a unique identifier (a protocol type,

SAP, or protocol identifier parameter ID) in the P2 buffer.
The port cannot be running in shared mode.

IO$_WRITE

The user can only transmit packets in the packet format previously
specified with a set mode QIO when the user was started. The
unique identifier for the packet format must be included in the P5
buffer following the destination address (see Section 9.20.2).

IO$_READ

The LAN driver completes the promiscuous users read requests

with Ethernet, IEEE 802, and 802 extended packets. Because
any packet format can be used to complete a read request, the P5
parameter (if specified) must be at least 20 bytes in length (21 bytes
for FDDI with RFC turned on).
All Ethernet format packets are processed as if they have no size
field specified after the protocol type. Therefore, Ethernet packets
are always returned with 46 to 1500 bytes of data. If the Ethernet
packet contains a size field, it is returned as part of the user data in
the first word of the P1 buffer.
The promiscuous user should use the information returned in the P5
buffer to determine the packet format. If the application program
first filled the P5 buffer with zeros, the program can determine the
format of the packet received by scanning the P5 buffer after the
read request is completed.

9.22.2 Local Area Network Programming Examples

The VAX MACRO program LANETH.MAR (Example 93 shows the typical use of
QIO functions in driver operations such as establishing the protocol type, starting
the port, and transmitting and receiving data. The program sends a LOOPBACK
packet and waits for the packet to be returned.

994 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
The DEC C program LAN802E.C (Example 94) shows how to initialize an 802E
port and how to send and receive packets on that port. This program sends a
LOOPBACK packet and waits for the packet to be returned.
Example 93 LANETH.MAR Local Area Network Programming Example
.TITLE LAN SAMPLE TEST PROGRAM
.IDENT /X02/
.PSECT RWDATA,WRT,NOEXE,PAGE
;
;
;
;
;
;
;
;

This LAN test program sends a MOP loopback message to the Loopback Assistant
Multicast address and waits for a response. The program uses the LAN device
EWA0. To use a different device, change the device name in the program or
define the desired lan device as EWA0.
To build on VAX or Alpha:
$ MACRO LANETH
$ LINK LANETH
.LIBRARY "SYS$LIBRARY:LIB.MLB"
$IODEF
$NMADEF

; Define I/O functions and modifiers

; Define Network Management parameters

; Setmode parameter buffer and descriptor. Since the loopback protocol does
; not include a length word following the protocol type, we have to explicitly
; turn off padding since the default is on.
SETPARM:
.WORD NMA$C_PCLI_FMT
.LONG NMA$C_LINFM_ETH
.WORD NMA$C_PCLI_PTY
.LONG ^X0090
.WORD NMA$C_PCLI_PAD
.LONG NMA$C_STATE_OFF
SETPARMLEN = .-SETPARM

; Packet format
; Ethernet
; Protocol type
; Loopback
; Padding
; Off

SETPARMDSC:
.LONG SETPARMLEN
.ADDRESS SETPARM
; Sensemode parameter buffer and descriptor. This is used to get our physical
; address to put into the loopback message.
SENSEBUF:
.BLKB 512
SENSELEN=.-SENSEBUF
SENSEDSC:
.LONG SENSELEN
.ADDRESS SENSEBUF
; P2 transmit data buffer.
XMTBUF: .WORD 00
.WORD 02
FORW: .BLKB 6
.WORD 01
.WORD 00
XMTBUFLEN = .-XMTBUF

;
;
;
;

Skip count
Forward request
Forward address
Reply request

; Size of transmit buffer

; P5 transmit destination address, the Loopback Assistant Multicast Address.

XMTP5: .BYTE

^XCF,0,0,0,0,0

; P2 receive data buffer.

(continued on next page)

Local Area Network (LAN) Device Drivers 995

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 93 (Cont.) LANETH.MAR Local Area Network Programming Example
RCVBUF: .BLKB 512
RCVBUFLEN = .-RCVBUF

; Size of receive buffer

; P5 receive header buffer.

RCVP5:
RCVDA: .BLKB
RCVSA: .BLKB
RCVPTY: .BLKB

6
6
2

; Messages used to display status of this program.

GMSG:
LMSG:
EMSG:
DMSG:

.ASCID
.ASCID
.ASCID
.ASCID

"Successful test"
"No response"
"Error occurred while running test"
"LAN device not found"

; Miscellaneous data.
IOSB: .BLKQ 1
DEVCHAN:.BLKL 1
LANDSC: .ASCID EWA0

; I/O status block

; Returned port number
; Device to use for test

;*************************************************************************
;
; Start of code
;
;*************************************************************************
.PSECT CODE,EXE,NOWRT,PAGE
.ENTRY START,^M<>
; Assign a port to the LAN device.
$ASSIGN_S DEVNAM=LANDSC,CHAN=DEVCHAN
BLBS
R0,10$
; Branch if succeeded
MOVAL DMSG,R9
; Get address of error message
BRW
EXIT
; Print message and exit
; Set up the ports characteristics.
10$:

20$:

MOVAL EMSG,R9
; Assume error message address
$QIOW_S FUNC=#<IO$_SETMODE!IO$M_CTRL!IO$M_STARTUP>,CHAN=DEVCHAN,IOSB=IOSB,P2=#SETPARMDSC
BLBC
R0,20$
; Branch if failed
MOVZWL IOSB,R0
; Get status from IOSB
BLBS
R0,30$
; Branch if succeeded
BRW
EXIT
; Print message and exit

; Issue the SENSEMODE QIO to get our physical address for the loopback
; message.
30$:

$QIOW_S FUNC=#<IO$_SENSEMODE!IO$M_CTRL>,CHAN=DEVCHAN,IOSB=IOSB,P2=#SENSEDSC
BLBC
R0,20$
; Branch if failed
MOVZWL IOSB,R0
; Get status from IOSB
BLBC
R0,20$
; Branch if failed

; Locate the PHA parameter in the SENSEMODE buffer and copy it into the
; LOOPBACK transmit message. The PHA parameter is a string parameter.
(continued on next page)

996 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 93 (Cont.) LANETH.MAR Local Area Network Programming Example
40$:
50$:

60$:

MOVAB
BBS
ADDL
BRB
BICW3
CMPW
BEQL
ADDW
BRW
MOVL
MOVW

SENSEBUF,R0
#^XC,(R0),50$
#6,R0
40$
#^XF000,(R0)+,R1
R1,#NMA$C_PCLI_PHA
60$
(R0)+,R0
40$
2(R0),FORW
6(R0),FORW+4

;
;
;
;
;
;
;
;
;
;
;

Start at beginning of buffer

Branch if a string parameter
Skip over longword parameter
Check next parameter
Get type field less flag bits
Is this the PHA parameter?
Branch if so
Skip over string parameter
Check next parameter
Copy our address to the loopback
packet we are about to transmit

; Transmit the loopback message.

70$:

$QIOW_S FUNC=#IO$_WRITEVBLK,CHAN=DEVCHAN,IOSB=IOSB,P1=XMTBUF,P2=#XMTBUFLEN,P5=#XMTP5
BLBC
R0,70$
; Branch if failed
MOVZWL IOSB,R0
; Get status from IOSB
BLBS
R0,80$
; Branch if succeeded
BRW
EXIT
; Print message and exit

; Look for a response. We use the NOW function modifier on the READ so that
; we dont hang here waiting forever if there is no response. If there is no
; response in 1000 receive attempts, we declare no response status.
80$:
90$:

MOVL
#1000,R2
; Check 1000 times
$QIOW_S FUNC=#IO$_READVBLK!IO$M_NOW,CHAN=DEVCHAN,IOSB=IOSB,P1=RCVBUF,P2=#RCVBUFLEN,P5=#RCVP5
BLBC
R0,EXIT
; Branch if failed
MOVZWL IOSB,R0
; Get status from IOSB
BLBS
R0,100$
; Branch if succeeded
CMPL
R0,#SS$_ENDOFFILE
; Was there just no message available?
BNEQ
EXIT
; Branch if failed
SOBGTR R2,90$
; Try again

; No response in 1000 attempts.

MOVAL
BRW

LMSG,R9
EXIT

; Get address of lost message

; Print message and exit

; Received a message.
100$:

MOVAL

GMSG,R9

; Get address of success message

; The test is done. Call LIB$PUT_OUTPUT to display the test status.

EXIT:

PUSHL R9
CALLS #1,G^LIB$PUT_OUTPUT
$EXIT_S
.END

; P1 = Address of message to print

; Print the message
; Exit

START

Local Area Network (LAN) Device Drivers 997

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 94 LAN802.C Local Area Network Programming Example
/*************************************************************
* LAN Sample Test Program
*
* This LAN test program sends a MOP loopback message to the Loopback Assistant
* Multicast address and waits for a response. The program uses the LAN device
* EWA0. To use a different device, change the device name in the program or
* define the desired lan device as EWA0.
*
* To build on VAX:
To build on Alpha:
*
$ CC LAN802E
$ CC LAN802E + SYS$LIBRARY:SYS$LIB_C.TLB/LIB
*
$ LINK LAN802E,SYS$INPUT:/OPT
$ LINK LAN802E
*
SYS$SHARE:VAXCRTL.EXE/SHARE
*************************************************************/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#define
#define
#define
#define
#define
#define

<ctype>
<descrip>
<iodef>
<ssdef>
<starlet>
<stdio>
<stdlib>
<string>
<stsdef>

/*
/*
/*
/*
/*
/*
/*
/*
/*

Character type classification macros/routines */

For VMS descriptor manipulation */
I/O function code definitions */
System service return status code definitions */
System library routine prototypes */
ANSI C Standard Input/Output */
General utilities */
String handling */
VMS status code definitions */

NMA$C_PCLI_FMT 2770
NMA$C_PCLI_PID 2774
NMA$C_PCLI_PHA 2820
NMA$C_LINFM_802E 0
$SUCCESS(status) (((status) & STS$M_SUCCESS) == SS$_NORMAL)
$FAIL(status) (((status) & STS$M_SUCCESS) != SS$_NORMAL)

#pragma nomember_alignment
struct parm_802e
{
short pcli_fmt;
/* Format - 802E */
int fmt_value;
short pcli_pid;
/* Protocol ID - 08-00-2B-90-00 */
short pid_length;
char pid_value[5];
} setparm_802e = {NMA$C_PCLI_FMT, NMA$C_LINFM_802E,NMA$C_PCLI_PID, 5, 8,0,0x2b,0x90,0};
struct setparmdsc
{
int parm_len;
void *parm_buffer;
};
struct setparmdsc setparmdsc_loop = {sizeof(setparm_802e),&setparm_802e};
struct p5_param
{
unsigned char da[6];
unsigned char sa[6];
char misc[20];
};

/* P5 Receive header buffer */

(continued on next page)

998 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 94 (Cont.) LAN802.C Local Area Network Programming Example
struct iosb
{
short w_err;
short w_xfer_size;
short w_addl;
short w_misc;
};

/* IOSB structure */
/*
/*
/*
/*

Completion Status */
Transfer Size */
Additional status */
Miscellaneous */

struct ascid
{
short w_len;
short w_info;
char *a_string;
} devdsc = {4,0,"EWA0"};

/* Device descriptor for assign */

struct iosb qio_iosb;

struct p5_param rcv_param;
struct p5_param xmt_param={
0xCF,0,0,0,0,0};
char rcv_buffer[512];
char xmt_buffer[20]={
0,0,
2,0,
0,0,0,0,0,0,
1,0,
0,0};

/*
/*
/*
/*
/*
/*
/*
/*
/*
/*

char sense_buffer[512];

/* Sensemode buffer */

IOSB structure */
Receive header structure */
Transmit header structure */
Loopback Assistant Multicast Address */
Receive buffer */
Transmit buffer */
Skip count */
Forward request */
Forward address */
Reply request */

struct setparmdsc sensedsc_loop = {sizeof(sense_buffer),&sense_buffer};

/*
* MAIN
*/
main(int argc, char *argv[])
{
int i, j;
int chan;
int status;

/* Scratch */
/* Channel assigned */
/* Return status */

/*
* Start a channel.
*/
status = sys$assign(&devdsc,&chan,0,0);
if ($FAIL(status)) exit(status);
status = sys$qiow(0,chan,IO$_SETMODE|IO$M_CTRL|IO$M_STARTUP,&qio_iosb,0,0,0,
&setparmdsc_loop,0,0,0,0);
if ($SUCCESS(status)) status = qio_iosb.w_err;
if ($FAIL(status))
{
printf("IOSB addl status = %04X %04X (on startup)\n",qio_iosb.w_addl,qio_iosb.w_misc);
exit(status);
}
/*
* Issue the SENSEMODE QIO to get our physical address for the loopback message.
*/
(continued on next page)

Local Area Network (LAN) Device Drivers 999

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 94 (Cont.) LAN802.C Local Area Network Programming Example
status = sys$qiow(0,chan,IO$_SENSEMODE|IO$M_CTRL,&qio_iosb,0,0,0,
&sensedsc_loop,0,0,0,0);
if ($SUCCESS(status)) status = qio_iosb.w_err;
if ($FAIL(status))
{
printf("IOSB addl status = %04X %04X (on sensemode)\n",
qio_iosb.w_addl,qio_iosb.w_misc);
exit(status);
}
/*
* Locate the PHA parameter in the SENSEMODE buffer and copy it into the
* LOOPBACK transmit message. The PHA parameter is a string parameter.
*/
j = 0;
while (j < sizeof(sense_buffer))
{
i = (sense_buffer[j] + (sense_buffer[j+1]<<8));
if (0x1000 & i)
{
if ((i & 0xFFF) == NMA$C_PCLI_PHA)
{
memcpy(&xmt_buffer[4],&sense_buffer[j+4],6);
break;
}
j += (sense_buffer[j+2] + (sense_buffer[j+3]<<8)) + 4;
}
else
{
j += 6;
/* Skip over longword parameter */
}
}
/*
* Transmit the loopback message.
*/
status = sys$qiow(0,chan,IO$_WRITEVBLK,&qio_iosb,0,0,&xmt_buffer[0],
sizeof(xmt_buffer),0,0,&xmt_param,0);
if ($SUCCESS(status)) status = qio_iosb.w_err;
if ($FAIL(status))
{
printf("IOSB addl status = %04X %04X (on transmit)\n",
qio_iosb.w_addl,qio_iosb.w_misc);
exit(status);
}
/*
* Look for a response. We use the NOW function modifier on the READ so that
* we dont hang here waiting forever if there is no response. If there is no
* response in 1000 receive attempts, we declare no response status.
*/
(continued on next page)

9100 Local Area Network (LAN) Device Drivers

Local Area Network (LAN) Device Drivers

9.22 Application Programming Notes
Example 94 (Cont.) LAN802.C Local Area Network Programming Example
for (i=0;i<1000;i++)
{
status = sys$qio(0,chan,IO$_READVBLK|IO$M_NOW,&qio_iosb,0,0,&rcv_buffer[0],
sizeof(rcv_buffer),0,0,&rcv_param,0);
if ($SUCCESS(status)) status = qio_iosb.w_err;
if ($SUCCESS(status)) break;
}
if ($SUCCESS(status))
printf("Successful test\n");
else
printf("No response\n");
}

9.23 References
The following publications provide more information on local area networks:

IEEE Standards 802.1 (A, B, C, and D), 802.2, and 802.3

The EthernetData Link Layer and Physical Layer Specification

ANSI X3t9.5 and X3.139

Digital FDDI Network Architecture

ATM Forums LANE V1.0 Specification

RFC 1577

Local Area Network (LAN) Device Drivers 9101

10
Optional Features for Improving I/O
Performance
This chapter includes updated information for OpenVMS Version 7.31.
As of Version 7.0, OpenVMS Alpha includes two features that provide
dramatically improved I/O performance: Fast I/O and Fast Path. These features
are designed to promote OpenVMS as a leading platform for database systems.
Performance improvement results from reducing the CPU cost per I/O request
and improving symmetric multiprocessing (SMP) scaling of I/O operations. The
CPU cost per I/O is reduced by optimizing code for high-volume I/O and by using
better SMP CPU memory cache. SMP scaling of I/O is increased by reducing the
number of spinlocks taken per I/O and by substituting finer-granularity spinlocks
for global spinlocks.
The improvements follow a natural division that already exists between the
device-independent and device-dependent layers in the OpenVMS I/O subsystem.
The device-independent overhead is addressed by Fast I/O, which is a set of
lean system services that can substitute for certain $QIO operations. Using
these services requires some coding changes in existing applications, but the
changes are usually modest and well contained. The device-dependent overhead
is addressed by Fast Path, which is an optional performance feature that creates
a fast path to the device. It requires no application changes.
Fast I/O and Fast Path can be used independently; however, together they can
provide a 45% reduction in CPU cost per I/O on uniprocessor systems and a 52%
reduction on multiprocessor systems.

10.1 Fast I/O

Fast I/O is a set of three system services that were developed as a $QIO
alternative built for speed. These services are not a $QIO replacement; $QIO
is unchanged, and $QIO interoperation with these services is fully supported.
Rather, the services substitute for a subset of $QIO operations, namely, only the
high-volume read/write I/O requests.
The Fast I/O services support 64-bit addresses for data transfers to and from disk
and tape devices.
While Fast I/O services are available on OpenVMS VAX, the performance
advantage applies only to OpenVMS Alpha. OpenVMS VAX has a run-time
library (RTL) compatibility package that translates the Fast I/O service requests
to $QIO system service requests, so one set of source code can be used on both
VAX and Alpha systems.

Optional Features for Improving I/O Performance 101

Optional Features for Improving I/O Performance

10.1 Fast I/O
10.1.1 Fast I/O Benefits
The performance benefits of Fast I/O result from streamlining high-volume I/O
requests. The Fast I/O system service interfaces are optimized to avoid the
overhead of general-purpose services. For example, I/O request packets (IRPs)
are now permanently allocated and used repeatedly for I/O rather than allocated
and deallocated anew for each I/O.
The greatest benefits stem from having user data buffers and user I/O status
structures permanently locked down and mapped using system space. This
allows Fast I/O to do the following:

For direct I/O, avoid per-I/O buffer lockdown or unlocking.

For buffered I/O, avoid allocation and deallocation of a separate system buffer,
because the user buffer is always addressable.

Complete Fast I/O operations at IPL 8, thereby avoiding the interrupt

chaining usually required by the more general-purpose $QIO system service.
For each I/O, this eliminates the IPL 4 IOPOST interrupt and a kernel AST.

In total, Fast I/O services eliminate four spinlock acquisitions per I/O (two for the
MMG spinlock and two for the SCHED spinlock). The reduction in CPU cost per
I/O is 20% for uniprocessor systems and 10% for multiprocessor systems.

10.1.2 Using Buffer Objects

The lockdown of user-process data structures is accomplished by buffer objects.
A buffer object is process memory whose physical pages have been locked in
memory and double-mapped into system space. After creating a buffer object, the
process remains fully pageable and swappable and the process retains normal
virtual memory access to its pages in the buffer object.
If the buffer object contains process data structures to be passed to an OpenVMS
system service, the OpenVMS system can use the buffer object to avoid any
probing, lockdown, and unlocking overhead associated with these process data
structures. Additionally, double-mapping into system space allows the OpenVMS
system direct access to the process memory from system context.
To date, only the $QIO system service and the Fast I/O services have been
changed to accept buffer objects. For example, a buffer object allows a
programmer to eliminate I/O memory management overhead. On each I/O,
each page of a user data buffer is probed and then locked down on I/O initiation
and unlocked on I/O completion. Instead of incurring this overhead for each I/O,
it can be done once at buffer object creation time. Subsequent I/O operations
involving the buffer object can completely avoid this memory management
overhead.
Two system services can be used to create and delete buffer objects, respectively,
and can be called from any access mode. To create a buffer object, the $CREATE_
BUFOBJ system service is called. This service expects as inputs an existing
process memory range and returns a buffer handle for the buffer object. The
buffer handle is an opaque identifier used to identify the buffer object on future
I/O requests. The $DELETE_BUFOBJ system service is used to delete the buffer
object and accepts as input the buffer handle. Although image rundown deletes
all existing buffer objects, it is good form for the application to clean up properly.

102 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.1 Fast I/O
A 64-bit equivalent version of the $CREATE_BUFOBJ system service ($CREATE_
BUFOBJ_64) can be used to create buffer objects from the new 64-bit P2 or S2
regions. The $DELETE_BUFOBJ system service can be used to delete 32-bit or
64-bit buffer objects.
Buffer objects require system management. Because buffer objects tie up physical
memory, extensive use of buffer objects requires system management planning.
All the bytes of memory in the buffer object are deducted from a systemwide
system parameter called MAXBOBMEM (maximum buffer object memory).
System managers must set this parameter correctly for the application loads that
run on their systems.
The MAXBOBMEM parameter defaults to 100 Alpha pages, but for applications
with large buffer pools it will likely be set much larger. To prevent user-mode
code from tying up excessive physical memory, user-mode callers of $CREATE_
BUFOBJ must have a new system identifier, VMS$BUFFER_OBJECT_USER,
assigned. This new identifier is automatically created in an OpenVMS Version
7.0 upgrade if the file SYS$SYSTEM:RIGHTSLIST.DAT is present. The system
manager can assign this identifier with the DCL command SET ACL command to
a protected subsystem or application that creates buffer objects from user mode.
It may also be appropriate to grant the identifier to a particular user with the
Authorize utility command GRANT/IDENTIFIER (for example, to a programmer
who is working on a development system).
There is currently a restriction on the type of process memory that can be used
for buffer objects. Global section memory cannot be made into a buffer object.

10.1.3 Differences Between Fast I/O Services and $QIO

The precise definition of high-volume I/O operations optimized by Fast I/O
services is important. I/O that does not comply with this definition either is not
possible with the Fast I/O services or is not optimized. The characteristics of the
high-volume I/O optimized by Fast I/O services can be seen by contrasting the
operation of Fast I/O system services to the $QIO system service as follows:

The $QIO system service I/O status block (IOSB) is replaced by an I/O status
area (IOSA) that is larger and quadword aligned. The transfer byte count
returned in IOSA is 64 bits, and the field is aligned on a quadword boundary.
Unlike the IOSB, which is optional, the IOSA is required.

User data buffers must be aligned to a 512-byte boundary.

All user process structures passed to the Fast I/O system services must reside
in buffer objects. This includes the user data buffer and the IOSA.

Only transfers that are multiples of 512 bytes are supported.

Only the following function codes are supported: IO$_READVBLK,

IO$_READLBLK, IO$_WRITEVBLK, and IO$_WRITELBLK.

Only I/O to disk and tape devices is optimized for performance.

No event flags are used with Fast I/O services. If application code must
use an event flag in relation to a specific I/O, then the Event No Flag EFN
(EFN$C_ENF) can be used. This event flag is a no-overhead EFN that can be
used in situations when an EFN is required by a system service interface but
has no meaning to an application.

Optional Features for Improving I/O Performance 103

Optional Features for Improving I/O Performance

10.1 Fast I/O
For example, Fast I/O services do not use EFNs, so the application cannot
specify a valid EFN associated with the I/O to the $SYNCH system service
with which to synchronize I/O completion. To resolve this issue, the
application can call the $SYNCH system service passing as arguments:
EFN$C_ENF and the address of the appropriate IOSA. Specifying EFN$C_
ENF signifies to $SYNCH that no EFN is involved in the synchronization
of the I/O. Once the IOSA has been written with a status and byte count,
return from the $SYNCH call occurs. The IOSA is now the central point
of synchronization for a given Fast I/O (and is the only way to determine
whether the asynchronous I/O is complete).

To minimize arguments passing overhead to these services, the $QIO

parameters P3 through P6 are replaced by a single argument that is passed
directly by the Fast I/O system services to device drivers. For disk-like
devices, this argument is the media address (VBN or LBN) of the transfer.
For drivers with complex parameters, this argument is the address of a
descriptor or of a buffer specific to the device and function.

Segmented transfers are supported by Fast I/O but are not fully optimized.
There are two major causes of segmented transfers. The first is disk
fragmenting. While this can be an issue, it is assumed that sites seeking
maximum performance have eliminated the overhead of segmenting I/O due
to fragmentation.
A second cause of segmenting is issuing an I/O that exceeds the ports
maximum limit for a single transfer. Transfers beyond the port maximum
limit are segmented into several smaller transfers. Some ports limit transfers
to 64K bytes. If the application limits its transfers to less than 64K bytes,
this type of segmentation should not be a concern.

10.1.4 Using Fast I/O Services

The three Fast I/O system services are:

$IO_SETUPSets up an I/O

$IO_PERFORM[W]Performs an I/O request

$IO_CLEANUPCleans up an I/O request

10.1.4.1 Using Fandles

A key concept behind the operation of the Fast I/O services is the file handle or
fandle. A fandle is an opaque token that represents a setup I/O. A fandle is
needed for each I/O outstanding from a process.
All possible setup, probing, and validation of arguments is performed off the
mainline code path during application startup with calls to the $IO_SETUP
system service. The I/O function, the AST address, the buffer object for the data
buffer, and the IOSA buffer object are specified on input to $IO_SETUP service,
and a fandle representing this setup is returned to the application.
To perform an I/O, the $IO_PERFORM system service is called, specifying the
fandle, the channel, the data buffer address, the IOSA address, the length of the
transfer, and the media address (VBN or LBN) of the transfer.
If the asynchronous version of this system service, $IO_PERFORM, is used to
issue the I/O, then the application can wait for I/O completion using a $SYNCH
specifying EFN$C_ENF and the appropriate IOSA. The synchronous form of
the system service, $IO_PERFORMW, is used to issue an I/O and wait for
it to complete. Optimum performance comes when the application uses AST

104 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.1 Fast I/O
completion; that is, the application does not issue an explicit wait for I/O
completion.
To clean up a fandle, the fandle can be passed to the $IO_CLEANUP system
service.
10.1.4.2 Modifying Existing Applications
Modifying an application to use the Fast I/O services requires a few source-code
changes. For example:
1. A programmer adds code to create buffer objects for the IOSAs and data
buffers.
2. The programmer changes the application to use the Fast I/O services. Not all
$QIOs need to be converted. Only high-volume read/write I/O requests should
be changed.
A simple example is a database writer program, which writes modified pages
back to the database. Suppose the writer can handle up to 16 simultaneous
writes. At application startup, the programmer would add code to create 16
fandles by 16 $IO_SETUP system service calls.
3. In the main processing loop within the database writer program, the
programmer replaces the $QIO calls with $IO_PERFORM calls. Each $IO_
PERFORM call uses one of the 16 available fandles. While the I/O is in
progress, the selected fandle is unavailable for use with other I/O requests.
The database writer is probably using AST completion and recycling fandle,
data buffer, and IOSA once the completion AST arrives.
If the database writer routine cannot return until all dirty buffers are written
(that is, it must wait for all I/O completions), then $IO_PERFORMW can be
used. Alternatively $IO_PERFORM calls can be followed by $SYNCH system
service calls passing the EFN$C_ENF argument to await I/O completions.
The database writer will run faster and scale better because I/O requests now
use less CPU time.
4. When the application exits, an $IO_CLEANUP system service call is done for
each fandle returned by a prior $IO_SETUP system service call. Then the
buffer objects are deleted. Image rundown performs fandle and buffer object
cleanup on behalf of the application, but it is good form for the application to
clean up properly.
10.1.4.3 I/O Status Area (IOSA)
The central point of synchronization for a given Fast I/O is its IOSA. The IOSA
replaces the $QIO system services IOSB argument. Larger than the IOSB
argument, the byte count field in the IOSA is 64 bits and quadword aligned.
Unlike the $QIO system service, Fast I/O services require the caller to supply an
IOSA and require the IOSA to be part of a buffer object.
The IOSA context field can be used in place of the $QIO system service ASTPRM
argument. The $QIO ASTPRM argument is typically used to pass a pointer back
to the application on the completion AST to locate the user context needed for
resuming a stalled user-thread; however, for the $IO_PERFORM system service,
the ASTPRM on the completion AST is always the IOSA. Because there is no
user-settable ASTPRM, an application can store a pointer to the user-thread
context for this I/O in the IOSA context field and retrieve the pointer from the
IOSA in the completion AST.

Optional Features for Improving I/O Performance 105

Optional Features for Improving I/O Performance

10.1 Fast I/O
10.1.4.4 $IO_SETUP
The $IO_SETUP system service performs the setup of an I/O and returns a
unique identifier for this setup I/O, called a fandle, to be used on future I/Os. The
$IO_SETUP arguments used to create a given fandle remain fixed throughout
the life of the fandle. This has implications for the number of fandles needed in
an application. For example, a single fandle can be used only for reads or only
for writes. If an application module has up to 16 simultaneous reads or writes
pending, then potentially 32 fandles are needed to avoid any $IO_SETUP calls
during mainline processing.
The $IO_SETUP system service supports an expedite flag, which is available to
boost the priority of an I/O among the other I/O requests that have been handed
off to the controller. Unrestrained use of this argument is useless, because if
all I/O is expedited, nothing is expedited. Note that this flag requires the use of
ALTPRI and PHY_IO privilege.
10.1.4.5 $IO_PERFORM[W]
The $IO_PERFORM[W] system service accepts a fandle and five other variable
I/O parameters for the high-performance I/O operation. The fandle remains in
use to the application until the $IO_PERFORMW returns or if $IO_PERFORM is
used until a completion AST arrives.
The CHAN argument to the fandle contains the data channel returned to the
application by a previous file operation. This argument allows the application
the flexibility of using the same fandle for different open files on successive I/Os;
however, if the fandle is used repeatedly for the same file or channel, then an
internal optimization with $IO_PERFORM is taken.
Note that $IO_PERFORM was designed to have no more than six arguments to
take advantage of the OpenVMS Calling Standard, which specifies that calls with
up to six arguments can be passed entirely in registers.
10.1.4.6 $IO_CLEANUP
A fandle can be cleaned up by passing the fandle to the $IO_CLEANUP system
service.
10.1.4.7 Fast I/O FDT Routine (ACP_STD$FASTIO_BLOCK)
Because $IO_PERFORM supports only four function codes, this system service
does not use the generalized function decision table (FDT) dispatching that is
contained in the $QIO system service. Instead, $IO_PERFORM uses a single
vector in the driver dispatch table called DDT$PS_FAST_FDT for all the four
supported functions. The DDT$PS_FAST_FDT field is a FDT routine vector that
indicates whether the device driver called by $IO_PERFORM is set up to handle
Fast I/O operations. A nonzero value for this field indicates that the device driver
supports Fast I/O operations and that the I/O can be fully optimized.
If the DDT$PS_FAST_FDT field is zero, then the driver is not set up to handle
Fast I/O operations. The $IO_PERFORM system service tolerates such device
drivers, but the I/O is only slightly optimized in this circumstance.
The OpenVMS disk and tape drivers that ship as part of OpenVMS Version 7.0
have added the following line to their driver dispatch table (DDTAB) macro:
FAST_FDT=ACP_STD$FASTIO_BLOCK,- ; Fast-IO FDT routine
This line initializes the DDT$PS_FAST_FDT field to the address of the standard
Fast I/O FDT routine, ACP_STD$FASTIO_BLOCK.

106 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.1 Fast I/O
If you have a disk or tape device driver that can handle Fast I/O operations, you
can add this DDTAB macro line to your driver. If you cannot use the standard
Fast I/O FDT routine, ACP_STD$FASTIO_BLOCK, you can develop your own
based on the model presented in this routine.

10.1.5 Additional Information

Refer to the OpenVMS System Services Reference Manual for additional
information about the following Fast I/O system services:
$CREATE_BUFOBJ
$DELETE_BUFOBJ
$CREATE_BUFOBJ_64
$IO_SETUP
$IO_PERFORM
$IO_CLEANUP
To see a sample program that demonstrates the use of buffer objects and
the Fast I/O system services, refer to the IO_PERFORM.C program in the
SYS$EXAMPLES directory.

10.2 Fast Path (Alpha Only)

Fast Path is an optional, high-performance feature designed to improve I/O
performance. Fast Path creates a streamlined path to the device. Fast Path is
of interest to any application where enhanced I/O performance is desirable. Two
examples are database systems and real-time applications, where the speed of
transferring data to disk is often a vital concern.
Using Fast Path features does not require source-code changes. Minor interface
changes are available for expert programmers who want to maximize Fast Path
benefits.
The following table lists the supported ports for each OpenVMS Alpha version:
Version

Ports

7.31

KZPEA

7.3

CIXCD, CIPCA, KGPSA, KZPBA

7.1

CIXCD, CIPCA

7.0

CIXCD

Prior to OpenVMS Alpha Version 7.31, all hardware interrupts took place on
the primary CPU. Interrupts from Fast Path enabled devices would have to be
redirected from the primary CPU to a preferred CPU. However, this redirection
still involved the primary CPU, and also incurred interprocessor overhead.
Starting with OpenVMS Alpha Version 7.31, hardware interrupts that are
targetted for a preferred CPU go directly to the preferred CPU, thereby
eliminating any I/O processing in the primary CPU. This major Fast Path
enhancement is known as distributed interrupts.
Note
This feature is available on Fibre Channel, CI, and some SCSI ports on
AlphaServer DS20, ES40/45, and GS series systems.

Optional Features for Improving I/O Performance 107

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
For more information about Fibre Channel, SCSI, and CI configurations, refer to
Guidelines for OpenVMS Cluster Configurations.
Fast Path is not available on the OpenVMS VAX operating system.

10.2.1 Fast Path Features and Benefits

Fast Path achieves dramatic performance gains by reducing CPU time for I/O
requests on both uniprocessor and SMP systems. These savings are on the
order of 25% less CPU cost per I/O request on a uniprocessor and 35% less on a
multiprocessor system. The performance benefits are produced by:

Reducing code paths through streamlining for the case of high-volume I/O

Substituting port-specific spinlocks for global I/O subsystem spinlocks

Executing I/O requests for a given port on a specific CPU

The performance improvement can best be seen by contrasting the current

OpenVMS I/O scheme to the new Fast Path scheme. While transparent to an
OpenVMS user, each disk and tape device is tied to a specific port. All I/O for
a device is sent out over its assigned port. Under the current OpenVMS I/O
scheme, an I/O can be initiated on any CPU, but I/O completion must occur on
the primary CPU. Under Fast Path, all I/O for Fast Path-capable devices (such as
disks) for a given port is assigned to a specific CPU, eliminating the requirement
for completing the I/O on the primary CPU. This means that the entire I/O can
be initiated and completed on a single CPU. Because I/O operations are no longer
split among different CPUs, performance increases as memory cache thrashing
between CPUs decreases.
Fast Path also removes the primary CPU as a possible SMP bottleneck. Without
Fast Path, the primary CPU must be involved in all I/O. Once this CPU becomes
saturated, no further increase in I/O throughput is possible. Spreading the I/O
load evenly among CPUs in a multiprocessor system provides greater maximum
I/O throughput. This is achieved by assigning each Fast Path port to a specific
CPU referred to as the ports preferred CPU.
With most of the I/O code path executing under port-specific spinlocks and on
each ports preferred CPU, a highly scalable SMP model of parallel I/O operation
exists. Given multiple ports and CPUs, I/Os can be issued and processed in
parallel to a large degree.
Preferred CPU Selection
All Fast Path ports are assignable to CPUs. You can set a system parameter
specifying the set of CPUs that are allowed to serve as preferred CPUs. This set
is called the set of allowable CPUs. At any point in time, the set of CPUs that
currently can have ports assigned to them, called the set of usable CPUs, is the
intersection of the set of allowable CPUs, and the current set of running CPUs.
Each Fast Path Port is initially assigned to a CPU by the FASTPATH_SERVER
process that runs at port initialization time. This process executes an automatic
assignment algorithm that spreads Fast Path ports evenly among the usable
CPUs. The FASTPATH_SERVER process also runs whenever a secondary CPU
is started, and whenever the set of system parameters specifying the allowable
CPUs is changed.
If the primary CPU is in the set of allowable CPUs, the initial distribution will
be biased against the primary CPU in that a port will only be assigned to the
primary after ports have been assigned to each of the other usable CPUs.

108 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
To identify a device or ports current preferred CPU, you can use either $GETDVI
or the SHOW DEVICE/FULL command. To identify the Fast Path ports currently
assigned to a CPU, you use the SHOW CPU /FULL command.
You can directly assign a Fast Path port to a CPU, or request the system to
automatically select the ports preferred CPU from a specific set of CPUs. To
do this, you either issue a $QIO or use the SET DEVICE/PREFERRED_CPU
command. This will also set the ports User Preferred CPU to be the selected
CPU.
You can clear the ports User Preferred CPU by issuing either a $QIO, or by using
the SET DEVICE/NOPREFERRED CPU DCL command.
You can redistribute the system assignable Fast Path ports across a subset of the
set of usable CPUs by calling the $IO_FASTPATH system service.
Optimizing Application Performance
Processes running on a ports preferred CPU have an inherent advantage when
issuing I/O to a port in that the overhead to assign the I/O to the preferred
CPU can be avoided. An application process can use the $PROCESS_AFFINITY
system service to assign itself to the preferred CPU of the device to which the
majority of its I/O is sent.
With proper attention to assignment, a processs execution need never leave the
preferred CPU. This presents a scalable process and I/O scheme for maximizing
multiprocessor system operation. Like most RISC systems, Alpha system
performance is highly dependent on the performance of CPU memory caches.
Process assignment and preferred CPU assignment are two keys to minimizing
the memory stalls in the application and in the operating system, thereby
maximizing multiprocessor system throughput.

10.2.2 Using Fast Path

This section describes how to manage Fast Path.
10.2.2.1 Fast Path System Parameters
There are three FAST_PATH system parameters:

FAST_PATH

FAST_PATH_PORTS

IO_PREFER_CPUS

These parameters can be used to control Fast Path as follows:

FAST_PATH
FAST_PATH is a static system parameter that enables (1) or disables (0) the Fast
Path performance features for all Fast Path-capable ports.
Starting in OpenVMS Version 7.2, Fast Path is enabled by default. In Versions
7.0 and 7.1, Fast Path was disabled by default.
FAST_PATH_PORTS
FAST_PATH_PORTS is a 32-bit mask. Once Fast Path has been enabled by
setting FAST_PATH to 1, FAST_PATH_PORTS can be used to selectively disable
Fast Path for some specific adapter types.

Optional Features for Improving I/O Performance 109

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
The value of the FAST_PATH_PORTS system parameter is the sum of the values
of the bits that have been set. Following is a description of the bit mask:
Bit

Mask

Description

00000001

0 = Fast Path is ENABLED for KZPBA ports when FAST_PATH is set

to 1.
1 = Fast Path is DISABLED for KZPBA ports.

00000002

0 = Fast Path is ENABLED for KGPSA ports when FAST_PATH is set

to 1.
1 = Fast Path is DISABLED for KGPSA ports.

00000004

0 = Fast Path is ENABLED for KZPEA ports when FAST_PATH is set

to 1.
1 = Fast Path is DISABLED for KZPEA ports.

The remaining bits are reserved for possible future adapter types.
The default setting for FAST_PATH_PORTS is 0; therefore, the following ports
are enabled: KZPBA, KGPSA, and KZPEA.
Note that CI drivers are not controlled by FAST_PATH_PORTS. Fast Path for CI
is enabled and disabled exclusively by the FAST_PATH system parameter.
IO_PREFER_CPUS
IO_PREFER_CPUS is a dynamic system parameter that controls the set of CPUs
available for use as Fast Path preferred CPUs.
IO_PREFER_CPUS is a CPU bit mask specifying the CPUs that are allowed to
serve as preferred CPUs and thus can be assigned a Fast Path port. CPUs whose
bit is set in the IO_PREFER_CPUS bit mask are enabled for Fast Path port
assignment. IO_PREFER_CPUS defaults to -1, which specifies that all CPUs are
allowed to be assigned Fast Path ports.
You may want to disable the primary CPU from serving as a preferred CPU by
clearing its bit in IO_PREFER_CPUS. This will reserve the primary for use by
non-Fast Path IO operations.
Changing the value of IO_PREFER_CPUS causes the FASTPATH_SERVER
process to execute the automatic assignment algorithm that spreads Fast Path
ports evenly among the new set of usable CPUs.
10.2.2.2 Identifying and Setting a Ports Preferred CPU
Following are the commands used to identify and set a preferred CPU for a port.
DCL SHOW DEVICE/FULL or $GETDVI DVI$_PREFERRED_CPU
To identify the preferred CPU for any Fast Path-capable device when Fast Path
is enabled, use the DCL command SHOW DEVICE/FULL to displaywhether or
not the device supports Fast Paththe current preferred CPU ID and, if set, the
User Preferred CPU ID for a port or disk device.
Alternatively, the $GETDVI system service or the DCL F$GETDVI lexical
function will return the preferred CPU for a given device or file. The $GETDVI
system service item code is DVI$_PREFERRED_CPU, and the F$GETDVI item
code string argument is PREFERRED_CPU. The return argument is a 32-bit
CPU bit mask with a bit set indicating the preferred CPU. A return argument
containing a bit mask of zero indicates that no preferred CPU exists, either
because Fast Path is disabled or the device is not a Fast Path-capable device. The

1010 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
return argument serves as a CPU bit mask input argument to the $PROCESS_
AFFINITY system service. The argument can be used to assign an application
process to the optimal preferred CPU.
For an application seeking optimal Fast Path benefits, you can code each
application process to identify and run on the preferred CPU where the majority
of the process I/O activity occurs.
A high-availability feature of OpenVMS Cluster Systems is that dual-pathed
devices automatically fail over to a secondary path, if the primary path becomes
inoperable. Because a Fast Path device could fail over to another path or port,
and thereby, to another preferred CPU, an application should occasionally reissue
the $GETDVI in a timer thread to check that process assignment is optimal.
DCL SHOW CPU /FULL
You can use this DCL command to identify whether a CPU is enabled for use as a
preferred CPU, and the current set of ports assigned to that CPU.
DCL SET /PREFERRED_CPU and /NOPREFERRED_CPU
These commands allow you to specify a CPU or a set of candidate CPUs from
which the operating system will choose the CPU to assign to the Fast Path port.
The chosen CPU is called the preferred CPU for this Fast Path port. The Fast
Path ports interrupt I/O completion processing and I/O initiation processing will
be performed on this preferred CPU.
In addition to selecting the preferred CPU, the User Preferred CPU will be set
for this port. Setting the User Preferred CPU prevents the port from being
reassigned to another CPU unless the User Preferred CPU is being stopped. The
qualifier can be negated. When the /NOPREFERRED_CPUS qualifier is specified,
the User Preferred CPU will be cleared for the port, but it still remains a Fast
Path port, and the current preferred CPU will not be changed.
If both /PREFERRED_CPUS and /NOPREFERRED_CPUS are specified on the
same command line, /NOPREFERRED_CPUS is ignored.
$QIO IO$_SETPRFPATH ! IO$M_PREFERRED_CPU [!IO$M_SYS_
ASSIGNABLE]
You can change the assignment of a Fast Path port to a CPU by issuing a $QIO
IO$_SETPRFPATH (Set Preferred Path) to the port device, for example, PNA0.
The IO$M_PREFERRED_CPU modifier must be set, and the $QIO argument
P1 must be set to either zero or the address of a 32-bit CPU bit mask with a bit
set indicating the new preferred CPU. On return from the I/O, the port and its
associated devices are all assigned to a new preferred CPU. Note that explicitly
setting the preferred CPU overrides any default assignment of Fast Path ports to
CPUs. This interface allows you the flexibility to load balance I/O activity over
multiple CPUs in an SMP system. This is important because I/O activity can
change over the course of a day or week.
The $QIO passes in either a set containing one or more candidate CPUs, or
zero as a wildcard value indicating the set of usable CPUs. If the candidate
set contains only one CPU, you are explicitly designating the new preferred
CPU. If the candidate set contains multiple CPUs, you are requesting use of the
automatic preferred CPU assignment algorithm to select a suitable CPU from the
candidate set.
Including the IO$M_SYS_ASSIGNABLE modifier inhibits setting the selected
CPU as the devices User Preferred CPU.

Optional Features for Improving I/O Performance 1011

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
The $QIO or the SET DEVICE/PREFERRED_CPU command will make a best
effort to assign the port to a CPU. However, it is possible for this request to
return failure for the following reasons:

There is no intersection between the candidate set and the nodes set of usable
CPUs.

There is resource contention. If after a reasonable effort the request is unable

to acquire a key system resource, the request will fail. Some key resources
include Fast Path spinlock, the CPU mutex, and a CPU transition lock.

If the $QIO or SET DEVICE/PREFERRED_CPU returns failure, you should

consider retrying either immediately or after a short delay. It is possible that
a large number of ports were being reassigned, and the request failed due to
resource contention.
$IO_FASTPATH
The $IO_FASTPATH system service performs operations on the set of Fast
Path devices and CPUs enabled for Fast Path use. The $IO_FASTPATHW
system service completes synchronously. That is, it returns after the operation is
complete.
The FP$K_BALANCE_PORTS function code specifies that the system service is
to distribute the set of system assignable Fast Path ports across the intersection
of a caller-supplied set of candidate CPUs.

10.2.3 Fast Path Restrictions

Fast Path restrictions include the following:

Only high-volume I/Os are optimized.

Fast Path streamlines the operation of high-volume I/O. I/O that does not
meet the definition of high-volume is not optimized.
A high-volume Fast Path I/O is a read or write operation to a Fast Path device
without special I/O modifiers issued at a time when necessary resources have
been pre-allocated and there are no circumstances restricting I/O operations.

Send credits resource must be managed for DSA controllers.

Applications seeking maximum performance must ensure the availability of
sufficient I/O resources.
The only I/O resource that a Fast Path user needs to be concerned about is
send credits. Send credits are extended by DSA controllers to host systems
and represent the maximum number of I/Os that can be outstanding at
any given point in time. If an application sends an unlimited number of
simultaneous I/Os to a controller, it is likely that some I/O will back up
waiting for send credits.
You can tell whether the send-credit limit is being exceeded by using the
DCL command SHOW CLUSTER/CONTINUOUS, followed by an ADD
CONNECTIONS, CR_WAIT command. Rapidly increasing credit-wait
counts for the disk-class driver connections (a LOC_PROC_NAME name
of VMS$DISK_CL_DRVR) is a sign that an application may be incurring
send-credit waits.
To ensure sufficient send credits, some controllers, like the HSC and HSJ,
allow the number of send credits to vary; however, not all controllers have
this flexibility, and different controllers have different send-credit limits. The

1012 Optional Features for Improving I/O Performance

Optional Features for Improving I/O Performance

10.2 Fast Path (Alpha Only)
best workaround is to know your application access patterns and look for send
credit waits.
If the number of send credits is being exhausted on one node, then add
another controller to spread the load over multiple controllers. An alternative
is to rework the application to load balance controller activity throughout
the cluster, spreading a given controllers disk load over multiple nodes and
allowing an application to exceed the send credits allotted to one node.

10.2.4 Special Considerations for Fast Path on Multi-RAD Systems

On systems supporting multiple resource affinity domains (RADs), the best
performance for Fast Path ports is usually obtained by setting the Fast Path
preferred CPU assignment to a CPU within the same RAD as the port.
The FASTPATH_SERVER restricts its distribution of ports accordingly whenever
possible. If a port should be within a RAD without available Fast Path CPUs, the
system will set the preferred CPU to the primary CPU.
Because you can override this assignment by the methods described in
this chapter, care should be taken that reassignment does not sacrifice the
performance improvements provided by localizing activity to a single RAD.

Optional Features for Improving I/O Performance 1013

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.

A.1 ACP-QIO Interface Driver

This section lists the function codes and function modifiers for the ACP-QIO
interface driver.
Functions

Arguments

Modifiers

IO$_CREATE
IO$_ACCESS
IO$_DEACCESS
IO$_MODIFY
IO$_DELETE
IO$_ACPCONTROL

P1FIB descriptor
address
P2file name string
address
P3result string length
address
P4result string
descriptor address
P5attribute list
address

IO$M_CREATE1
IO$M_ACCESS1
IO$M_DELETE2
IO$M_DMOUNT3

IO$_MOUNT

None

None

1 Only

for IO$_CREATE and IO$_ACCESS

2 Only

for IO$_CREATE and IO$_DELETE

3 Only

for IO$_ACPCONTROL

QIO Status Returns

SS$_ACCONFLICT

SS$_ACPVAFUL

SS$_BADATTRIB

SS$_BADCHKSUM

SS$_BADFILEHDR

SS$_BADFILENAME

SS$_BADFILEVER

SS$_BADIRECTORY

SS$_BADPARAM

SS$_BADQFILE

SS$_BLOCKCNTERR

SS$_CREATED

SS$_DEVICEFULL

SS$_DIRFULL

SS$_DIRNOTEMPTY

SS$_DUPDSKQUOTA

SS$_DUPFILENAME

SS$_ENDOFFILE

SS$_EXBYTLM

SS$_EXDISKQUOTA

SS$_FCPREADERR

SS$_FCPREWNDERR

SS$_FCPSPACERR

SS$_FCPWRITERR

SS$_FILELOCKED

SS$_FILENUMCHK

SS$_FILEPURGED

SS$_FILESEQCHK

SS$_FILESTRUCT

SS$_FILNOTEXP

SS$_HEADERFULL

SS$_IBCERROR

SS$_ILLCNTRFUNC

SS$_NODISKQUOTA

1 The

SS$_IDXFILEFULL
SS$_NOMOREFILES

second longword of the IOSB contains a job controller status code.

I/O Function Codes A1

I/O Function Codes

A.1 ACP-QIO Interface Driver
QIO Status Returns
SS$_NOPRIV

SS$_NOQFILE

SS$_NOSUCHFILE

SS$_NOTAPEOP

SS$_NOTLABELMT

SS$_NOTPRINTED1

SS$_NOTVOLSET

SS$_OVRDSKQUOTA

SS$_QFACTIVE

SS$_QFNOTACT

SS$_SERIOUSEXCP

SS$_SUPERSEDE

SS$_TAPEPOSLOST

SS$_TOOMANYVER

SS$_WRITLCK

SS$_WRONGACP
1 The

second longword of the IOSB contains a job controller status code.

A.2 Disk Drivers

This section lists the function codes and function modifiers for the disk drivers.
Functions

Arguments

Modifiers

IO$_READVBLK
IO$_READLBLK
IO$_READPBLK4
IO$_WRITEVBLK
IO$_WRITELBLK
IO$_WRITEPBLK4

P1buffer address
P2byte count
P3disk address

IO$M_INHSEEK1
IO$M_DATACHECK2
IO$M_DELDATA3
IO$M_INHRETRY
IO$M_ERASE5

IO$_WRITECHECK2

P1buffer address
P2byte count
P3disk address

None

IO$_SENSECHAR
IO$_SENSEMODE
IO$_PACKACK
IO$_AVAILABLE
IO$_UNLOAD

None

None

IO$_SEARCH

P1read/write
head position

None

IO$_SEEK4

P1seek to
specified
cylinder

None

IO$_FORMAT

P1RX02 density

None

IO$_SETPRFPATH

P1node or HSx name

IO$_FORCEPATH

1 Only

for IO$READPBLK and IO$_WRITEPBLK (not for TU58, RX01, RX02, RB02, or RL02)

2 Not

for RX01 and RX02

3 Only for IO$_WRITEPBLK on RX02
4 Not

for DSA disks

for write functions

5 Only

A2 I/O Function Codes

I/O Function Codes

A.2 Disk Drivers
Functions

Arguments

Modifiers

IO$_CREATE
IO$_ACCESS
IO$_DEACCESS
IO$_MODIFY
IO$_DELETE
IO$_ACPCONTROL

P1FIB descriptor
address
P2file name string
address
P3result string
length address
P4result string
descriptor
address
P5attribute list
address

IO$M_CREATE6
IO$M_ACCESS6
IO$M_DELETE7
IO$M_DMOUNT8

6 Only

for IO$_CREATE and IO$_ACCESS

7 Only

for IO$_CREATE and IO$_DELETE

8 Only

for IO$_ACPCONTROL

QIO Status Returns

SS$_ABORT

SS$_CANCEL

SS$_CTRLERR

SS$_DATACHECK

SS$_DATAOVERUN

SS$_DRVERR

SS$_FORCEDERR

SS$_FORMAT

SS$_ILLIOFUNC

SS$_IVADDR

SS$_IVBUFLEN

SS$_MEDOFL

SS$_NONEXDRV

SS$_NORMAL

SS$_OPINCOMPL

SS$_PARITY

SS$_RCT

SS$_RDDELDATA

SS$_TIMEOUT

SS$_UNSAFE

SS$_VOLINV

SS$_WASECC

SS$_WRITLCK

A.3 Magnetic Tape Drivers

This section lists the function codes and function modifiers for the magnetic tape
drivers.
Functions

Arguments

Modifiers

IO$_READVBLK
IO$_READLBLK
IO$_READPBLK

P1buffer address
P2byte count

IO$M_DATACHECK1
IO$M_INHRETRY
IO$M_REVERSE3

IO$_WRITEVBLK
IO$_WRITELBLK
IO$_WRITEPBLK

P1buffer address
P2byte count

IO$M_DATACHECK1
IO$M_INHRETRY
IO$M_INHEXTGAP2
IO$M_NOWAIT8
IO$M_ERASE7

IO$_SETMODE
IO$_SETCHAR

P1characteristics buffer
address
P2characteristics buffer
length9

1 Not

for TS04 and TU80

for TE16, TU45, and TU77

2 Only
3 Not

for TK50

7 IO$M_ERASE

takes no arguments; only for IO$_WRITELBLK and IO$_WRITEPBLK on TMSCP

drives.
8 Only for TU81-Plus drives
9 Only

for TMSCP drives

I/O Function Codes A3

I/O Function Codes

A.3 Magnetic Tape Drivers
Functions

Arguments

Modifiers

IO$_CREATE
IO$_ACCESS
IO$_DEACCESS
IO$_MODIFY
IO$_ACPCONTROL

P1FIB descriptor
address
P2file name string
address
P3result string length
address
P4result string
descriptor address
P5attribute list address

IO$M_CREATE4
IO$M_ACCESS4
IO$M_DMOUNT5

IO$_SKIPFILE

P1skip n tape marks

IO$M_ALLOWFAST10
IO$M_INHRETRY
IO$M_NOWAIT8

IO$_SKIPRECORD

P1skip n blocks

IO$M_INHRETRY
IO$M_NOWAIT8

IO$_REWIND
IO$_REWINDOFF
IO$_UNLOAD

None

IO$M_INHRETRY
IO$M_NOWAIT
IO$M_RETENSION

IO$_WRITEOF

None

IO$M_INHEXTGAP2
IO$M_INHRETRY
IO$M_NOWAIT8

IO$_SENSEMODE
IO$_SENSECHAR

P1characteristics
buffer address9
P2characteristics
buffer length9

IO$M_INHRETRY

IO$_DSE6
IO$_PACKACK
IO$_AVAILABLE

None

None

2 Only

for TE16, TU45, and TU77

4 Only

for IO$_CREATE and IO$_ACCESS

5 Only

for IO$_ACPCONTROL

6 Only

for TU78, TU81, TA81, and TA78

8 Only

for TU81-Plus drives

9 Only

for TMSCP drives

10 Only

for local SCSI drives

QIO Status Returns

SS$_ABORT

SS$_CANCEL

SS$_CTRLERR

SS$_DATACHECK

SS$_DATAOVERUN

SS$_DEVOFFLINE

SS$_DRVERR

SS$_ENDOFFILE

SS$_ENDOFTAPE

SS$_ENDOFVOLUME

SS$_FORMAT

SS$_ILLIOFUNC

SS$_MEDOFL

SS$_NONEXDRV

SS$_NORMAL

SS$_OPINCOMPL

SS$_PARITY

SS$_SERIOUSEXCP

SS$_TIMEOUT

SS$_UNSAFE

SS$_VOLINV

SS$_WRITLCK

A4 I/O Function Codes

I/O Function Codes

A.4 Mailbox Driver

A.4 Mailbox Driver

This section lists the function codes and function modifiers for the mailbox
driver.
Functions

Arguments

Modifiers

IO$_READVBLK
IO$_READLBLK
IO$_READPBLK
IO$_WRITEVBLK
IO$_WRITELBLK
IO$_WRITEPBLK

P1buffer
address
P2buffer size

IO$M_NOW
IO$M_NORSWAIT1
IO$M_
READERCHECK1
IO$M_
WRITERCHECK2
IO$M_STREAM2

IO$_WRITEOF

None

IO$M_NOW
IO$M_
READERCHECK
IO$M_STREAM

IO$_SETMODE!IO$M_READATTN
IO$_SETMODE!IO$M_WRTATTN
IO$_SETMODE!IO$MB_ROOM_
NOTIFY

P1AST address
P2AST parameter
P3access mode

None

IO$_SETMODE!IO$M_
READERWAIT
IO$_SETMODE!IO$M_
WRITERWAIT

None

None

IO$_SETMODE!IO$M_SETPROT

P2volume
protection
mask

None

IO$_SENSEMODE!IO$M_
READERCHECK
IO$_SENSEMODE!IO$M_
WRITERCHECK

None

None

1 Only

for write functions

2 Only

for read functions

VAX specific

QIO Status Returns in R0

SS$_ACCVIO

SS$_EXQUOTA

SS$_ILLIOFUNC

SS$INSFMEM

SS$MBFULL

SS$_MBTOOSML

SS$_NOPRIV

SS$_NORMAL

SS$_ENDOFFILE

IOSB Status Returns

SS$_ABORT

SS$_BUFFEROVF

SS$_CANCEL

SS$_
NOREADER

SS$_NORMAL

SS$_NOWRITER

I/O Function Codes A5

I/O Function Codes

A.5 Terminal Driver

A.5 Terminal Driver

This section lists the function codes and function modifiers for the terminal
driver.
Functions

Arguments

Modifiers

IO$_READVBLK
IO$_READLBLK
IO$_READPROMPT

P1buffer address
P2buffer size
P3timeout
P4read terminator
block address
P5prompt string
buffer address
P6prompt string
buffer size1

IO$M_NOECHO
IO$M_CVTLOW
IO$M_NOFILTR
IO$M_TIMED
IO$M_PURGE
IO$M_DSABLMBX
IO$M_TRMNOECHO
IO$M_ESCAPE

IO$_READVBLK

P1buffer address
P2buffer size
P3access mode to
probe itemlist
P4(zero)
P5itemlist buffer
address
P6itemlist buffer
size

IO$M_EXTEND2

IO$_WRITEVBLK
IO$_WRITELBLK
IO$_WRITEPBLK

P1buffer address
P2buffer size
P3(ignored)
P4carriage control
specifier3

IO$M_CANCTRLO
IO$M_ENABLMBX
IO$M_NOFORMAT
IO$M_REFRESH
IO$M_BREAKTHRU

IO$_SETMODE
IO$_SETCHAR

P1characteristics
buffer address
P2characteristics
buffer size
P3speed specifier
P4fill specifier
P5parity flags

IO$_SETMODE
IO$_SETCHAR

None

IO$M_HANGUP

IO$_SETMODE

P1buffer address
P2buffer size

IO$M_BRDCST

IO$_SETMODE
IO$_SETCHAR

P1AST service
routine address
P2AST parameter
P3access mode to
deliver AST

IO$M_CTRLCAST
IO$M_CTRLYAST

IO$_SETMODE
IO$_SETCHAR

P1AST service
routine address
P2character mask
address
P3access mode to
deliver AST

IO$M_OUTBAND
IO$M_TT_ABORT4
IO$M_INCLUDE4

1 Only

for IO$_READPROMPT

2 Only

for itemlist read function. Do not specify with other modifiers.

3 Only

for IO$_WRITELBLK and IO$_WRITEVBLK

4 Only

with IO$M_OUTBAND

A6 I/O Function Codes

I/O Function Codes

A.5 Terminal Driver
Functions

Arguments

Modifiers

IO$_SETMODE
IO$_SETCHAR

P1address of
control signals

IO$M_SET_MODEM5
IO$M_MAINT

IO$_SETMODE
IO$_SETCHAR

None

IO$M_LOOP5
IO$M_UNLOOP5
IO$M_MAINT

IO$_TTY_PORT

IO$M_LT_CONNECT
IO$M_LT_DISCON

IO$_TTY_PORT

P1itemlist6
address
P2queued status

IO$M_LT_MAP_PORT

IO$_TTY_PORT

P1service name
descriptor
address
P2service rating

IO$M_LT_RATING

IO$_TTY_PORT

P1itemlist
address
P2itemlist
length
P3entity type
P4entity string
descriptor

IO$M_LT_SENSEMODE

IO$_TTY_PORT

P1itemlist
address
P2itemlist
length
P3entity type
P4entity string
descriptor

IO$M_LT_SETMODE

IO$_SENSEMODE
IO$_SENSECHAR

P1characteristics
buffer address
P2characteristics
buffer size

IO$M_TYPEAHDCNT

IO$_SENSEMODE
IO$_SENSECHAR

P1address of input
modem signal
block

IO$M_RD_MODEM

IO$_SENSEMODE

P1buffer address
P2buffer size

IO$M_BRDCST

5 Only

with IO$M_MAINT

6 Itemlist:

IO$V_LT_MAP_NODNAM, IO$V_LT_MAP_PORNAM, IO$V_LT_MAP_SRVNAM, IO$V_

LT_MAP_LNKNAM, and IO$V_LT_MAP_NETADR.

QIO Status Returns

SS$_ABORT

SS$_BADESCAPE

SS$_BADPARAM

SS$_CANCEL

SS$_CHANINTLK

SS$_CONTROLC

SS$_CONTROLO

SS$_CONTROLY

SS$_DATAOVERUN

SS$_INCOMPAT

SS$_NORMAL

SS$_PARITY

SS$_PARTESCAPE

SS$_TIMEOUT

I/O Function Codes A7

I/O Function Codes

A.6 Local Area Network Device Drivers

A.6 Local Area Network Device Drivers

This section lists the function codes and function modifiers for the local area
network drivers.
Functions

Arguments

Modifiers

IO$_READLBLK
IO$_READVBLK
IO$_READPBLK
IO$_WRITELBLK
IO$_WRITEVBLK
IO$_WRITEPBLK

P1buffer address
P2buffer size
P4802 format fields (optional)3
P5destination address (optional)3

IO$M_NOW1
IO$M_RESPONSE2

IO$_SETMODE
IO$_SETCHAR

P2extended characteristics buffer

(optional)4

IO$M_CTRL
IO$M_STARTUP
IO$M_SHUTDOWN

IO$_SETMODE
IO$_SETCHAR

P1AST service address

P3 access mode to deliver AST

IO$M_ATTNAST

IO$_SENSEMODE
IO$_SENSECHAR

P1device characteristics buffer

(optional)
P2extended characteristics buffer
(optional)

IO$M_CTRL

1 Only

for read functions

2 Only

for write functions

3 See

text for complete contents

4 Use

only with IO$M_CTRL alone or with IO$_STARTUP, that is, the set controller mode

QIO Status Returns

SS$_ABORT

SS$_ACCVIO

SS$_BADPARAM

SS$_BUFFEROVF

SS$_COMMHARD

SS$_CTRLERR

SS$_DATACHECK

SS$_DATAOVERUN

SS$_DEVACTIVE

SS$_DEVALLOC

SS$_DEVINACT

SS$_DEVOFFLINE

SS$_DEVREQERR

SS$_DISCONNECT

SS$_DUPUNIT

SS$_ENDOFFILE

SS$_EXQUOTA

SS$_INSFMEM

SS$_INSFMAPREG

SS$_IVBUFLEN

SS$_MEDOFL

SS$_NOPRIV

SS$_NORMAL

SS$_OPINCOMPL

SS$_TIMEOUT

SS$_TOOMUCHDATA

A.7 Fast I/O Function Codes and Modifiers

This section lists the function codes and parameters for the $IO_SETUP system
service.

A8 I/O Function Codes

I/O Function Codes

A.7 Fast I/O Function Codes and Modifiers
Functions

Arguments

IO$_READVBLK
IO$_READLBLK
IO$_WRITEVBLK
IO$_WRITELBLK

bufobj - users buffer

iosobjI/O Status Area (IOSA)
astadrCompletion AST routine
flagslongword mask
return_fandlefandle address

A.8 Fast Path Function Codes and Modifiers

This section lists the function codes and function modifiers for Fast Path.
Functions

Arguments

Modifiers

IO$_SETPRFPATH

P1CPU mask
None

IO$M_PREFERRED_CPU
IO$M_SYS_ASSIGNABLE

I/O Function Codes A9

B
IO$_DIAGNOSE Function for SCSI Class
Drivers
As of OpenVMS Version 7.0, the $QIO IO$_DIAGNOSE function has been
enhanced to support 64-bit addressing for the following SCSI class drivers:
GKDRIVER, DKDRIVER, and MKDRIVER. This means that the virtual
addresses specified within the S2DGB may now be 64-bit virtual addresses if the
user application requests it.
The $QIO IO$_DIAGNOSE arguments are still as follows:
Argument

Use

P1

S2DGB base address

P2

S2DGB length

P3

Reserved, should be zero

P4

Reserved, should be zero

P5

Reserved, should be zero

P6

Reserved, should be zero

The SCSI Diagnose Buffer (S2DGB) defined in STARLET now allows two formats,
one for 32-bit addressing and one for 64-bit addressing. The 32-bit format is
identical to the one supported on OpenVMS Alpha Version 6.2.
Figure B1 shows the 32-bit S2DGB format. Figure B2 shows the 64-bit S2DGB
format.

IO$_DIAGNOSE Function for SCSI Class Drivers B1

IO$_DIAGNOSE Function for SCSI Class Drivers

Figure B1 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-Bit Layout

S2DGB$L_OPCODE

:00

S2DGB$L_FLAGS

:04

S2DGB$L_32CDBADDR

:08

S2DGB$L_32CDBLEN

:0C

S2DGB$L_32DATADDR

:10

S2DGB$L_32DATLEN

:14

S2DGB$L_32PADCNT

:18

S2DGB$L_32PHSTMO

:1C

S2DGB$L_32DSCTMO

:20

S2DGB$L_32SENSEADDR

:24

S2DGB$L_32SENSELEN

:28
:2C

Reserved

:30

Should Be Zero

:34
:38

ZK8486AGE

B2 IO$_DIAGNOSE Function for SCSI Class Drivers

IO$_DIAGNOSE Function for SCSI Class Drivers

Figure B2 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-Bit Layout

S2DGB$L_OPCODE

:00

S2DGB$L_FLAGS

:04

S2DGB$PQ_64CDBADDR

:08

S2DGB$PQ_64DATADDR

:10

S2DGB$PQ_64SENSEADDR

:18

S2DGB$L_64CDBLEN

:20

S2DGB$L_64DATLEN

:24

S2DGB$L_64SENSELEN

:28

S2DGB$L_64PADCNT

:2C

S2DGB$L_64PHSTMO

:30

S2DGB$L_64DSCTMO

:34

Reserved. Should be Zero

:38

ZK8487AGE

A user application must specify which one of the two S2DGB formats is
to be used by passing a format value in S2DGB$L_OPCODE. Specifically,
S2DGB$L_OPCODE must be assigned a value of either OP_XCDB32 (= 1) to
request 32-bit format, or OP_XCDB64 (= 2) to request 64-bit format. Once the
value of OP_XCDB64 has been specified, the user application is obligated to use
the 64-bit S2DGB format and, in particular, to use the 64-bit names for S2DGB
fields as described below. Likewise, an opcode value of OP_XCDB32 obligates the
user application to use the 32-bit names for the fields.
The correct length of the structure is defined by the constant S2DGB$K_
XCDB32_LENGTH (value: 60-decimal), as well as by the constant S2DGB$K_
XCDB64_LENGTH (value: 60-decimal).
The fields in the S2DGB are in the sections that follow. Whenever a field has two
different names for the 32-bit and 64-bit cases, the 32-bit name is given first,
and the 64-bit name is given after it in parentheses. Also, except for fields that
contain addresses, all fields are unsigned longwords.
S2DGB$L_OPCODE
This field should contain either S2DGB$K_OP_XCDB32 or S2DGB$K_OP_
XCDB64, depending on whether the user application intends to supply 32-bit
virtual addresses or 64-bit virtual addresses, respectively, in the other fields of
the S2DGB.
IO$_DIAGNOSE Function for SCSI Class Drivers B3

IO$_DIAGNOSE Function for SCSI Class Drivers

S2DGB$L_FLAGS
This field should contain the bit fields shown in the following table. Note
that these bit definitions start at bit 0 and omit no bits. This is required for
compatibility with the IO$_DIAGNOSE interface available in OpenVMS Alpha
Version 6.1 and earlier.
Table B1 S2DGB$L_FLAGS Bit Fields
Bit Field

Description

S2DGB$V_READ

This bit should be 1 if the operation being performed is a read. If the

operation is a write, this bit should be 0.

S2DGB$V_DISCPRIV

This bit should contain the DiscPriv bit value to be used in the IDENTIFY
message sent with this operation. If S2DGB$V_TAGGED_REQ is 1, then
this bit is ignored. Note that S2DGB$V_DISCPRIV may be ignored by
some ports unconditionally.

S2DGB$V_SYNCHRONOUS

This bit is ignored because its value is beyond the control of the user in
SCSI-2 drivers.

S2DGB$V_OBSOLETE1

This bit is ignored. In previous releases, it represented the disabling of

command retries, which is now beyond the control of the user in SCSI-2
drivers.

S2DGB$V_TAGGED_REQ

When this bit is 1, the operation is processed as using tagged command

queuing and S2DGB$V_TAG should define the tag value to be used. When
this bit is 0, the operation is processed without benefit of tagged command
queuing.
Note that although some ports do not support tagged command queuing,
setting this bit to 1 will inhibit changing the values of S2DGB$L_
32PADCNT (S2DGB$L_64PADCNT), S2DGB$L_32DSCTMO (S2DGB$L_
64DSCTMO), and S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO), and
will cause S2DGB$V_DISCPRIV to be ignored. Note also that some ports
simulate untagged operations using appropriately tagged operations. If
S2DGB$V_TAGGED_REQ is 1, then this 3-bit field should contain one of
the following coded constant values:
S2DGB$K_SIMPLE indicates that the command is to be sent with the
SIMPLE queue tag.
S2DGB$K_ORDERED indicates that the command is to be sent with
the ORDERED queue tag.
S2DGB$K_EXPRESS indicates that the command is to be sent with
the HEAD OF QUEUE queue tag.
If S2DGB$V_TAGGED_REQ is 0, then this field is ignored. Ports that
do not support tagged command queuing always ignore the S2DGB$V_
TAG field and send all commands as untagged operations.
Note that automatic contingent allegiance processing is not accessible
through the IO$_DIAGNOSE function. Also, even though this is a
3-bit field, only 2 bits are currently being utilized. That is, the 3
constants above represent values, not bit positions.
(continued on next page)

B4 IO$_DIAGNOSE Function for SCSI Class Drivers

IO$_DIAGNOSE Function for SCSI Class Drivers

Table B1 (Cont.) S2DGB$L_FLAGS Bit Fields

Bit Field

Description

S2DGB$V_AUTOSENSE

When this bit is 1, S2DGB$L_32SENSEADDR and S2DGB$L_

32SENSELEN should contain a valid sense buffer address and length.
If a CHECK CONDITION or COMMAND TERMINATED status is
returned, REQUEST SENSE data will be returned in the buffer defined by
S2DGB$L_32SENSEADDR and S2DGB$L_32SENSELEN.
When S2DGB$V_AUTOSENSE is 0, the buffer described by S2DGB$L_
32SENSEADDR and S2DGB$L_32SENSELEN is ignored. In such cases,
the class driver saves the autosense data in pool and returns it to the next
IO$_DIAGNOSE, if and only if that IO$_DIAGNOSE has a REQUEST
SENSE CDB.
All other bits in S2DGB$L_FLAGS should be zero.

S2DGB$L_32CDBADDR (S2DGB$PQ_64CDBADDR)
This field should contain the 32-bit (or 64-bit) virtual address of the SCSI
command data block (CDB) to be sent to the target by this IO$_DIAGNOSE
operation.
Note that S2DGB$L_32CDBADDR is a pointer to a longword, while S2DGB$PQ_
64CDBADDR is a pointer to a quadword.
S2DGB$L_32CDBLEN (S2DGB$L_64CDBLEN)
This field should contain the number of bytes in the SCSI command data block
(CDB) to be sent to the target by this IO$_DIAGNOSE operation. (Legal
values: 2 to 248; however, some ports may restrict CDBs to smaller lengths.
Recommended values: 2 to 16.)
S2DGB$L_32DATADDR (S2DGB$PQ_64DATADDR)
This field should contain the 32-bit (or 64-bit) virtual address of the DATAIN or
DATAOUT buffer to be used with this SCSI operation. If the CDB being sent to
the target does not use a DATAIN or DATAOUT buffer, then this field should be
zero.
Note that S2DGB$L_32DATADDR is a pointer to a longword, while S2DGB$PQ_
64DATADDR is a pointer to a quadword.
S2DGB$L_32DATLEN (S2DGB$L_64DATLEN)
This field should contain the number of bytes in the DATAIN or DATAOUT buffer
associated with this operation. If the CDB being sent to the target does not use a
DATAIN or DATAOUT buffer, then this field should be zero. (Legal values: 0 to
UCB$L_MAXBCNT. Recommended values: 0 to 65,536. All ports are required to
support at least 65,536 byte data transfers.)
S2DGB$L_32PADCNT (S2DGB$L_64PADCNT)
This field should contain the number of padding DATAIN or DATAOUT bytes
required by this operation. If S2DGB$V_TAGGED_REQ is 1, then the PAD count
value will not be its default value. (Legal values: 0 to the maximum number of
bytes in a disk block on this system minus one. Current legal values: 0 to 511.)
S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO)
This field should contain the number of seconds that the port driver should
wait for a phase transition to occur or for delivery of an expected interrupt. If
S2DGB$V_ TAGGED_REQ is 1 or this field contains a 0 or 1, then the current
phase transition timeout setting will not be changed. (Legal values: 0 to 65,535
[about 18 hours].)
IO$_DIAGNOSE Function for SCSI Class Drivers B5

IO$_DIAGNOSE Function for SCSI Class Drivers

S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO)
This field should contain the number of seconds that the port driver should wait
for a disconnected transaction to reconnect. If S2DGB$V_TAGGED_REQ is 1 or
this field contains a 0 or 1, then the current disconnect timeout setting will not be
changed. (Legal values: 0 to 65,535 [about 18 hours].)
S2DGB$L_32SENSEADDR (S2DGB$PQ_64SENSEADDR)
If S2DGB$V_AUTOSENSE is 1, then this field should contain the 32-bit (or
64-bit) virtual address of the sense buffer to be used by this SCSI operation. If
S2DGB$V_AUTOSENSE is 0, this field will be ignored.
Note that S2DGB$L_32SENSEADDR is a pointer to a longword, while
S2DGB$PQ_64SENSEADDR is a pointer to a quadword.
S2DGB$L_32SENSELEN (S2DGB$L_64SENSELEN)
If S2DGB$V_AUTOSENSE is 1, then this field should contain the number of
bytes in the sense buffer associated with this operation. (Legal values: 0 to
255. Note that a value of 0 instructs the class driver to discard any sense data
received. Recommended value: 18. Some ports may restrict the number of sense
bytes to 18.) If S2DGB$V_AUTOSENSE is 0, this field will be ignored.
The following example shows how to set up a 64-bit S2DGB:
#include <s2dgbdef.h>
#include <far_pointers.h>

/* Define S2DGB */
/* Define VOID_PQ */

S2DGB diag_desc;
/* Set up some default S2DGB descriptor values */
diag_desc.s2dgb$l_opcode = OP_XCDB64
/* Use 64-bits */
diag_desc.s2dgb$l_flags = (S2DGB$M_READ |
/* Flags*/
S2DGB$M_TAGGED_REQ |
S2DGB$M_AUTOSENSE);
diag_desc.s2dgb$v_tag = S2DGB$K_SIMPLE;
/* SIMPLE que tag */
diag_desc.s2dgb$pq_64cdbaddr = (VOID_PQ)(&cdb[0]);/* Command addr */
diag_desc.s2dgb$l_64cdblen = 6;
/* Command length */
diag_desc.s2dgb$pq_64dataddr = (VOID_PQ)(&buf[0]);/* Data addr
*/
diag_desc.s2dgb$l_64datlen = 20;
/* Data length
*/
diag_desc.s2dgb$l_64padcnt = 0;
/* Pad length
*/
diag_desc.s2dgb$l_64phstmo = 20;
/* Phase timeout */
diag_desc.s2dgb$l_64dsctmo = 10;
/* Disc timeout */
diag_desc.s2dgb$pq_64senseaddr = (VOID_PQ)(&asn[0]);/* Autosense addr */
diag_desc.s2dgb$l_64senselen = 255;
/* Sense length */
diag_desc.s2dgb$l_reserved_1 = 0;
/* Reserved
*/
.
.
.
status = sys$qiow(0, target_chan, IO$_DIAGNOSE, &iosb, 0, 0,
&diag_desc, S2DGB$K_XCDB64_LENGTH, 0, 0, 0, 0);
If all arguments are valid, the class driver will invoke the necessary port
functions to send the CDB, transfer the data, and return, save or discard sense
data as defined by the input S2DGB. Upon completion, the return IOSB will have
the following format:
Byte count <15:0>
SCSI status

Zero

Port VMS status

:00

Byte count <31:16>

:04
ZK8488AGE

B6 IO$_DIAGNOSE Function for SCSI Class Drivers

IO$_DIAGNOSE Function for SCSI Class Drivers

The DKDRIVER, GKDRIVER, and MKDRIVER class drivers, which implement

other QIO functions, might intermix other tagged requests with IO$_DIAGNOSE
requests. The order in which requests are sent generally matches the order in
which requests are presented to the driver. An exception to this ordering occurs
when the driver receives REQUEST SENSE for which autosense data previously
has been recovered and stored. In this case, the IO$_DIAGNOSE will complete
immediately and no command will be sent to the target.
The DKDRIVER, GKDRIVER, and MKDRIVER class drivers permit only one
IO$_DIAGNOSE operation to be active (in the start I/O routine) at a given time,
except as described in the next paragraph. However, applications must single
thread IO$_DIAGNOSE requests to properly detect the presence of sense data
and send the required REQUEST SENSE command. This is consistent with the
VAX IO$_DIAGNOSE behavior. For example, if three reads are issued with no
waiting and the first read gets a CHECK CONDITION, the sense data will be
discarded by the target when the second read arrives.
The DKDRIVER, GKDRIVER, and MKDRIVER drivers permit more than one
IO$_DIAGNOSE operation to be active (in the start I/O routine) only when
all active operations have the S2DGB$V_AUTOSENSE flag equal to 1. Upon
encountering the first IO$_DIAGNOSE with S2DGB$V_AUTOSENSE equal to 0,
the class driver will apply the restrictions described in the previous paragraph.

IO$_DIAGNOSE Function for SCSI Class Drivers B7

C
Tables
This appendix includes tables for the DEC Multinational character set and for
terminal escape sequences and modes.

C.1 DEC Multinational Character Set

Table C1 lists the DEC Multinational character set. The DEC Multinational
character set is an 8-bit character set with 256 characters. The first 128
characters in the set correspond to the ASCII character set. The VAX EDT
Reference Manual lists the graphics for these characters and describes how to
enter them from various types of terminals.
Table C1 DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

Description

ASCII Control Characters1

00

000

000

NUL

null character

01

001

001

SOH

start of heading (Ctrl/A)

02

002

002

STX

start of text (Ctrl/B)

03

003

003

ETX

end of text (Ctrl/C)

04

004

004

EOT

end of transmission (Ctrl/D)

05

005

005

ENQ

enquiry (Ctrl/E)

06

006

006

ACK

acknowledge (Ctrl/F)

07

007

007

BEL

bell (Ctrl/G)

08

010

008

BS

backspace (Ctrl/H)

09

011

009

HT

horizontal tabulation (Ctrl/I)

0A

012

010

LF

line feed (Ctrl/J)

0B

013

011

VT

vertical tabulation (Ctrl/K)

0C

014

012

FF

form feed (Ctrl/L)

0D

015

013

CR

carriage return (Ctrl/M)

0E

016

014

SO

shift out (Ctrl/N)

0F

017

015

SI

shift in (Ctrl/O)

10

020

016

DLE

data link escape (Ctrl/P)

11

021

017

DC1

device control 1 (Ctrl/Q)

12

022

018

DC2

device control 2 (Ctrl/R)

1 The

ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control characters.

(continued on next page)

Tables C1

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

Description

ASCII Control Characters1

13

023

019

DC3

device control 3 (Ctrl/S)

14

024

020

DC4

device control 4 (Ctrl/T)

15

025

021

NAK

negative acknowledge (Ctrl/U)

16

026

022

SYN

synchronous idle (Ctrl/V)

17

027

023

ETB

end of transmission block

(Ctrl/W)

18

030

024

CAN

cancel (Ctrl/X)

19

031

025

EM

end of medium (Ctrl/Y)

1A

032

026

SUB

substitute (Ctrl/Z)

1B

033

027

ESC

escape

1C

034

028

FS

file separator

1D

035

029

GS

group separator

1E

036

030

RS

record separator

1F

037

031

US

unit separator

ASCII Special and Numeric Characters

20

040

032

SP

space

21

041

033

exclamation point

22

042

034

"

quotation marks (double quote)

23

043

035

number sign

24

044

036

dollar sign

25

045

037

percent sign

26

046

038

&

ampersand

27

047

039

apostrophe (single quote)

28

050

040

opening parenthesis

29

051

041

closing parenthesis

2A

052

042

asterisk

2B

053

043

plus

2C

054

044

comma

2D

055

045

hyphen or minus

2E

056

046

period or decimal point

2F

057

047

slash

30

060

048

zero

31

061

049

one

32

062

050

two

33

063

051

three

1 The

ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control characters.

(continued on next page)

C2 Tables

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Decimal
Code

Char or
Abbrev.

Hex Code

Octal Code

Description

34

064

052

four

35

065

053

five

36

066

054

six

37

067

055

seven

38

070

056

eight

39

071

057

nine

3A

072

058

colon

3B

073

059

semicolon

3C

074

060

<

less than

3D

075

061

equals

3E

076

062

>

greater than

3F

077

063

question mark

ASCII Special and Numeric Characters

ASCII Alphabetic Characters

40

100

064

commercial at sign

41

101

065

uppercase A

42

102

066

uppercase B

43

103

067

uppercase C

44

104

068

uppercase D

45

105

069

uppercase E

46

106

070

uppercase F

47

107

071

uppercase G

48

110

072

uppercase H

49

111

073

uppercase I

4A

112

074

uppercase J

4B

113

075

uppercase K

4C

114

076

uppercase L

4D

115

077

uppercase M

4E

116

078

uppercase N

4F

117

079

uppercase O

50

120

080

uppercase P

51

121

081

uppercase Q

52

122

082

uppercase R

53

123

083

uppercase S

54

124

084

uppercase T

55

125

085

uppercase U
(continued on next page)

Tables C3

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

56

126

086

uppercase V

57

127

087

uppercase W

58

130

088

uppercase X

59

131

089

uppercase Y

5A

132

090

uppercase Z

5B

133

091

left bracket

5C

134

092

backslash

5D

135

093

right bracket

5E

136

094

circumflex

5F

137

095

underscore

60

140

096

grave accent

61

141

097

lowercase a

62

142

098

lowercase b

63

143

099

lowercase c

64

144

100

lowercase d

65

145

101

lowercase e

66

146

102

lowercase f

67

147

103

lowercase g

68

150

104

lowercase h

69

151

105

lowercase i

6A

152

106

lowercase j

6B

153

107

lowercase k

6C

154

108

lowercase l

6D

155

109

lowercase m

6E

156

110

lowercase n

6F

157

111

lowercase o

70

160

112

lowercase p

71

161

113

lowercase q

72

162

114

lowercase r

73

163

115

lowercase s

74

164

116

lowercase t

75

165

117

lowercase u

76

166

118

lowercase v

77

167

119

lowercase w

78

170

120

lowercase x

79

171

121

lowercase y

Description

ASCII Alphabetic Characters

(continued on next page)

C4 Tables

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

7A

172

122

lowercase z

7B

173

123

left brace

7C

174

124

vertical line

7D

175

125

right brace (ALTMODE)

7E

176

126

tilde (ALTMODE)

7F

177

127

DEL

rubout (DELETE)

80

200

128

[reserved]

81

201

129

[reserved]

82

202

130

[reserved]

83

203

131

[reserved]

84

204

132

IND

index

85

205

133

NEL

next line

86

206

134

SSA

start of selected area

87

207

135

ESA

end of started area

88

210

136

HTS

horizontal tab set

89

211

137

HTJ

horizontal tab set with

justification

8A

212

138

VTS

vertical tab set

8B

213

139

PLD

partial line down

8C

214

140

PLU

partial line up

8D

215

141

RI

reverse index

Description

ASCII Alphabetic Characters

8E

216

142

SS2

single shift 2

8F

217

143

SS3

single shift 3

90

220

144

DCS

device control string

91

221

145

PU1

private use 1

92

222

146

PU2

private use 2

93

223

147

STS

set transmit state

94

224

148

CCH

cancel character

95

225

149

MW

message waiting

96

226

150

SPA

start of protected area

97

227

151

EPA

end of protected area

98

230

152

[reserved]

99

231

153

[reserved]

9A

232

154

[reserved]

9B

233

155

CSI

control sequence introducer

9C

234

156

ST

string terminator

9D

235

157

OSC

operating system command

(continued on next page)

Tables C5

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

9E

236

158

PM

privacy message

9F

237

159

APC

application

A0

240

160

[reserved]

A1

241

161

inverted exclamation point

A2

242

162

cent sign

A3

243

163

pound sign

A4

244

164

[reserved]

A5

245

165

yen sign

A6

246

166

[reserved]

A7

247

167

section sign

A8

250

168

general currency sign

A9

251

169

copyright sign

AA

252

170

feminine ordinal indicator

AB

253

171

angle quotation mark left

AC

254

172

[reserved]

AD

255

173

[reserved]

AE

256

174

[reserved]

AF

257

175

[reserved]

B0

260

176

degree sign

B1

261

177

plus/minus sign

B2

262

178

superscript 2

B3

263

179

superscript 3

B4

264

180

[reserved]

B5

265

181

micro sign

B6

266

182

paragraph sign, pilcrow

B7

267

183

middle dot

B8

270

184

[reserved]

B9

271

185

superscript 1

BA

272

186

masculine ordinal indicator

BB

273

187

angle quotation mark right

Description

ASCII Alphabetic Characters

BC

274

188

fraction one-quarter

BD

275

189

fraction one-half

BE

276

190

[reserved]

BF

277

191

inverted question mark

C0

300

192

uppercase A with grave

accent
(continued on next page)

C6 Tables

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

C1

301

193

uppercase A with acute

accent

C2

302

194

uppercase A with circumflex

C3

303

195

uppercase A with tilde

C4

304

196

uppercase A with umlaut

(diaeresis)

C5

305

197

uppercase A with ring

C6

306

198

uppercase AE diphthong

C7

307

199

uppercase C with cedilla

C8

310

200

uppercase E with grave

accent

C9

311

201

uppercase E with acute

accent

CA

312

202

uppercase E with circumflex

CB

313

203

uppercase E with umlaut

(diaeresis)

CC

314

204

uppercase I with grave

accent

CD

315

205

uppercase I with acute

accent

CE

316

206

uppercase I with circumflex

CF

317

207

uppercase I with umlaut

(diaeresis)

D0

320

208

[reserved]

D1

321

209

uppercase N with tilde

D2

322

210

uppercase O with grave

accent

D3

323

211

uppercase O with acute

accent

D4

324

212

uppercase O with circumflex

D5

325

213

uppercase O with tilde

D6

326

214

uppercase O with umlaut

(diaeresis)

D7

327

215

uppercase OE ligature

D8

330

216

uppercase O with slash

D9

331

217

uppercase U with grave

accent

DA

332

218

uppercase U with acute

accent

DB

333

219

uppercase U with circumflex

Description

ASCII Alphabetic Characters

(continued on next page)

Tables C7

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

DC

334

220

uppercase U with umlaut

(diaeresis)

DD

335

221

uppercase Y with umlaut

(diaeresis)

DE

336

222

[reserved]

DF

337

223

German lowercase sharp s

E0

340

224

lowercase a with grave

accent

E1

341

225

lowercase a with acute

accent

E2

342

226

lowercase a with circumflex

E3

343

227

lowercase a with tilde

E4

344

228

lowercase a with umlaut

(diaeresis)

E5

345

229

lowercase a with ring

E6

346

230

lowercase ae diphthong

E7

347

231

lowercase c with cedilla

E8

350

232

lowercase e with grave

accent

E9

351

233

lowercase e with acute

accent

EA

352

234

lowercase e with circumflex

EB

353

235

lowercase e with umlaut

(diaeresis)

EC

354

236

lowercase i with grave

accent

ED

355

237

lowercase i with acute

accent

EE

356

238

lowercase i with circumflex

EF

357

239

lowercase i with umlaut

(diaeresis)

F0

360

240

[reserved]

F1

361

241

lowercase n with tilde

F2

362

242

lowercase o with grave

accent

F3

363

243

lowercase o with acute

accent

F4

364

244

lowercase o with circumflex

F5

365

245

lowercase o with tilde

F6

366

246

lowercase o with umlaut

(diaeresis)

Description

ASCII Alphabetic Characters

(continued on next page)

C8 Tables

Tables
C.1 DEC Multinational Character Set
Table C1 (Cont.) DEC Multinational Character Set
Hex Code

Octal Code

Decimal
Code

Char or
Abbrev.

F7

367

247

lowercase oe ligature

F8

370

248

lowercase o with slash

F9

371

249

lowercase u with grave

accent

FA

372

250

lowercase u with acute

accent

FB

373

251

lowercase u with circumflex

FC

374

252

lowercase u with umlaut

(diaeresis)

FD

375

253

lowercase y with umlaut

(diaeresis)

FE

376

254

[reserved]

FF

377

255

[reserved]

Description

ASCII Alphabetic Characters

C.2 Terminal Sequences and Modes

Table C2 lists the valid ANSI and DIGITAL private escape sequences
for terminals that have the TT2$M_ANSICRT, TT2$M_DECCRT,
TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK characteristics (see
Section 5.2.1.4).
Table C2 also lists assumed and selectable ANSI modes and selectable DIGITAL
private modes. Only the names of the escape sequences and modes are listed (for
more information, refer to the specific VT100-, VT200-, or VT300- family users
guide). Unless otherwise noted, the operation of escape sequences and modes
is identical to the particular VT100-, VT200-, or VT300- family terminals that
implement these features.
Table C2 Sequences and Modes
Name

Valid Parameters

ANSICRT

DECCRT

AVO

EDIT

BLOCK1

ANSI-Defined Escape Sequences

CPR

All

CUB

All

CUD

All

CUF

All

CUP

All

CUU

All

DSR

0,3,5,6

ED

0,1,2

1 Terminal

characteristics. Prefix is TT2$M_.

(continued on next page)

Tables C9

Tables
C.2 Terminal Sequences and Modes
Table C2 (Cont.) Sequences and Modes
Name

Valid Parameters

ANSICRT

DECCRT

AVO

EDIT

BLOCK1

ANSI-Defined Escape Sequences

EL

0,1,2

HVP

All

IND

NEL

RI

RIS
SCS

UK,ASCII,0

SCS

UK,ASCII

SGR

0,4,7

SGR

0,1,4,5,7

DA

Terminal specific

HTS

RM

Class specific

SM

Class specific

TBC

0,3

DCH

All

DL

All

IL

All

DIGITAL Private Escape Sequences

DECDHDL

2,3

DECDWL

DECKPAM

DECKPNM

DECRC

DECSC

DECSTBM

All

DECSWL

DECPRO

0,1,4,5,7,254

DECTTC

0,1

DECXMIT

x
ANSI Selectable Modes (Set with ANSI SM/RM)

IRM

GATM

ERM

1 Terminal

x
x
x

characteristics. Prefix is TT2$M_.

(continued on next page)

C10 Tables

Tables
C.2 Terminal Sequences and Modes
Table C2 (Cont.) Sequences and Modes
Name

Valid Parameters

ANSICRT

DECCRT

AVO

EDIT

BLOCK1

ANSI Selectable Modes (Set with ANSI SM/RM)

TTM

16

x
DIGITAL Private Selectable Modes (Set with ANSI SM/RM)

DECCKM

DECANM

DECCOLM

DECSCLM

DECSCNM

DECOM

DECAWM

DECARM

DECEDM

10

DECEKEM

16

DECLTM

11

DECSCFDM

13

DECTEM

14

x
ANSI Assumed Modes

CRM

Reset

Reset

EBM

Reset

Reset

ERM

Set

Set

FEAM

Reset

Reset

FETM

Reset

Reset

GATM

N/A

N/A

HEM

N/A

N/A

IRM

Reset

Reset

KAM

Reset

Reset

MATH

N/A

N/A

PUM

Reset

Reset

SATM

N/A

N/A

SRTM

Reset

Reset

TSM

Reset

Reset

TTM

N/A

N/A

VEM

N/A

N/A

1 Terminal

characteristics. Prefix is TT2$M_.

2 Selectable

mode.

Tables C11

D
Control Connection Routines
This appendix lists and describes the calling conventions for the pseudoterminal
driver control connection routines. The routines appear in this section in
alphabetical order.
Table D1 lists the control connection routines and their functions:
Table D1 Control Connection Routines
Routine Name

Description

PTD$CANCEL

Cancels a queued control connection read

request

PTD$CREATE

Creates a pseudoterminal

PTD$DELETE

Deletes a pseudoterminal

PTD$READ

Reads data from the pseudoterminal

PTD$READW

Reads data from the pseudoterminal and

waits for read to complete

PTD$SET_EVENT_NOTIFICATION

Enables or disables terminal event notification

ASTs

PTD$WRITE

Writes data to the pseudoterminal

Control Connection Routines D1

Control Connection Routines

PTD$CANCEL

PTD$CANCELCancel Queued Request

Cancels a queued control connection read request.

Format
PTD$CANCEL chan

Returns
OpenVMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
read only
by value

Arguments

Number of the I/O channel assigned to the pseudoterminal. This channel is only
intended to be used for PTD$XXX operations.

Return Values
SS$_NORMAL
SS$_DEVOFFLINE
SS$_IVCHAN
SS$_NOPRIV

D2 Control Connection Routines

Normal successful completion.

Device is off line and request cannot proceed.
Illegal channel.
Insufficient privilege to perform request.

Control Connection Routines

PTD$CREATE

PTD$CREATECreate a Pseudoterminal
Creates a new pseudoterminal with a unique device name.

Format
PTD$CREATE chan [,acmode] [,charbuff] [,buflen] [,astadr] [,astprm] [,ast_acmode], inadr

Returns
OpenVMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism:
by value

Arguments
chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
write only
by reference

Number of the channel that is assigned to the new pseudoterminal. This

argument is the address of a word into which PTD$CREATE writes the channel
number. This channel is only intended to be used for PTD$XXX operations.
acmode
OpenVMS usage:
type:
access:
mechanism:

access_mode
longword (unsigned)
read only
by value

Access mode to be associated with the channel. The most privileged access mode
is the access mode of the caller. I/O operations on the channel can be performed
only from equal and more privileged access modes.
charbuff
OpenVMS usage:
type:
access:
mechanism:

device_characteristics
longword (unsigned)
read only
by reference

Address of buffer containing the device characteristics. This information is used

to set up the pseudoterminals initial characteristics. This buffer can be 12, 16, or
20 bytes long.
Figure D1 shows the format of this buffer:

Control Connection Routines D3

Control Connection Routines

PTD$CREATE
Figure D1 Device Characteristics Buffer

Page Width
Page Length

Type

Class

Basic Terminal Characteristics

Extended Terminal Characteristics
Reserved
Reserved
ZK9573GE

buflen
OpenVMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Length of the characteristics buffer (either 12, 16, or 20 bytes). This argument is
required if you supply the charbuff argument.
astadr
OpenVMS usage:
type:
access:
mechanism:

ast_procedure
procedure value
call without stack unwinding
by reference

AST service routine to be executed when the terminal connection deassigns the
last channel to the pseudoterminal. This argument is the procedure value of this
routine. This is a repeating AST and is active until the control connection deletes
the pseudoterminal.
astprm
OpenVMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

AST parameter to be passed to the AST service routine specified by astadr.

ast_acmode
OpenVMS usage:
type:
access:
mechanism:

access_mode
longword (unsigned)
read only
by value

Access mode for which the AST is to be declared. The most privileged access
mode is the access mode of the caller. The resulting mode is the access mode at
which the AST is declared.
inadr
OpenVMS usage:
type:
access:
mechanism:

D4 Control Connection Routines

address_range
longword (unsigned)
read only
by reference

Control Connection Routines

PTD$CREATE
Address of a two-longword array containing the starting and ending virtual
addresses in the virtual address space of the process (either P0 or P1 regions)
to be used as I/O buffers. The array contains, in order, the starting and ending
virtual addresses. The addresses supplied to inadr must express an integral
number of CPU-specific pages. The lower address must be on a CPU-specific
page boundary, and the higher address must be one less than a CPU-specific page
boundary. Together these addresses form a range from lowest to highest bytes.
The pages must already exist and must be fully contained in either P0 or P1
space. All pages in the range must:

Have identical page protection

Be writable in the mode of the caller

Be owned by the same access mode

Be owned in a mode equal to or less privileged than the caller

Be of the same page type (process or global)

Description
PTD$CREATE creates a new pseudoterminal with a unique device name. This
device name is in the form FTAn:, where n is the unit number.
When a pseudoterminal is created, it inherits the current system terminal default
attributes unless you specify an alternate set of characteristics.

Return Values
SS$_NORMAL
SS$_ACCVIO
SS$_BADPARAM
SS$_EXBYTLM
SS$_EXQUOTA
SS$_EXASTLM
SS$_INSFMEM
SS$_INSFWSL
SS$_IVSECFLG
SS$_NOPRIV
SS$_PAGOWNVIO
SS$_VA_IN_USE

Normal successful completion.

Unable to read one of the arguments.
Bad parameter value.
Insufficient BYTLM to create device or map
buffers.
Insufficient quota to create device.
Insufficient AST quota for notification AST.
Insufficient memory to create device.
Insufficient working set limit to map buffers.
Invalid process or global section flags.
No privilege for attempted operation.
Page owner violation.
Virtual address already in use.

Control Connection Routines D5

Control Connection Routines

PTD$DELETE

PTD$DELETEDelete a Pseudoterminal
Forces the pseudoterminal to be deleted and frees the channel.

Format
PTD$DELETE chan

Returns
OpenVMS usage: longword (unsigned)
type:
write only
access:
by value

Arguments
chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
read only
by value

Number of the I/O channel assigned to the pseudoterminal. This channel is only
intended to be used for PTD$XXX operations.

Description
PTD$DELETE forces the pseudoterminal to be deleted and frees the channel
assigned to the pseudoterminal. When a pseudoterminal is deleted, any process
using the pseudoterminal (except the control program) is disconnected. A
PTD$DELETE request causes any pending I/O for the control program to be
aborted. It deletes any queued event notification ASTs and returns the I/O
buffers back to the application. It also causes the pseudoterminal unit control
block (UCB) to be deleted once the reference count returns to zero.

Return Values
SS$_NORMAL
SS$_DEVOFFLINE
SS$_IVCHAN
SS$_NOPRIV

D6 Control Connection Routines

Normal successful completion.

Device is off line and request cannot proceed.
Illegal channel.
Insufficient privilege to perform request.

Control Connection Routines

PTD$READ

PTD$READRead Data from Pseudoterminal

Reads data from the pseudoterminal. The PTD$READ routine completes
asynchronously; that is, it returns to the caller without waiting for the data
to be read.
For synchronous completion, use the PTD$READW routine. The PTD$READW
routine is identical to the PTD$READ routine in every way, except that
PTD$READW returns to the caller after the data is read.

Format
PTD$READ [efn], chan [,astadr] [,astprm] readbuf, readbuf_len

Returns
OpenVMS usage: longword (unsigned)
type:
write only
access:
by value

Arguments
efn
OpenVMS usage:
type:
access:
mechanism:

ef_number
longword (unsigned)
read only
by value

Number of the event flag to be set when PTD$READ returns the requested
information. If you do not specify this argument, event flag 0 is used. When
PTD$READ begins execution, it clears this flag.
chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
read only
by value

Number of the I/O channel assigned to the pseudoterminal. This channel is only
intended to be used for PTD$XXX operations.
astadr
OpenVMS usage:
type:
access:
mechanism:

ast_procedure
procedure value
call without stack unwinding
by reference

AST service routine to be executed when PTD$READ completes. If you specify

astadr, the AST routine executes at the same access mode as the caller of the
PTD$READ routine.

Control Connection Routines D7

Control Connection Routines

PTD$READ
astprm
OpenVMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

AST parameter to be passed to the AST service routine specified by the astadr
argument.
readbuf
OpenVMS usage:
type:
access:
mechanism:

char_string
character coded text string
write only
by reference

Address of the read I/O status longword. The first character position in an I/O
buffer to receive all output is this address plus 4. The readbuf argument must
be in the range specified in the inadr argument of the PTD$CREATE routine;
otherwise, an SS$_ACCVIO status is returned.
readbuf_len
OpenVMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Number of characters that can be read from the pseudoterminal and stored in the
buffer specified by readbuf.

Description
The PTD$READ routine reads data from the pseudoterminal. The read request
completes with a minimum of one character and a maximum of the number of
characters specified by the readbuf_len argument. The read operation completes
when the pseudoterminal has characters to output. If a read request is issued
and no data is available, the read request is queued and then completed at a later
time.

Return Values
SS$_NORMAL
SS$_ACCVIO
SS$_DEVOFFLINE
SS$_EXASTLM
SS$_ILLEFC
SS$_INSFMEM
SS$_IVBUFLEN
SS$_IVCHAN
SS$_NOPRIV
SS$_UNASEFC

D8 Control Connection Routines

Normal successful completion.

Unable to read an argument, or invalid read
buffer address.
Device is off line and request cannot proceed.
Insufficient AST quota for notification AST.
Illegal event flag cluster.
Insufficient memory.
Buffer size supplied is illegal.
Illegal channel.
Insufficient privilege to perform request.
Unassociated event flag cluster.

Control Connection Routines

PTD$READW

PTD$READWRead Data from Pseudoterminal and Wait

Reads data from the pseudoterminal. The PTD$READW routine completes
synchronously; that is, it returns to the caller after the data has been read.
For asynchronous completion, use the PTD$READ routine. The PTD$READ
routine is identical to the PTD$READW routine in every way except that
PTD$READ returns to the caller without waiting for the data to be read.

Format
PTD$READW [efn], chan [,astadr] [,astprm] readbuf, readbuf_len

Control Connection Routines D9

Control Connection Routines

PTD$SET_EVENT_NOTIFICATION

PTD$SET_EVENT_NOTIFICATIONEnable or Disable Terminal Event

Notification ASTs
Enables or disables a number of repeating terminal event notification ASTs.

Format
PTD$SET_EVENT_NOTIFICATION chan, astadr [,astprm] [,acmode], type

Returns
OpenVMS usage: longword (unsigned)
type:
write only
access:
by value

Arguments
chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
read only
by value

Number of the I/O channel assigned to the pseudoterminal. This channel is only
intended to be used for PTD$XXX operations.
astadr
OpenVMS usage:
type:
access:
mechanism:

ast_procedure
procedure value
call without stack unwinding
by reference

Address of the notification AST service routine, or zero if the AST is to be

canceled.
astprm
OpenVMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

AST parameter to be passed to the AST service routine specified by the astadr
argument.
acmode
OpenVMS usage:
type:
access:
mechanism:

access_mode
longword (unsigned)
read only
by value

Access mode for which the AST is to be declared. The most privileged access
mode is the access mode of the caller. The resulting mode is the access mode at
which the AST is declared.

D10 Control Connection Routines

Control Connection Routines

PTD$SET_EVENT_NOTIFICATION
type
OpenVMS usage:
type:
access:
mechanism:

type_longword
longword (unsigned)
read only
by value

Value that indicates which notification AST to enable. The $PTDDEF macro
defines the symbolic names listed in Table D2.
Table D2 Symbolic Names Defined by $PTDDEF Macro
Symbolic Name

Description

PTD$C_SEND_XON

Deliver notification AST when the pseudoterminal is ready to

accept input. This AST is not delivered if the pseudoterminal is
set to NO HOSTSYNC.
Deliver notification AST when the pseudoterminal wants to stop
input and signal it with a bell character.
Deliver notification AST when the pseudoterminal wants to stop
input and signal it with a DC3 character.
Deliver notification AST when the pseudoterminal is stopping
output.
Deliver notification AST when the pseudoterminal is resuming
output.
Deliver notification AST when the pseudoterminal has changed
some device characteristic.
Deliver notification AST when the pseudoterminal wants to
abort output.
Deliver notification AST when the pseudoterminal is starting
an applications read request. This AST is delivered only if read
event notification has been enabled.
Deliver notification AST when the pseudoterminal has finished
sending an applications read request prompt string. This AST
is delivered only if read event notification has been enabled.
Deliver notification AST when the pseudoterminal has finished
an applications read request. This AST is delivered only if read
event notification has been enabled.
Enable terminal read event AST delivery. If this code is used,
you cannot supply the astadr argument.
Disable terminal read event AST delivery. If this code is used,
you cannot supply the astadr argument.

PTD$C_SEND_BELL
PTD$C_SEND_XOFF
PTD$C_STOP_OUTPUT
PTD$C_RESUME_OUTPUT
PTD$C_CHAR_CHANGED
PTD$C_ABORT_OUTPUT
PTD$C_START_READ

PTD$C_MIDDLE_READ

PTD$C_END_READ

PTD$C_ENABLE_READ
PTD$C_DISABLE_READ

Description
PTD$SET_EVENT_NOTIFICATION enables or disables the repeating terminal
event notification ASTs listed in Table D2. After an event notification AST is
enabled, it remains in effect until it is disabled or until the device is deleted.

Control Connection Routines D11

Control Connection Routines

PTD$SET_EVENT_NOTIFICATION
Return Values
SS$_NORMAL
SS$_ACCVIO
SS$_BADPARAM

SS$_DEVOFFLINE
SS$_EXASTLM
SS$_INSFMEM
SS$_IVCHAN
SS$_NOPRIV

D12 Control Connection Routines

Normal successful completion.

Unable to read an argument, or invalid I/O buffer
address.
An astadr, astprm, or acmode argument
was not zero when enabling or disabling read
notification.
Device is off line and request cannot proceed.
Insufficient AST quota for notification AST.
Insufficient memory.
Illegal channel.
Insufficient privilege to perform request.

Control Connection Routines

PTD$WRITE

PTD$WRITEWrite Data to Pseudoterminal

Inputs data to the pseudoterminal and reads any immediately echoed characters.

Format
PTD$WRITE chan [,astadr] [,astprm], wrtbuf, wrtbuf_len [,echobuf] [,echobuf_len]

Returns
OpenVMS usage: longword (unsigned)
type:
write only
access:
by value

Arguments
chan
OpenVMS usage:
type:
access:
mechanism:

channel
word (unsigned)
read only
by value

Number of I/O channel assigned to the pseudoterminal. This channel is only

intended to be used for PTD$XXX operations.
astadr
OpenVMS usage:
type:
access:
mechanism:

ast_procedure
procedure value
call without stack unwinding
by reference

AST service routine to be executed when PTD$WRITE completes. If astadr is

specified, the AST routine executes at the same access mode as the caller of the
PTD$WRITE routine.
astprm
OpenVMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

AST parameter to be passed to the AST service routine specified by the astadr
argument.
wrtbuf
OpenVMS usage:
type:
access:
mechanism:

char_string
character coded text string
read only
by reference

Address of the write I/O status longword. The first character in an I/O buffer to
be written is this address plus 4. The wrtbuf must be in the range specified by
the inadr argument of the PTD$CREATE routine; otherwise, an SS$_ACCVIO
status is returned.

Control Connection Routines D13

Control Connection Routines

PTD$WRITE
wrtbuf_len
OpenVMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Number of characters to be written to the pseudoterminal. These characters

appear as input to the terminal side of the pseudoterminal.
echobuf
OpenVMS usage:
type:
access:
mechanism:

char_string
character coded text string
write only
by reference

Address of the echo I/O status longword. The first character position in an I/O
buffer to receive all output is this address plus 4. The echobuf must be in the
range specified by the inadr argument of the PTD$CREATE routine; otherwise
an SS$_ACCVIO status is returned.
echobuf_len
OpenVMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Number of characters that can be read from the pseudoterminal. If an echo buffer
is specified, up to echobuf_len characters can be stored in it.

Description
PTD$WRITE inputs data to the pseudoterminal and reads any immediately
echoed characters. PTD$WRITE allows you to specify a buffer to receive any
output generated by the write; you do not need to issue a separate read request
to read this data.

Return Values
SS$_NORMAL
SS$_ACCVIO
SS$_DATALOST
SS$_DATAOVERUN

SS$_DEVOFFLINE
SS$_EXASTLM
SS$_INSFMEM
SS$_IVBUFLEN
SS$_IVCHAN
SS$_NOPRIV

D14 Control Connection Routines

Normal successful completion.

Unable to read an argument, or invalid I/O buffer
address.
The terminal driver type-ahead buffer is full and
character written was lost.
The terminal driver type-ahead buffer is getting
full; attempts to send more data might result in
loss of characters.
Device is off line and request cannot proceed.
Insufficient AST quota for notification AST.
Insufficient memory.
Buffer size supplied is illegal.
Illegal channel.
Insufficient privilege to perform request.

Index
A
ACP functions, 12, 135
attributes, 115 to 118
disk quotas, 137
IO$_ACCESS, 17, 110, 114, 127
IO$_ACPCONTROL, 17
IO$_CREATE, 110, 111, 114, 125
IO$_DEACCESS, 113, 114, 129
IO$_DELETE, 17, 130
IO$_MODIFY, 17, 111, 113, 114, 129
IO$_MOUNT, 135
magnetic tape positioning, 136
miscellaneous disk, 136
quota file transfer block, 138
ACP-QIO interface
See also FIBs
access file function, 127
access subfunction, 110
ACP control function, 135
ANSI standard, 12, 136
arguments, 12
disk quota, 139
attribute control block, 114
attributes, 115 to 118
attributes statistics block, 122
BLISS-32 programming, 11
create file function, 125
disk, 126
magnetic tape, 127
deaccess file function, 129
delete file function, 130
description, 11
directory entries, 19, 127
file characteristics, 118
function codes, A1
function modifiers, 12
IO$M_ACCESS, 110, 125, 127
IO$M_CREATE, 125, 126, 127
IO$M_DELETE, 125, 126, 131
IO$M_DMOUNT, 135, 137
I/O operations, 11
I/O status block, 139
MACRO programming, 11
movefile subfunction, 131
record attributes area, 121
values, 121

ACP-QIO interface (contd)

serious exception (EOT), 125, 128, 136
status returns, A1
XQP (extended QIO processor), 11
ACP subfunctions, 16
access, 110
directory lookup, 17
extend, 111, 139
movefile, 129
read/write attributes, 114
truncate, 113
ALTMODE key, 521
ANSI escape sequence, C9
Applications
connecting to LAT ports, 550
Arguments
device- or function-dependent, 12
list, A1
ASCII character set
See DEC Multinational character set
ASTs (asynchronous system traps)
quota, 228, 310, 45, 545
Asynchronous SCSI data transfer mode
enabling, 86, 812
ATM (asynchronous transfer mode)
ELAN frames, 948
LAN emulation, 932
ATM network
LAN emulation, 933
Attention AST, 578
LAN drivers, 981
mailbox, 412
terminal, 545
AUCBs (audio control blocks)
definition, 220
Audio
error handling in applications, 223
extensions to SCSI disk class driver, 219
$QIO interface to disk class driver, 220
storing with data on CD-ROM, 225
Audio applications
programming, 226
programming example, 226
Audio control blocks
See AUCBs

Index1

Autoconfiguration
of SCSI device, 88

CTDRIVER driver, 512, 538

Ctrl/x key sequence
See Terminals, control characters

B
Baud rate
of terminal, 543
64-bit virtual addressing
device driver support, xx
Booting, 936
Broadcast and unknown server (BUS), 933
Broadcast messages, 518, 522, 524, 550
Buffered I/O
quota, 228, 310, 45

C
Caches
tape, 35
write-back volatile, 35
Carriage control, 539
CD-ROM (compact disc read-only memory)
storing data and audio information, 25
Characters
terminator set for, 530
Character sets
See also DEC Multinational character set
terminal lowercase, 521, C1
Classical IP, 934
Classical IP over ATM, 932
Compact discs
See CD-ROM (compact disc read-only memory)
Configuring
Ethernet media type, 944
Configuring ISA devices, 943 to 944
CONNECT command, 518
Console configuring
Ethernet media type, 944
Console disks
See RX01 console disk
Console terminals, 51
Control characters
list, C1
terminal, 54 to 57, 510
Control connection routines, D1 to D14
PTD$CANCEL, D2
PTD$CREATE, D3
PTD$DELETE, D6
PTD$READ, D7
PTD$READW, D9
PTD$SET_EVENT_NOTIFICATION, D10
PTD$WRITE, D13
Control key sequences, 58
Create file function, 125
directory entry creation, 127

Index2

D
Data
storing with audio information on CD-ROM,
225
Data checks
disk, 212, 233, 234
magnetic tape, 36, 314, 316
Data transfer mode
as controlled by the generic SCSI class driver,
86, 812
asynchronous, 86, 812
synchronous, 86, 812
DE500-AA adapter, 96
DE500-BA adapter, 96
DE500-FA adapter, 96
DE500 LAN controllers, 96
DE500-XA adapter, 96
DE600 adapter, 97
Deaccess file function, 129
DEC Multinational character set, C1
DEGPA Gigabit Ethernet NIC, 98
DEGPA internal counters, 98
DEGXA Gigabit Ethernet NIC, 921
DEGXA internal counters, 922
Delete file function, 130
Delete key, 55
Device characteristics
disk, 226
LAN drivers, 960
magnetic tape, 38
mailbox, 44
pseudoterminal, 63
terminal, 520
Devices
SCSI support, 72
supported, 72
Device-specific functions, 931
DHU11 device, 51
DHV11 device, 51
Dialup lines, 513
Digital private escape sequence, C9
Digital Storage Architecture disks
See DSA disks
Direct I/O
count process limit, 228, 310
Directory entry
creation, 127
protection, 19
Directory lookup subfunction, 17
directory entry protection, 19

DISCONNECT command, 518

Disconnect features
enabling, 812
Disk class drivers
audio extensions, 219
disabling the loading of, 89
$QIO interface to audio functions, 220
Disk drives
compatibility for volume shadowing, 72
Disks
ACP operation
control function, 136
creating file, 126
deaccessing file, 129
available function, 236
Backup utility, 217
compact disc, 25
data check, 212, 233, 234
device characteristics, 226
device descriptions, 23 to 27
driver, 21, 219
SCSI, 218
VAXstation 2000 and MicroVAX 2000,
218
dual-pathed, 28
DSA disks, 211
dual-ported, 29
DSA disks, 211
HSC disks, 211
restrictions for use, 210
error recovery, 214
features, 28
file attributes, 212
function codes, 229, A2
function modifiers
IO$M_DATACHECK, 212, 233, 234
IO$M_DELDATA, 234
IO$M_ERASE, 231, 234
IO$M_INHRETRY, 214, 233, 234
HSC50 controller, 22
HSC70 controller, 22
HSC controllers, 22
I/O functions, 228, 233 to 239
See also ACP-QIO interface
arguments, 230 to 233
IO$_ACPCONTROL, 136
I/O status block, 239
KDA50 controller, 22
KDB50 controller, 22
KFQSA adapter, 23
offset recovery, 212
pack acknowledge function, 236
port access mode, 29
port selection, 29
programming example, 240
quotas, 137 to 138, 228
RA60, 23
RA70, 23

Disks (contd)
RA90, 23
RB02 cartridge, 24
RC25, 24
RCT (replacement and caching table), 217
RD53, 24
RD54, 24
read function, 233
RF30, 25
RF31
failover, 211
RF70
failover, 211
RF71, 25
RK06 cartridge, 25
RK07 cartridge, 25
RL02 cartridge, 24
RM03, 25
RM05, 25
RP05, 25
RP06, 25
RP07, 25
RQDX3 controller, 23
RRD40 CD-ROM, 25
RRD50 CD-ROM, 25
RX02, 26
RX23 flexible, 27
RX33 flexible, 27
RX50 flexible, 27
RZ22, 27
RZ23, 27
RZ55, 27
SDI (standard disk interface), 23
search function, 235
sector translation, 215
seek operations, 213, 236
sense mode function, 235
set density function, 235
set preferred path function, 237
SII integral adapter, 23
skip sectoring, 214
status returns, A3
supported devices, 21 to 28
SYS$GETDVI returns, 226
TU58 magnetic tape, 27
data checks, 212
read function, 233
search function, 235
write check function, 237
write function, 234
UDA50 disk adapter, 21
unload function, 236
use with Verify utility, 216, 217
VAXstation 2000 and MicroVAX 2000 driver,
218
write check function, 236
write function, 234

Index3

DISMOUNT command, 137

Distributed interrupts, 107
DMA statistics, 918
DMB32 device, 51
DMF32 device, 51
DMZ32 device, 51
Driver messages, 930
Drivers
disks, 21
LAN, 92
LAT port, 51
magnetic tape, 31
mailbox, 41
pseudoterminal, 61
SCSI, 218
SCSI disk class, 219
shadow set virtual unit, 71
terminal, 51
VAXstation 2000 and MicroVAX 2000 disk,
218
DSA32 device, 51
DSA disks, 211, 216
See also Disks
bad block replacement, 217, 218
forced error, 217
forced error flag, 217
use with Verify utility, 216, 217
DSE (data security erase)
magnetic tape, 324
Dual host
definition, 23
Dual path
definition, 28
Dual-pathed disks, 28
DSA disk, 211
Dual-ported disks, 29
DSA disk, 211
HSC disk, 211
restrictions for use, 210
Duplex mode
See also Half-duplex mode
terminal, 510
DZ11 device, 51
DZ32 device, 51
DZV11 device, 51

E
ELAN configuring, 936
Enable attention AST function
LAN drivers, 981
End-of-file
See EOF
End-of-tape markers
See EOT markers

Index4

End-of-volume
See EOV
EOF (end-of-file)
status of magnetic tape, 315
write mailbox message, 411
EOT markers
status
magnetic tape, 315, 316, 319
EOV (end-of-volume)
detection on magnetic tape, 318
Error recovery
disk, 214
magnetic tape, 37
shadow set virtual unit driver, 74
Escape sequences
ANSI, C9
Digital private, C9
terminal, 57, 521
Ethernet
device drivers, 95
Ethernet media types
configuring from console, 944
Event notification
pseudoterminal, 66
Event statistics, 917
Extend subfunction, 111

F
Fandle, 104
Fast Ethernet, 96
Fast I/O
function codes, A8
system services, 101
Fast Path, 107
function codes, A9
Fast Path performance enhancement, 107
FDDI (Fiber Distributed Data Interface)
device drivers, 95
FDDI NIcs
PDQ chip, 932
FIBs (file information blocks), 13
See also ACP functions
access control, 110
contents, 14 to 16
descriptor, 12, 13
directory lookup, 17
disk quota, 137 to 138
extend control, 111
IO$_ACCESS, 128
IO$_ACPCONTROL, 135 to 138
IO$_CREATE, 125
IO$_DEACCESS, 129
IO$_DELETE, 131
IO$_MODIFY, 130
truncate control, 113

File characteristics
ACP-QIO attributes, 118
Fork delay debug data, 930
Form feeds
terminal, 522
Full-duplex mode, 510
Function codes
See also I/O functions
IO$_ACCESS, 127
IO$_ACPCONTROL, 135, 311
IO$_AVAILABLE, 236, 325
IO$_CREATE, 125
IO$_DEACCESS, 129
IO$_DELETE, 130
IO$_DSE, 324
IO$_FORMAT, 235
IO$_MODIFY, 129
IO$_PACKACK, 236
IO$_READLBLK, 233, 314, 45, 528, 962
IO$_READPBLK, 233, 314, 45, 962
IO$_READPROMPT, 528
IO$_READVBLK, 233, 314, 45, 528, 962
IO$_REWIND, 316
IO$_REWINDOFF, 319
IO$_SEARCH, 235
IO$_SEEK, 232, 236
IO$_SENSECHAR, 235, 579
IO$_SENSEMODE, 235, 319, 579, 987
IO$_SETCHAR, 320, 541, 968
IO$_SETMODE, 320, 541, 968
IO$_SETPRFPATH, 237
IO$_SKIPFILE, 317
IO$_SKIPRECORD, 318
IO$_UNLOAD, 236, 319
IO$_WRITECHECK, 236
IO$_WRITELBLK, 234, 316, 49, 538, 966
IO$_WRITEOF, 319
IO$_WRITEPBLK, 234, 316, 49, 538, 966
IO$_WRITEVBLK, 234, 316, 49, 538, 966
list of, A1
Function modifiers
for LAN driver, 965
IO$M_ACCESS, 125, 127, 311
IO$M_ATTNAST, 981
IO$M_BRDCST, 550, 582
IO$M_BREAKTHRU, 511, 539
IO$M_CANCTRLO, 55, 539
IO$M_CREATE, 125, 127, 311
IO$M_CTRL, 981, 987
IO$M_CTRLCAST, 545
IO$M_CTRLYAST, 56, 545
IO$M_CVTLOW, 529
IO$M_DATACHECK, 212, 233, 234, 36,
314, 316
IO$M_DELDATA, 234
IO$M_DELETE, 125, 131
IO$M_DMOUNT, 135
IO$M_DSABLMBX, 529

Function modifiers (contd)

IO$M_ENABLMBX, 539
IO$M_ERASE, 231, 234, 316
IO$M_ESCAPE, 57, 529
IO$M_EXTEND, 529, 531
IO$M_FORCEPATH, 237
IO$M_HANGUP, 545
IO$M_INCLUDE, 546, 549
IO$M_INHEXTGAP, 37
IO$M_INHRETRY, 233, 37
IO$M_MAINT, 546, 548
IO$M_MOVEFILE, 129
IO$M_NOECHO, 511, 526, 529
IO$M_NOFILTR, 529
IO$M_NOFORMAT, 511, 539
IO$M_NORSWAIT, 49, 411
IO$M_NOW, 45, 49, 411, 965
IO$M_NOWAIT, 316, 319
IO$M_OUTBAND, 549
IO$M_PURGE, 529
IO$M_RD_MODEM, 580
IO$M_READATTN, 411
IO$M_READERCHECK, 49, 411, 415
IO$M_REFRESH, 539
IO$M_RESPONSE, 968
IO$M_REVERSE, 314
IO$M_SETPROT, 414
IO$M_SET_MODEM, 546
IO$M_SHUTDOWN, 981
IO$M_STREAM, 45
IO$M_TIMED, 530
IO$M_TRMNOECHO, 530
IO$M_TT_ABORT, 549
IO$M_TYPEAHDCNT, 580
IO$M_UNLOOP, 549
IO$M_WRITERCHECK, 45, 415
list of, A1

G
Generic SCSI class driver, 81 to 815
assigning a channel to, 89
flow of, 84
I/O status block returned by, 810
loading, 88
obtaining device information from, 813
programming example, 814 to 815
$QIO system service format for, 810 to 813
security considerations, 84
Generic SCSI descriptor
format of, 811 to 813
Gigabit Ethernet, 97
Gigabit Ethernet NIC
DEGXA, 921

Index5

H
Half-duplex mode, 510, 521
See also Duplex mode
Hangup function modifier
terminal
disconnecting a, 545
interaction with, 518, 525
Hardware
supported, 72
Hardware interrupts
preferred CPU, 107
Host coalescing state machine statistics, 929
Host commands statistics, 915
HSC40 disk controller, 22
HSC50 disk controller, 22
HSC70 disk controller, 22
HSC disk controllers, 22
HSC disks, 211

I
I/O buffers
pseudoterminal, 63
I/O drivers
LAN drivers, 92
I/O functions
ACP-QIO interface, 12
codes, A1
disk, 12, 228
for LAN driver, 961
list of, A1
magnetic tape, 12, 310
terminal, 527
I/O write operations
preventing data loss, 213
unsuccessful completion, 213
INITIALIZE command, 325
Intel Ethernet devices, 97
Interface counter statistics, 912
Internal MAC receive statistics, 919
Internal MAC transmit statistics, 921
Interrupt statistics, 917
Interrupt status block, 925
IO$M_ALLOWFAST modifier, 317
IO$M_LT_QUE_CHG_NOTIF
LAT $QIO Function Modifier, 578
IO$M_ROUTE functional modifier, 986
IO$M_SENSE_MAC
Used with IO$_SENSEMODE, 989
IO$M_SENSE_MAC functional modifier, 989
IO$M_SHOW_MAP
Used with IO$_SENSEMODE, 991
IO$M_SHOW_MAP functional modifier, 991
IO$M_SHOW_ROUTE
Used with IO$_SENSEMODE, 991

Index6

IO$M_SHOW_ROUTE functional modifier, 991

IO$M_UPDATE_MAP functional modifier, 984
IO$_M_SET_MAC functional modifier, 982
IO$_SETMODE
IO$M_UPDATE_MAP, 984
IOSBs (I/O status blocks)
ACP-QIO interface, 139
disk, 239
LAN drivers, 993
LAT port driver, 582
magnetic tape, 325
mailbox, 415
returned by generic SCSI class driver, 810
terminal, 582
Itemlist read operations, 531

K
KDA50 disk controller, 22
KDB50 disk controller, 22
Keyboard control character, 54 to 57, 510
KFQSA adapter, 23

L
LANCP commands, 936
LAN drivers
addresses
destination, 962, 966
Ethernet, 939 to 941
hardware, 988
loopback assistance, 940
multicast, 939, 940, 962, 974
node, 939
physical, 939, 940, 962, 975, 988
port, 975
shared protocol destination, 971
source, 962
Token Ring, 941
AST access mode, 981
AST service routine address, 981
ATM, 95
attention AST, 981
buffer
receive, 962, 970
channel assignment, 938
characteristics
device, 960, 987
extended, 969 to 979, 988
controller mode, 971
CRC generation, 971
device characteristics, 960, 987
See also LAN, extended characteristics
driver service (802 format), 978
echo mode (DEUNA only), 972
error summary bits, 961
Ethernet, 95, 938, 939, 954
Ethernet packet format, 954

LAN drivers (contd)

Ethernet packet padding, 954
exclusive mode on Alpha systems, 959
exclusive mode on VAX systems, 955
extended characteristics, 969 to 978, 987
FDDI, 95
function codes, 961, A8
function modifiers, 965, 968, 981 to 987
hardware interface, 938
I/O functions, 962, 966, 968, 987
I/O status block, 993
IEEE 802 packet format
Class I service packet format, 956, 973
driver service parameter, 978
extended packet format, 958, 973
802 format SAP parameter, 977
group SAP parameter, 973
read function, 962
SAP use and restrictions, 958
support for, 94
user-supplied service packet format, 957,
973
write function, 966
IEEE 802 programming example, 995
initializing, 938
internal loopback mode (DELUA only), 973
loopback mode, 971
message size, 960, 964, 965, 966, 970
modify characteristics, 969
multicast address state, 974
operating, 938
packet format, 953
Class I service, 956
Ethernet, 954
extended 802, 958
IEEE 802, 956
set mode parameters, 979
SNAP SAP value, 959
user-supplied service, 957
padding
message size, 960, 965
transmit messages, 974
parameter ID, 969
packet format, 979
parameter validation, 980
port
address, 970
start, 969
privilege, 962
programming example, 995
programming notes, 994
promiscuous mode, 976, 994
rules for, 994
protocol type, 95, 962, 966, 976
access mode, 970
Compaq, 954
cross-company, 954
Ethernet, 954

LAN drivers (contd)

protocol type on Alpha systems
sharing, 959
protocol type on VAX systems
sharing, 955
read function, 962
restart, 977
sense mode function, 987
Service Access Point (SAP), 958
set controller mode
extended characteristics, 969 to 978
P2 buffer, 969
parameter ID, 969
set controller mode on Alpha systems
protocol type sharing, 959
set controller mode on VAX systems
protocol type sharing, 955
set mode function, 968
shared default mode on Alpha systems, 959
shared default mode on VAX systems, 955
shared with destination mode on Alpha
systems, 959
shared with destination mode on VAX systems,
955
shutdown controller mode, 981
shutdown port, 981
software interface, 938
status returns, A8
supported devices, 92
SYS$ASSIGN routine, 938
SYS$DASSGN routine, 939
SYS$GETDVI routine, 960
Token Ring, 95
transmit/receive buffer size, 970
unit and line status, 961
write function, 966
LAN emulation
ATM network, 933
topology, 934
LAN emulation client (LEC), 933
LAN emulation configuration server (LECS), 933
LAN emulation data frame format, 948
LAN emulation over ATM, 932
support, 935
LAN emulation server (LES), 933
LAN_FLAGS system parameter, 936
LAT $QIO, 578
LAT port driver (LTDRIVER), 51
LAT SENSEMODE $QIO Function, 560
LAT SETMODE $QIO Function, 552
Line terminator
terminal, 510

Index7

M
MAC counter statistics, 911
Magnetic tapes
function codes, A3
I/O functions
See ACP-QIO interface
status returns, A4
Mailboxes
See also Terminals
creating, 41
deleting, 43
device characteristics, 44
disable terminal, 522
driver, 41
function codes, 45, A5
function modifiers
IO$M_NORSWAIT, 49, 411
IO$M_NOW, 45, 49, 411, 413
IO$M_READATTN, 411
IO$M_READERCHECK, 49, 411, 415
IO$M_SETPROT, 414
IO$M_STREAM, 45
IO$M_WRITERCHECK, 45, 415
get mailbox information function, 415
I/O functions
IO$_READLBLK, 45
IO$_READPBLK, 45
IO$_READVBLK, 45
IO$_WRITELBLK, 49
IO$_WRITEOF, 411
IO$_WRITEPBLK, 49
IO$_WRITEVBLK, 49
I/O status block, 415
list of operations, 41
message format, 44
terminal, 519
message size, 41
permanent, 41, 43, 44
programming examples, 417
protection, 41, 44, 414
read attention AST function, 411
read function, 45
set attention AST function, 411
set protection function, 414
status returns, A5
SYS$GETDVI returns, 44
temporary, 41, 44
terminal/mailbox interaction, 518
volume protection, 414, 415
wait for writer/reader function, 414
write attention AST function, 411
write end-of-file message function, 411
write function, 49
Master adapter, 36

Index8

MAXBUF system parameter, 528, 532, 538

Message format
See Mailboxes
Modify file function, 129
MOUNT command, 325
Mount function, 135
Movefile subfunction
calling, 131
description, 131
MSCP (mass storage control protocol)
supported devices, 72
Multinational character set
See DEC Multinational character set
Multiplexers, 51
DMB32 device, 51
DMF32 device, 51
DZ11 device, 51
DZ32 device, 51

O
Out-of-band AST, 514, 549

P
Parity flag, 543
PASTHRU mode, 59, 511, 526, 529
PDQ chip
FDDI NICs, 932
Permanent mailboxes
See Mailboxes
Port access mode, 29
Ports
LAN configuration, 937
Port selection, 29
Protection
directory entry, 19
Pseudoterminals
canceling request, 62
control connection routines, D1
creating, 61
deleting, 62
device characteristics, 63
driver, 61
event notification, 66
features, 63
flow control, 65
I/O buffers, 63
programming example, 67
reading data, 64
using write with echo, 65
writing data, 65
PTD$CANCEL control connection routine, D2
PTD$CREATE control connection routine, D3
PTD$DELETE control connection routine, D6

PTD$READ control connection routine, D7

PTD$READW control connection routine, D9
PTD$SET_EVENT_NOTIFICATION control
connection routine, D10
PTD$WRITE control connection routine, D13

Q
$QIO, 578
Quota file
transfer block, 139
Quotas
AST, 228, 310, 45, 412, 545
buffered I/O, 228, 310, 45
BYTELIM, 111
direct I/O, 228, 310
disk, 137 to 138
mailbox buffer, 41, 43, 45

R
RA60 disk, 23
RA70 disk, 23
RA90 disk, 23
Radix-50 encoding, 120
RADs support
See Resource Affinity Domains support
RB02 cartridge disk, 24
RC25 disk, 24
RD53 disk, 24
RD54 disk, 24
Read/write attributes subfunction, 114
Read attention AST function, 412
Receive list placement state machine statistics,
928
Receive MAC statistics, 926
Record attributes value, 121
Resource Affinity Domains (RADs) support, 1013
Return key, 57
Rewind offline function, 319
RF30 disk, 25
RF71 disk, 25
Ring statistics, 918
RK06 cartridge disk, 25
RK07 cartridge disk, 25
RL02 cartridge disk, 24
RM03 disk, 25
RM05 disk, 25
RP05 disk, 25
RP06 disk, 25
RP07 disk, 25
RQDX3 disk controller, 23
RTPAD component of SET HOST, 512
RX01 console disk, 26
RX02 diskette, 26

RX23 diskette, 27
RX33 diskette, 27
RX50 diskette, 27
RZ22 disk, 27
RZ23 disk, 27
RZ55 disk, 27

S
SCSI (Small Computer Systems Interface)
disk class driver, 219
disks
class driver, 218
error recovery, 214, 218
handling errors in audio applications, 223
hardware compliance, 72
$QIO interface to disk class driver, 220
SCSI class/port architecture, 82
SCSI class driver, 83
SCSI command
disabling retry, 87
enabling retry, 812
padding, when required, 813
setting disconnect timeout for, 88, 813
setting DMA timeout for, 88, 813
setting phase change timeout for, 88, 813
SCSI disconnect feature
enabling, 87
SCSI port driver, 82
SCSI_NOAUTO system parameter, 89
SDI (standard disk interface), 23
Sector translation, 215
Seek operation, 213
Send data initiator state machine statistics, 929
Sense tape mode function, 319
Serial line multiplexer, 51
Set attention AST
See Attention AST
SET HOST facility, 511
Set modes
magnetic tape, 320
mailbox, 411
Set Mac qualifier, 982
terminal, 541
SET TERMINAL command, 54, 519, 526
Setting characteristics
magnetic tape, 320
terminal, 541
Shadow set virtual unit driver, 71
functions, 72
hardware configurations, 72
SHDRIVER functions, 71
Shelving
determining if file is shelvable, 118
determining if file is shelved, 118

Index9

SII integral adapter, 23

Skip file function, 317
Skip sectoring, 214
Slave formatter, 36
Small Computer Systems Interface (SCSI)
See SCSI
SONET/SDH framing, 936
SS$_ABORT return, 548, 576, 977, A3, A4,
A5, A7, A8
SS$_ACCONFLICT return, A1
SS$_ACCVIO return, 415, A5, A8
SS$_ACPVAFUL return, A1
SS$_BADATTRIB return, A1
SS$_BADCHKSUM return, A1
SS$_BADESCAPE return, 58, A7
SS$_BADFILEHDR return, A1
SS$_BADFILENAME return, A1
SS$_BADFILEVER return, A1
SS$_BADIRECTORY return, A1
SS$_BADPARAM return, 955, 959, 970, 980,
A1, A7, A8
SS$_BADQFILE return, A1
SS$_BLOCKCNTERR return, A1
SS$_BUFFEROVF return, 45, 989, A5, A8
SS$_CANCEL return, A3, A4, A5, A7
SS$_CHANINTLK return, A7
SS$_COMMHARD return, A8
SS$_CONTROLC return, 549, A7
SS$_CONTROLO return, A7
SS$_CONTROLY return, A7
SS$_CREATED return, A1
SS$_CTRLERR return, A3, A4, A8
SS$_DATACHECK return, A3, A4, A8
SS$_DATAOVERUN return, 59, 965, A3, A4,
A7, A8
SS$_DEVACTIVE, 578
SS$_DEVACTIVE return, 576, A8
SS$_DEVALLOC return, A8
SS$_DEVICEFULL return, A1
SS$_DEVINACT return, A8
SS$_DEVOFFLINE return, A4, A8
SS$_DEVREQERR, 578
SS$_DEVREQERR return, A8
SS$_DIRFULL return, A1
SS$_DIRNOTEMPTY return, A1
SS$_DISCONNECT return, A8
SS$_DRVERR return, A3, A4
SS$_DUPDSKQUOTA return, A1
SS$_DUPFILENAME return, A1
SS$_DUPUNIT return, A8
SS$_ENDOFFILE return, 318, 48, 411, 965,
A1
LAN driver status return, A8
magnetic tape status return, A4
mailbox status return, A5

Index10

SS$_ENDOFTAPE return, A4
SS$_ENDOFVOLUME return, 318, A4
SS$_EXBYTLM return, A1
SS$_EXDISKQUOTA return, A1
SS$_EXQUOTA return, 415, A5, A8
SS$_FCPREADERR return, A1
SS$_FCPREWNDERR return, A1
SS$_FCPSPACERR return, A1
SS$_FCPWRITERR return, A1
SS$_FILELOCKED return, A1
SS$_FILENUMCHK return, A1
SS$_FILEPURGED return, A1
SS$_FILESEQCHK return, A1
SS$_FILESTRUCT return, A1
SS$_FILNOTEXP return, A1
SS$_FORCEDERR return, A3
SS$_FORMAT return, A3, A4
SS$_HANGUP return, 514
SS$_HEADERFULL return, A1
SS$_IBCERROR return, A1
SS$_IDXFILEFULL return, A1
SS$_ILLCNTRFUNC return, A1
SS$_ILLIOFUNC return, 415, 576, A3, A4,
A5
SS$_INCOMPAT return, A7
SS$_INSFMAPREG return, A8
SS$_INSFMEM return, 415, A5, A8
SS$_IVADDR return, A3
SS$_IVBUFLEN return, 967, A3, A8
SS$_MBFULL return, 42, 49, 415, A5
SS$_MBTOOSML return, 415, A5
SS$_MEDOFL return, A3, A4, A8
SS$_NODISKQUOTA return, A1
SS$_NOMOREFILES return, A1
SS$_NONEXDRV return, A3, A4
SS$_NOPRIV return, 414, 415, A2, A5, A8
SS$_NOQFILE return, A2
SS$_NOREADER return, A5
SS$_NORMAL return, 415, 576, A3, A4, A7,
A8
SS$_NOSUCHFILE return, A2
SS$_NOTAPEOP return, A2
SS$_NOTLABELMT return, A2
SS$_NOTPRINTED return, A2
SS$_NOTVOLSET return, A2
SS$_NOWRITER return, A5
SS$_OPINCOMPL return, 977, A3, A4, A8
SS$_OVRDSKQUOTA return, A2
SS$_PARITY return, A3, A4, A7
SS$_PARTESCAPE return, 58, 533, A7
SS$_QFACTIVE return, A2
SS$_QFNOTACT return, A2
SS$_RCT return, A3
SS$_RDDELDATA return, A3
SS$_SERIOUSEXCP return, A2, A4
SS$_SUPERSEDE return, A2

SS$_TAPEPOSLOST return, A2
SS$_TIMEOUT return, 530, 576, 977, A3,
A4, A7, A8
SS$_TOOMANYVER return, A2
SS$_TOOMUCHDATA return, A8
SS$_UNSAFE return, A3, A4
SS$_VOLINV return, A3, A4
SS$_WASECC return, A3
SS$_WRITLCK return, A2, A3, A4
SS$_WRONGACP return, A2
Statistics block, 926
Synchronous Digital Hierarchy (SDH), 936
Synchronous Optical Network (SONET), 936
Synchronous SCSI data transfer mode
enabling, 86, 812
SYS$ASSIGN routine, 41, 518, 577, 938
SYS$CREMBX system service, 41
SYS$DASSGN routine, 43, 938
SYS$DELMBX system service, 43
SYS$DISMOU system service, 137
SYS$EWDRIVER LAN driver, 944
SYS$GETDVI routine, 38
disk, 226
LAN drivers, 960
mailbox, 44
SCSI generic class driver, 813
terminal, 520
SYS$QIO routines
format for request to SCSI generic class driver,
810
SYS$QIO system service
interface to audio functions, 220
SYSGEN (System Generation utility)
See System Generation utility
System
console terminal, 51
System Generation utility (SYSGEN)
configuring SCSI devices, 88
System parameters
LAN_FLAGS, 936

T
Tabs
Ctrl/I, 57
terminal mechanical, 522
terminal tab stops, 538
Tape class drivers
disabling the loading of, 89
Tape marks, 315, 317, 318
Tapes
function codes, 310
function modifiers
IO$M_DATACHECK, 36, 314
IO$M_INHEXTGAP, 37
IO$M_INHRETRY, 37
IO$M_REVERSE, 314
I/O functions

Tapes
I/O functions (contd)
IO$_ACCESS, 311
IO$_ACPCONTROL, 136, 311
IO$_AVAILABLE, 325
IO$_CREATE, 311
IO$_DEACCESS, 311
IO$_DSE, 311, 324
IO$_FLUSH, 311
IO$_MODIFY, 311, 324
IO$_PACKACK, 325
IO$_READLBLK, 314
IO$_READPBLK, 314
IO$_READVBLK, 314
IO$_REWIND, 316
IO$_REWINDOFF, 319
IO$_SENSEMODE, 319
IO$_SETCHAR, 320
IO$_SETMODE, 320
IO$_SKIPFILE, 317
IO$_SKIPRECORD, 318
IO$_UNLOAD, 319
IO$_WRITELBLK, 316
IO$_WRITEOF, 319
IO$_WRITEPBLK, 316
IO$_WRITEVBLK, 316
modify function, 324
sense mode function, 319
status returns, 310
Temporary mailboxes, 44
Terminal characteristics, 521 to 526
Terminals
ANSI CRT terminal, 523
autobaud detection, 519, 523
baud rates, 519, 523, 543
bell (Ctrl/G), 59
broadcast messages, 518, 522, 524, 550
carriage control, 539
command line editing, 53, 538
command recall (Ctrl/B), 54, 56
control and data signals, 516
control characters, 54 to 57, 510, 528
numeric values, C1
control key sequences, 58
cursor movement, 53, 56, 523
delete character, 53
delete line (Ctrl/U), 55, 528
device characteristics, 520, 521
categories, 527
changing, 544
extended, 523
dialup
characteristic, 522
lines, 513, 525, 545
support, 513
Digital CRT terminal, 524, 525
discard output (Ctrl/O), 55, 528, 539
driver, 51

Index11

Terminals (contd)
duplex modes, 510, 513
enable Ctrl/C AST, 545
enable Ctrl/Y AST, 545
escape sequences, 57, 582
ANSI, C9
Digital private, C9
overflow size (item code), 533
extended characteristics, 523
fallback conversion, 511, 525, 545
features, 52
form feed, 522, 538
frame size, 544
function codes, 527, A6
function modifiers
IO$M_BRDCST, 550, 582
IO$M_BREAKTHRU, 511, 539
IO$M_CANCTRLO, 55, 539
IO$M_CTRLCAST, 545
IO$M_CTRLYAST, 56, 514, 545
IO$M_CVTLOW, 529
IO$M_DSABLMBX, 529
IO$M_ENABLMBX, 539
IO$M_ESCAPE, 57, 529
IO$M_EXTEND, 529, 531
IO$M_HANGUP, 545
IO$M_INCLUDE, 520, 546, 549
IO$M_LOOP, 548
IO$M_LT_CONNECT, 552
IO$M_LT_DISCON, 552
IO$M_LT_SENSEMODE, 552
IO$M_LT_SETMODE, 552
IO$M_MAINT, 546, 548
IO$M_NOECHO, 59, 511, 526, 529
IO$M_NOFILTR, 529
IO$M_NOFORMAT, 511, 539, 548
IO$M_OUTBAND, 549
IO$M_PURGE, 529
IO$M_RD_MODEM, 580
IO$M_REFRESH, 539
IO$M_SET_MODEM, 546
IO$M_TIMED, 530
IO$M_TRMNOECHO, 530
IO$M_TT_ABORT, 520, 549
IO$M_TYPEAHDCNT, 580
IO$M_UNLOOP, 549
hangup, 514, 517, 518, 525, 545, 579
I/O functions
CTDRIVER, 538
IO$_READLBLK, 528
IO$_READPROMPT, 528
IO$_READVBLK, 528
IO$_SENSECHAR, 579
IO$_SENSEMODE, 579
IO$_SETCHAR, 541
IO$_SETMODE, 541
IO$_TTY_PORT, 552
IO$_WRITELBLK, 538

Index12

Terminals
I/O functions (contd)
IO$_WRITEPBLK, 538
IO$_WRITEVBLK, 538
I/O status block, 582
initiate login, 510
input processing, 53
insert/overstrike (Ctrl/A), 53, 57
interrupt (Ctrl/Y), 56
item codes, 532 to 537
itemlist read, 531
item codes, 532 to 537
item descriptor, 532
LAT line, 51
LAT port driver, 550
application services creation, 577
I/O functions, 552
LAT rejection codes, 584
line editing, 53, 525
See also Terminals, item codes
line feed, 538
line terminators, 510
mailbox, 518, 539
message format, 519
message types, 519
modem
characteristic, 522
control signals, 516
data signals, 516
protocol, 514
sense signals, 580
signal control, 513
no type-ahead, 522
out-of-band
See also Out-of-band AST
characters, 520
output
CTDRIVER, 512
RTPAD, 512
SET HOST, 511
output formatting, 511, 527
output processing, 510
page length and width, 542, 580
parity flag, 543
PASTHRU mode, 59, 511, 526, 529
process preservation, 517
programming examples, 586
protocol, 514
read function, 528 to 538
read verify, 57, 537
receive speed, 543
redisplay data (Ctrl/R), 56, 528
ReGIS graphics, 526
restart data (Ctrl/Q), 57
sense characteristics function, 579
sense mode function, 579
serial line multiplexer, 51
set characteristics function, 541

Terminals
set characteristics function (contd)
arguments, 541
set mode function, 541
arguments, 541
SET TERMINAL DCL command, 54, 519,
526
SIXEL graphics, 526
special operating modes, 510
status (Ctrl/T), 57
status returns, A7
stop data (Ctrl/S), 57
supported devices, 51
SYS$GETDVI returns, 520
system password, 526
tab
Ctrl/I, 57
mechanical, 522
stops, 538
terminator mask, 530, 531
time (Ctrl/T), 57
transmit speed, 543
TTY_DIALTYPE system parameter, 513,
516, 517
type-ahead, 59, 518, 521, 580
alternate buffer, 523
unsolicited data, 518
write breakthrough function, 539
write function, 538 to 541
XON/XOFF control, 526
Terminator character bit mask, 530
ThinWire, 94
Thrashing magnetic tape, 38
Timeout periods
for SCSI device, 88, 813
TMS380 chip
Token Ring NICs, 932
Token Ring
Address mappings, 941
Token Ring NICs
TMS380 chip, 932
Translations
logical to physical, 215
Transmit MAC statistics, 927
Truncate subfunction, 113
TU58 magnetic tapes
See Disks

User to network interface (UNI), 935

W
Write attention AST function, 412
Write breakthrough function, 539
Write end-of-file function
magnetic tape, 319
message, 411
Write protection
hardware, 72

X
XQP (extended QIO processor), 11

U
UDA50 disk adapter, 21
UNI
user to network interface, 935
Unload function
disk, 236
magnetic tape, 319

Index13