Digital PDFs

AA-L677A-TC

April 1983

550 pages

Original

20MB

Document:	RSX-11M/M-PLUS I/O Drivers Reference Manual
Order Number:	AA-L677A-TC
Revision:	0
Pages:	550
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/5_IOdrivers/AA-L677A-TC_ioDrvRef_198304.pdf

OCR Text

RSX-11 M/M-PLUS
1/0 Drivers Reference Manual
Order No. AA-L677 A-TC
Update Notice No. 1 (AD-L677 A-T1)

RSX-11 M Version 4.1
RSX-11 M-PLUS Version 2.1

digital equipment corporation · maynard, massachusetts

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

(§) 1979, 1981, 1983 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.

The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

DIBOL
Edusystem
!AS
MASSBUS
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

~nmnomo
ZK2251

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

800-258-1710

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

603-884-6660

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

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

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K1 G 4C2
Attn: A&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
clo Digital's local subsidiary or
approved distributor

*Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)
imerna1 oraers snou10 oe p1acea tnrough me Sottware u1stnout1on Genter (8LJG), Digital Equipment
Corporation, Northboro, Massachusetts 01532

UPDATE NOTICE NO. 1

RSX-11 M/M-PLUS 1/0 Drivers
Reference Manual
AD-L677 A-T1
April 1983

insert this page in the RSX-11 MIM-PLUS 110 Drivers Reference Manual to
maintain an up-to-date record of changes to the manual.

NEW AND CHANGED INFORMATION
This update reflects software changes and additions made in RSX-11 M Version 4.1 and RSX-11 M-PLUS
Version 2.1.
Copyright © 1983 by Digital Equipment Corporation
All rights reserved

INSTRUCTIONS
Add the following pages to the RSX-11MIM-PLUS110 Drivers Reference Manual as replacements for or
additions to current pages. The changes made on the replacement pages are indicated in the outside
margin by change bars (I) for additions, and bullets (•) for deletions. A date at the bottom of the new
pages denotes revised or new information for this update.

NEW PAGE

OLD PAGE
Title page/Copyright page
...; iii/iv through xix/xx
J, xxv/blank
,] 1-1/1-2 through 1-3/1-4
,; 1-19/1-20 through 1-25/1-26
·.J 2-1 /2-2 through 2-3/2-4

,) 2-9/2-10
,J 2-13/2-14 through 2-1712-18
··~ 2-3712-38 through 2-39/2-40
'i 5-1 /5-2 through

5-3/5-4

"8-1/8-2 through 8-7/8-8
8-13/8-14 through 8-15/8-16
'J 10-1/10-2
1

' 10-3/10-4
A-7/A-8
8-9/8-10
~· C-5/C-6 through C-7 /C-8
C-9/C-10
.) C-13/C-14
' lndex-1 /lndex-2 through
lndex-7 /blank
1
'
Readers' Comments/Mailer

,_,.title page/Copyright page
./fli/iv through xix/xx

~xv/blank
J i-111-2 through 1-3/1-4
J.1-4.1 /blank
j'1-19/1-20 through 1-25/1-26
2-1 /2-2 through 2-3/2-4
J~-4.1 /blank
-1;2-9/2-10
J/2-13/2-14 through 2-17/2-18
12-3712-38 through 2-39/2-40
, 2-40.1 /blank
V,'5-1 /5-2 through 5-3/5-4
15-4.1 /blank
J 8-1/8-2 through 8-7/8-8
J8-13/8-14 through 8-15/8-16
1./10-1 /10-2
\!10-2.1 /blank
v;10-3/10-4
\/,A-7/A-8
v'8-9/8-10
C-5/C-6 through C-7 /C-8
C-8.1 /blank
C-9/C-10
C-13/C-14
lndex-1 /lndex-2 through
lndex-7 /blank
Readers' Comments/Mailer

CONTENTS

Page
PREFACE

xxi

SUMMARY OF TECHNICAL CHANGES

xxv

CHAPTER 1

RSX-llM/M-PLUS INPUT/OUTPUT

OVERVIEW OF RSX-llM I/0
••••••••
PHYSICAL, LOGICAL, AND VIRTUAL I/O •
RSX-llM DEVICES
• • • • • •
LOGICAL UNITS
• • • •
• • • • • •
•
Logical Unit Number
• • • •
• •••
Logical Unit Table • • • • • •
Changing LUN Assignments
•••••
• •
ISSUING AN I/0 REQUEST • •
•
QIO Macro Format • • • • •
•
Significant Events • • •
System Traps • • • • • • • • • • •
DIRECTIVE PARAMETER BLOCKS •
I/0-RELATED MACROS • • • • • • • • •
The QIO$ Macro: Issuing an I/O Request
The QIOW$ Macro: Issuing an I/O Request and
Waiting for an Event Flag
••••••••••
The DIR$ Macro: Executing a Directive • • • •
1. 7. 3
The .MCALL Directive: Retrieving System Macros
1. 7 .4
The ALUN$ Macro: Assigning a LUN • • • • • • •
1. 7. 5
Physical Device Names
• • • • • • • • • • •
1.7.5.l
Pseudo-Device Names
••••••••••••
1.7.5.2
The GLUN$ Macro: Retrieving LUN Information
1. 7 .6
The ASTX$S Macro:
Terminating AST Service • •
1. 7. 7
The WTSE$ Macro: Waiting for an Event Flag
1. 7 .8
1.8
STANDARD I/O FUNCTIONS • • • • • • • •
IO.ATT: Attaching to an I/O Device • • • • • •
1.8 .1
1.8 .2
IO.DET: Detaching from an I/O Device • • • • •
IO.KIL: Canceling I/O Requests • • • • • •
1.8 .3
IO.RLB: Reading a Logical Block
••••
1.8 .4
IO.RVB: Reading a Virtual Block
1.8 .5
IO.WLB: Writing a Logical Block • • • • •
1.8.6
IO.WVB: Writing a Virtual Block • • • •
1.8. 7
User-Mode Diagnostic Functions •
1.8 .8
1.9
I/O COMPLETION • • • • • •
• • • • • • • •
1.10
RETURN CODES • • • • • •
• • • •
Directive Conditions •
• •••
1.10.1
I/O Status Conditions
••••
1.10. 2
POWER-FAIL RECOVERY PROCEDURES FOR DISKS AND
1.11
DECTAPE

1.1
1.2
1.3
1.4
1.4 .1
1.4 .2
1.4. 3
1.5
1.5 .1
1.5 .2
1.5 .3
1.6
1. 7
1. 7 .1
1. 7 .2

CHAPTER 2
2.1
2 .1.1

•
•
•
•
•
•
•
•
•

1-1
1-2
1-2
1-5
1-6
1-6
1-7
1-7
1-9
1-12
1-12
1-13
1-14
1-16
1-16
1-16
1-17
1-17
1-18
1-21
1-21
1-24
1-24
1-25
1-26
1-27
1-27
1-28
1-28
1-29
1-29
1-30
1-32
1-32
1-33
1-34
1=39

FULL-DUPLEX TERMINAL DRIVER
INTRODUCTION • • • • •
ASR-33/35 Teletypes
iii

• • 2-1
2-3

CONTENTS

Page

2 .1.2
2 .1.3
2 .1.4
2.1.5
2.1.6
2 .1. 7
2 .1.8
2 .1.9
2 .1. 9A
2 .1. 9B
2 .1.10

KSR-33/35 Teletypes •
• • • • • 2-3
LA12 Portable Terminal
• • • • • • • 2-3
LAlOO DECprinter •
• • • •
2-3
LA30 DECwriters •
• • 2-4
LA36 DECwriter • • •
• • • • • • • • •
2-4
LA34/38 DECwriters
• • • 2-4
LA120 DECwriter
• • • • •
2-4
LA180S DECprinter
• • • • •
• • • •
2-4
LQP02 Letter-Quality Printer
• • • •
2-4
LASO Personal Printer
• • • • • • • • • 2-4.1
RT02 Alphanumeric Display Terminal and RT02-C
Badge Reader/Alphanumeric Display Terminal • • 2-4.1
2.1.11
VT05B Alphanumeric Display Terminal
• • • 2-5
2.1.12
VT50 Alphanumeric Display Terminal • • • • • • • 2-5
2.1.13
VT50H Alphanumeric Display Terminal
2-5
2.1.14
VT52 Alphanumeric Display Terminal •
• 2-5
2.1.15
VTSS Graphics Display Terminal • • • • • • • • • 2-5
2.1.16
VT61 Alphanumeric Display Terminal •
• 2-5
2.1.17
VTlOO DECscope •
• • • • •
• • • • • • 2-5
2.1.18
VTlOl DECscope • • • • • • •
• • 2-6
2.1.19
VT102 DECscope • • • • • • • • • • •
• • • • 2-6
2.1.20
VT105 DECscope • • • • • •
• • • •
• • 2-6
2.1.21
VT131 DECscope • • • • • • • • • • • • • • • • • 2-6
2.2
GET LON INFORMATION MACRO • • • •
• • 2-6
2 .3
QIO MACRO • • • • • • • • • • • •
• • • • • 2-7
2.3.1
Subfunction Bits • • • • • • • • • •
• • • 2-9
2.3.2
Device-Specific QIO Functions
2-10
2.3.2.1
IO.ATA • • • • •
• • • • •
2-12
2.3.2.2
IO.ATT!TF.ESQ
• • • • • • • • 2-13
2.3.2.3
IO.CCO
• • • • • • • • 2-13
2.3.2.4
SF.GMC
• • • • 2-13
2.3.2.5
IO.GTS •
• • • •
• • • • 2-18
2.3.2.6
IO.RAL
• • • •
• • • • • • • 2-19
2.3.2.7
IO.RNE •
• • • • • • • • •
• • • • 2-20
2.3.2.8
IO.RPR
• • • •
2-20
2.3.2.9
IO.RPR!TE.BIN • • • • • • • •
• • • • • 2-20
2.3.2.10
IO.RPR!TE.XOF
2-20
2.3.2.11
IO.RST.
• • • • 2-21
2.3.2.12
SF.SMC
• • • • •
• • • • 2-21
2.3.2.13
IO.RTT
• • • •
2-22
2.3.2.14
IO.WAL
• • • • • • •
• • • • 2-22
2.3.2.15
IO.WBT •
2-22
2.3.2.16
IO.HNG • •
2-23
2.4
STATUS RETURNS
• • • •
• • • • 2-23
2.5
CONTROL CHARACTERS AND SPECIAL KEYS
2-27
2.5.1
Control Characters
• • • •
2-27
2.5.2
Special Keys • • • • • •
• • • • • • • • • 2-29
2.6
ESCAPE SEQUENCES • • • • • • • • • • • • • •
2-29
2.6.1
Definition • • • • •
• • • •
2-31
2.6.2
Prerequisites
• • • • • • •
2-32
2.6.3
Characteristics • • • • • •
2-32
2.6.4
Escape Sequence Syntax Violations
2-32
2.6.4.1
DEL or RUBOUT (177)
• • • • • •
2-32
2.6.4.2
Control Characters (0-037) • • • • • • • • • 2-33
2.6.4.3
Full Buffer • • • • • • • • • •
• • • • 2-33
2.6.5
Exceptions to Escape-Sequence Syntax
2-33
2.7
VERTICAL FORMAT CONTROL • • • • • •
2-33
2.8
AUTOMATIC CARRIAGE RETURN • • • • • •
2-34
2.9
FEATURES AVAILABLE BY RSX-llM SYSGEN OPTION
2-35
2.9.1
Private Buffer Pool Size • • • • • • •
2-35
2.9.2
Hard Receive Error Detection • • • • • • • • • 2-36
2.10
TASK BUFFERING OF RECEIVED CHARACTERS
2-36
2.11
TYPE-AHEAD BUFFERING • •
• • • • 2-37
2.12
FULL-DUPLEX OPERATION • • • • • •
2-38
2.13
PRIVATE BUFFER POOL • • • • • • •
2-38
iv

April 1983

CONTENTS
Page
2.14
2.15
2.16
2.16.1
2.16.2
2.16.3
2.16.4
2.16.5
2.17
2.11.1
2.17.2
2.17.3
2.17.4

INTERMEDIATE INPUT AND OUTPUT BUFFERING
2-38
TERMINAL-INDEPENDENT CURSOR CONTROL
2-39
TERMINAL INTERFACES • • • • • • • • • • • • • • 2-39
DHll Asynchronous Serial Line Multiplexer
2-40
DHVll Asynchronous Serial Line Multiplexer
2-40
DJll Asynchronous Serial Line Multiplexer
2-40
DLll Asynchronous Serial Line Interface
2-40
DZll Asynchronous Serial Line Multiplexer
2-40
PROGRAMMING HINTS • • • •
2-40
ESCape Code Conversion • • • • •
2-40.1
RT02-C Control Function • • • • •
2-40.l
using IO.WVB Instead of IO.WLB •
2-41
Remote DLll-E, DHll, and DZll Lines
2-41

2.17.5

Side Effects of Setting Characteristics

2-41

2.17.6

Modem Support

2-42

CHAPTER 3

• • • • • • • • • • • • •

HALF-DUPLEX TERMINAL DRIVER

INTRODUCTION • • • • • • • •
• • • 3-1
ASR-33/35 Teletypes
• • • • • • • • 3-2
KSR-33/35 Teletypes
• • • • • • • • • • 3-2
LA30 DECwriters
• • • • • • •
• 3-2
LA36 DECwriter • • • •
• • • • •
• 3-2
LA120 DECwriter
• • • • • • • • • • • • • 3-3
LA180S DECprinter
• • • • • • •
• • • 3-3
RT02 Alphanumeric Display Terminal and RT02-C
Badge Reader/Alphanumeric Display Terminal • • • 3-3
3.1.8
VT05B Alphanumeric Display Terminal
• • 3-3
3.1.9
VT50 Alphanumeric Display Terminal •
• • 3-3
3.1.10
VT50H Alphanumeric Display Terminal
• • • 3-3
3.1.11
VT52 Alphanumeric Display Terminal •
• 3-4
3.1.12
VT55 Graphics Display Terminal • • • • • • • • • 3-4
3.1.13
VT61 Alphanumeric Display Terminal • • • • • • • 3-4
3.1.14
VTlOO DECscope • • • • • •
• • • • • • • 3-4
3. 2
GET LUN INFORMATION MACRO • • • • • •
3-4
3.3
QIO MACRO • • • • • • • • • • • • •
• • 3-5
3.3.1
Subfunction Bits • • • • •
• • • •
• • • 3-7
3.3.2
Details on Device-Specific QIO Functions • • • • 3-8
3.3.2.1
IO.ATA • • • • •
• • • •
• 3-8
3.3.2.2
IO.ATT!TF.ESQ
• • • • •
3-10
3.3.2.3
IO.CCO •
• • • •
3-10
3.3.2.4
SF.GMC
• • • • • • • • • • • • • • • • 3-10
3.3.2.5
IO.GTS •
• • • •
• • • • • • 3-12
3.3.2.6
IO.RAL •
• • • • • • • •
• • • •
3-13
3.3.2.7
IO.RNE
• • • •
3-13
3.3.2.8
IO.RPR
• • • •
3-13
3.3.2.9
IO.RPR!TF.BIN
• • • •
3-14
3.3.2.10
IO.RPR!TF.XOF • • • • • • •
3-14
3.3.2.11
IO.RST.
• • • • • 3-14
3.3.2.12
SF.SMC • •
• • • • •
• • • •
3-14
3.3.2.13
IO.WAL
• • • • • • • • •
• • • • • • 3-15
3.3.2.14
IO.WBT • • • • • • • •
3-15
3.4
STATUS RETURNS
• • • • • • 3-16
3.5
CONTROL CHARACTERS AND SPECIAL KEYS • • • • • • 3-16
3.5.1
Control Characters
• • • • • • 3-20
3.5.2
Special Keys • •
• • • • • • • • • 3-22
3.6
ESCAPE SEQUENCES • • • • • • •
• • • • 3-22
3.6.l
Definition • • •
• • • •
3-22
3.6.2
Prerequisites
• • • • • • • • • • • • • • 3-24
3.6.3
Characteristics
• • • •
3-24
3~6~4
Escape Sequence Syntax Violations
• • • •
3-24
3.6.4.1
DEL or RUBOUT (177(8)) • • •
• • • • 3-24
3.6.4.2
Control Characters (0-37(8)) • • • • • •
3-25
3.6.4.3
Full Buffer
• • • • • • • • •
3-25

3.1
3 .1.1
3 .1.2
3 .1. 3
3.1.4
3 .1.5
3 .1.6
3 .1. 7

April 1983

CONTENTS

Page
Exceptions to Escape-Sequence Syntax •
3.6.5
VERTICAL FORMAT CONTROL
• • • •
3.7
FEATURES AVAILABLE BY SYSGEN OPTION • • • •
3.8
Automatic Carriage Return • • • •
3.8.1
variable-Length Buffering • • • • • • • • • •
3.8.2
Task Buffering of Received Characters • • • •
3.8.3
3.8.4
LA30-P Support • • • • • • • • • • • •
TERMINAL INTERFACES
• • • • • • • • • •
3.9
DHll Asynchronous Serial Line Multiplexer
3.9.l
DJll Asynchronous Serial Line Multiplexer
3.9.2
DLll Asynchronous Serial Line Interface
3.9.3
DZll Asynchronous Serial Line Multiplexer
3.9.4
3.10
PROGRAMMING HINTS
• • • • • • • • •
Terminal Line Truncation
3.10.l
ESCape Code Conversion • • • • •
3.10.2
RT02-C Control Function
3.10.3
Checkpointing During Terminal Input • • • • •
3.10.4
Time Required for IO.KIL • •
3.10.5
Use of I 0 • WVB • • • • • • • • • • • •
3.10.6
Remote DHll and DZll Lines • • • • • •
3.10.7
High-Order Bit on Output • • • • • •
3.10.8
Side Effects of Setting Characteristics
3.10.9
Unsolicited-Input-Character ASTs for Tasks
3.10.10
Attaching Several Terminals • • • • • •
Direct Cursor Control
•••••
3.10.11
DLll Receiver Interrupt Enable
••••
3.10.12
Loadable Driver Restrictions • • • • • • •
3.10.13
CHAPTER 4
4.1
4.2
4.3
4.3.1
4.3.1.1
4.3.1.2
4.3.1.3
4.3.1.4
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.4
CHAPTER 5
5.1
5 .1.1
5 .1. 2
5 .1.3
5 .1. 4
5 .1.5
5 .1.6
5 .1. 7
5 .1. 8
5 .1.9
5 .1.10
5.1.11
5 .1.12

5.1.13
5 .1.14

5 .1.15

3-26
3-26
3-27
3-27
3-28

3-29
3-29
3-29
3-29
3-30
3-30
3-30
3-30
3-30
3-30
3-30
3-31
3,...31
3-31
3-31
3-32
3-32
3-32
3-33
3-33
3-33

VIRTUAL TERMINAL DRIVER
INTRODUCTION • • • • • • •
GET LON INFORMATION MACRO
QIO MACRO
• • • • • •
Standard QIO Functions
IO.ATT •
IO.DET
•••••
IO.KIL
•••••••••
I 0. RLB , I 0. RVB , I 0. WLB , I 0 • WVB •
Device-Specific QIO Function (IO.STC)
SF.GMC •
IO.GTS •
IO. RPR
SF.SMC •
STATUS RETURNS

• • 4-1
4-1
• 4-2
4-4
• 4-4
4-4
• • 4-4
• • 4-4
• 4-5
• • 4-6
• • • 4-6
4-7
• 4-7
4-7

DISK DRIVERS
INTRODUCTION • • • • •
RFll/RSll Fixed-Head Disk
RS03 Fixed-Head Disk •
. . • •
RS04 Fixed-Head Disk • • • •
RP11/RP02 or RP03 Pack Disks
RM02/RM03/RM05/RM80 Pack Disk
RP04, RP05, RP06 Pack Disks
RK11/RK05 or RK05F Cartridge Disks • •
RLll/RLOl or RL02 Cartridge Disk • • • • • •
RK611/RK06 or RK07 Cartridge Disk
RXll/RXOl Flexible Disk • • • • • • • •
RX211/RX02 Flexible Disk • • •
ML-11 Disk Emulator
. . . .
UDA50/RA60/RA80/RA81 Disks •
. . . . . .
RC25 Disk Subsystem
•
RD51 Fixed 5.25 Disk/RX50 Flexible 5.25 Disk
vi

5-1
• • 5-1
. • 5-1
• 5-1
• • 5-1
5-3
• 5-3
• • 5-3
• • 5-3
• • 5-3
• • 5-4
• 5-4
. 5-4
. . 5-4
• 5-4 .1
• 5-4.1

April 1983

CONTENTS
Page
5.2
5.3
5.3.1
5.3.2
5.3.3
5.4
5.5
CHAPTER 6
6.1
6.2

6.3
6.3.1
6.3.2
6.4
6 .. 4..1
6.4.2
6.5
6.5.1
6.5.2
6.5.3
6.5.4
CHAPTER 7
7.1
7 .1.1
7 .1. 2
7.2
7.3
7.3.1
7.3.2
7.3.2.l
7.3.2.2
7.3.2.3
7.3.2.4
7.4
CHAPTER 8
8.1
8 .1.1
8 .1.2
8 .1.3
8 .1. 4
8.2
8.3
8.3.1
8.3.2
8.3.2.1
8.3.2.2
8.3.2.3
8.3.2.4
8.3.2.5
8.3.2.6
8.3.2.7
8.4
8.4.1
8.4.2
8.4.3
8.5

GET LUN INFORMATION MACRO • • • •
QIO MACRO • • • • • • • • •
Standard QIO Functions • • • • •
Device-Specific QIO Functions
•
Device-Specific QIO Function for
STATUS RETURNS • • •
• • •
PROGRAMMING HINTS
• • • • • •

• • • • • • • 5-4.1
. . • . . • 5-5
• •
• 5-5
• • • • • • • • 5-7
the RASO
• 5-8
• • • •
• 5-8
5-11

DECTAPE DRIVER
INTRODUCTION •
• • • • •
. . . . .
GET LUN INFORMATION MACRO
. . . . . . . .
QIO MACRO • • • • • • • • •
. . . . .
Standard QIO Functions • •
Device-Specific QIO Functions
STATUS RETURNS • • • • • • • •
•
DECtape Recovery Procedures
. . . . . . . . .
Select Recovery • • • •
. • . • . . . . .
PROGRAMMING HINTS • • • • • • • • . • .
.
DECtape Transfers
• • • • •
Reverse Reading and Writing
••••
Speed Considerations When Reversing Direction
Aborting a Task
• • • • • • • • • • • • • • •

. 6-1
. 6-1
. 6-2
6-2
• 6-3
• 6-4
. 6-6
• 6- 7
• 6- 7
6-7
• 6-7
• 6-7
• 6-8

DECTAPE II DRIVER
INTRODUCTION • • • •
• • •
TU58 Hardware
TU58 Driver
• • • • • •
GET LON INFORMATION MACRO
• • •
QIO MACRO • • • • • • • • • • •
Standard QIO Functions • •
Device-Specific QIO Functions
IO.WLC
• • • •
IO.RLC •
• • • •
IO.BLS
• • • •
IO.DGN
• •
STATUS RETURNS • • • • • • • • •

•
•
•
•
•

•
•
•
•

•
• • • • • •
• • • •
•
• •
•
• •

• • • • • •
•
• •
• • • •
• • • • • • • •
• • • • • •

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

MAGNETIC TAPE DRIVERS
INTRODUCTION • • • • • • • • • • • • • •
• • • 8-1
TE10/TU10/TS03 Magnetic Tape • • • • • • • • • • 8-1
TE16/TU16/TU45/TU77/TU78 Magnetic Tape
• • • 8-1
TS11/TU80 Magnetic Tape
• • • • • • 8-1
TSV05 Magnetic Tape
• • • • • • 8-2
GET LUN INFORMATION MACRO
• • • • • 8-3
QIO MACRO • • • • • • • • • • • • • • • • • • • • 8-3
Standard QIO Functions • •
8-4
Device-Specific QIO Functions
• • • • • • • • • 8-4
IO. RLV
• • • •
• • • • • • • • • • 8-4
IO.RWD
• • • • • • •
• • • 8-5
IO. RWU • • • • • • • • • • • •
• 8-5
IO.ERS •
• • • • •
• 8-6
IO.DSE
• • • •
• • 8-6
IO.SEC
• • • •
• • • • • • • •
• 8-6
IO.SMO •
• • • •
8-9
STATUS RETURNS
8-10
Select Recovery • . • • • • • • • • • • •
8-13
Retry Procedures for Reads and Writes
• • • • 8-13
Power-Fail Recovery for Magnetic Tapes •
8-14
PROGRAMMING HINTS
• • • • • • • • • • •
8-14
vii

April 1983

CONTENTS
Page
8.5.1
8.5.2
8.5.3
8.5.4
8.5.5

8 .. s . 6

8.5.7
CHAPTER 9
9.1
9.2
9.3
9.3.1
9.3.2
9.4
9.4.1
9.5
9.6
9.6.l
9.6.2
9.6.3
9.6.4
9.6.5
9.6.6
CHAPTER 10

10.1
10 .1.1
10 .1. 2
10 .1. 3
10 .1. 4
10 .1.5
10.2
10.3
10.4
10.4.1
10.5
10.6
10.6.1
10.6.2
10.6.3
CHAPTER 11
11.1
11.2
11.3
11. 3 .1
11. 3. 2
11.4
11. 4 .1
11.4.2
11. 4. 3
11.5

11. 5 .1
11.6
11. 6 .1
11.6.2
11. 7
11.7.1
11. 7. 2

Block Size • • • • • • • • • • • • • • • • • •
Importance of Resetting Tape Characteristics •
Aborting a Task • • • • • •
• • • •
Writing an Even-Parity Zero-NRZI • • • •
Density Selection • • • • • • • • • • •
End-of-Volume Status (Unlabeled Tape)
• • • •
Resetting VCK Indicator • • • • • • • •

8-14
8-15
8-15
8-15
8-15
8-15
8-16

CASSETTE DRIVER
INTRODUCTION • • • • • • •
GET LON INFORMATION MACRO
QIO MACRO • • • • • • • •
Standard QIO Functions • •
Device-Specific QIO Functions
• •
STATUS RETURNS • • • • • • • • •
Cassette Recovery Procedures
STRUCTURE OF CASSETTE TAPE •
PROGRAMMING HINTS • • • •
• •
Importance of Rewinding • • • • • • •
End-of-File and IO.SPF •
• •
The Space Functions, IO.SPB and IO.SPF
verifying of Write Operations
Block Length • • • • •
Logical End-of-Tape • • • • •

9-1
9-.1
• • 9-2
9-2
• • • • • 9-3
• • • • • 9-3

• •
• •
•

• • 9-6
• 9-6
• 9-7
• 9-7
• 9-7
• • 9-7
• • 9-8
• 9-8
• 9-8

LINE PRINTER DRIVER
INTRODUCTION • • • •
LPll Line Printer
LSll Line Printer
LVll Line Printer
LA180 DECprinter • • • • •
LNOl Laser Printer •
GET LON INFORMATION MACRO
QIO MACRO • • • • • • •
STATUS RETURNS • • • • •
Ready Recovery • • • • •
VERTICAL FORMAT CONTROL
PROGRAMMING HINTS
RUBOUT Character • • •
• • • •
Print Line Truncation • • • • •
Aborting a Task

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

CARD READER DRIVER
INTRODUCTION • • • • • • •
GET LON INFORMATION MACRO
QIO MACRO • • • • • • • • •
Standard QIO Functions •
Device-Specific QIO Functions
• • •
STATUS RETURNS • • • • • • • • • • • • • •
Card Input Errors and Recovery •
Ready and Card Reader Check Recovery
I/O Status Conditions • • • • • • • • •
FUNCTIONAL CAPABILITIES
•
Control Characters
• •
CARD READER DATA FORMATS •
• • • •
Alphanumeric Format (026 and 0211)
Binary Format • • • • • • • • • • • • •
PROGRAMMING HINTS • • •
• • • •
Input Card Limitation
•
Aborting a Task
viii

11-1
11-1
11-2
11-2

• • •
• • •

11-3
11-3
11-3
11-4
11-7
11-8
11-8
11-9
11-9
11-9
11-9

• • • 11-9
• 11-10
April 1983

CONTENTS
Page
MESSAGE-ORIENTED COMMUNICATION DRIVERS

CHAPTER 12

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

INTRODUCTION
12.1
DAll-B Parallel Interface
12.1.1
DLll-E Asynchronous Line Interface
12 .1. 2
DMCll Synchronous Line Interface
12 .1.3
DPll Synchronous Line Interface
12 .1. 4
DQll Synchronous Line Interface
12 .1. 5
12 .1. 6
DUll Synchronous Line Interface
12 .1. 7
DUPll Synchronous Line Interface
12.2
GET LUN INFORMATION MACRO
QIO MACRO
12.3
Standard QIO Functions
12.3.1
oevice-Specif ic QIO Functions
12.3.2
IO.FOX
12.3.2.1
12.3.2.2
IO.HDX
12.3.2.3
IO. INL and IO.TRM
12.3.2.4
IO.RNS
12.3.2.5
IO.SYN
12.3.2.6
IO.WNS
12.4
STATUS RETURNS
12.5
PROGRAMMING HINTS
Transmission Validation
12.5.1
Redundancy Checking
12.s.2
Half-Duplex and Full-Duplex Considerations
12.5.3
12.5.4
Low-Traffic Sync Character Considerations
vertical Parity Support
12.5.5
Power fail with DMCll
12.5.6
Importance of IO. INL
12.5.7
PROGRAMMING EXAMPLE
12.6

12-1
12-2
12-2
12-3
12-3
12-3
12-3
12-4
12-4
12-5
12-5
12-5
12-7
12-7
12-7
12-7
12-8
12-8
12-8
12-11
12-11
12-11
12-11
12-12
12-12
12-12
12-12
12-13

13.1
INTRODUCTION • • • • • • •
13.1.1
PCLll-B Hardware • • • • •
13.1.2
PCLll Transmitter Driver •
• • • • • •
13.1.3
PC-Lll Receiver Driver
• • • • • • • • • •
13.2
GET LUN INFORMATION MACRO
• • • •
13.3
QIO MACRO -- PCLll TRANSMITTER DRIVER FUNCTIONS
13.3.1
Standard QIO Functions • • •
13.3.2
Device-Specific QIO Functions
13.3.2.1
IO.ATX • •
• • • •
• • • •
13.3.2.2
IO.SEC • • • • • • • • • • • •
• • • •
13.3.2.3
IO.STC • • • • • • • • • • • • • • • •
13.4
PCLll TRANSMITTER DRIVER STATUS RETURNS
• • • •
13.5
QIO MACRO -- PCLll RECEIVER DRIVER FUNCTIONS • •
13.5.1
Standard QIO Functions • • • • •
13.5.2
Device-Specific QIO Functions
13.5.2.1
IO.CRX •
• •
13.5.2.2
IO.RTF • •
• • • • •
• ••
13.5.2.3
IO.ATF •
• • • • • •
•
13.5.2.4
IO.DRX • •
• ••••••••••
13.6
PCLll RECEIVER DRIVER STATUS RETURNS •
•

13-1
13-1
13-1
13-1
13-2
13-3
13-3
13-3
13-5
13-5
13-5
13-6
13-8
13-8
13-9
13-10
13-10
13-10
13-11
13-11

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

CHAPTER 13

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

CHAPTER 14

ANALOG-TO-DIGITAL CONVERTER DRIVERS

14.1
14 .1.1
14 .1. 2
,

.....

.L':t • L

14.3

INTRODUCTION • • • • • • • • • • • •
AFCll Analog-to-Digital Converter
ADOl-D Analog-to-Digital Converter • •
GET LUN INFORMATION MACRO
• • • •
QIO MACRO • • • • • • • • • • • • • •

14-1
14-1
14-1
14-2
14-2

CONTENTS
Page
14.3.1
14.3.2
14.4
14.4.1

Standard QIO Function
Device-Specific QIO Function
FORTRAN INTERFACE • • • • • •
Synchronous and Asynchronous Process Control

14.4.2
14.4.3
14.4.4

The isb Status Array • • • • • • • • • • • • •
FORTRAN Subroutine Summary • • • • • • • • • •
AIRD/AIRDW: Performing Input of Analog Data in
Random Sequence • • • • • • • • • • • • • • •
AISQ/AISQW: Reading Sequential Analog Input
Channels • • • • • • • • •
ASADLN: Assigning a LON to the ADOl-D
ASAFLN: Assigning a LON to the AFCll
STATUS RETURNS • • • • • • •
FORTRAN Interface Values •
FUNCTIONAL CAPABILITIES
• • • • • •
•
Control and Data Buffers •
• • • • • •
PROGRAMMING HINTS
• • • • •
• •
use of A/D Gain Ranges • •
• • • • • • •
Identical Channel Numbers on the AFCll •
•
AFCll Sampling Rate • • • •
• • • •
•
Restricting the Number of ADOl-D Conversions •

I/O

14.4.5
14.4.6
14.4.7
14.5
14.5.1
14.6
14.6.1
14.7
14.7.1
14.7.2
14.7.3
14.7.4
CHAPTER 15

• •

• • • •

• • • • •

• • • •

14-2
14-2
14-3
14-3
14-4
14-4

14-5
14-6
14-7
14-7
14-8
14-9
14-10
14-10
14-10
14-10
14-10
14-11
14-11

UNIVERSAL DIGITAL CONTROLLER DRIVER

15.1
INTRODUCTION • • • • • • • • •
15-1
15.1.1
Creating the UDCll Driver
15-1
15.1.2
Accessing UDCll Modules • • • • • • • • • • • 15-2
15.1.2.1
Driver Services
15-2
15.1.2.2
Direct Access
••••••••
15-3
15.2
GET LUN INFORMATION MACRO
15-3
15.3
QIO MACRO • • • • • • • •
• • • • • • 15-3
15.3.1
Standard QIO Function • • • • • • •
15-3
15.3.2
Device-Specific QIO Functions
••••
15-3
15.3.2.1
Contact Interrupt Digital Input
(W733
Modules)
• • • • . • • • •
15-6
Timer (W734 I/O Counter Modules) •
15.3.2.2
15-7
Latching Digital Output (M685, M803, and
15.3.2.3
M805 Modules)
• • • • • • • • • • • •
15-8
Analog-to-Digital Converter (ADUOl Module) • 15-8
15.3.2.4
ICSll Analog-to-Digital Converter
(IAD-IA
15.3.2.5
Module)
• • • • • • • • • • •
15-8
15.4
DIRECT ACCESS • • • • • • • • • • • • • • • • • 15-9
Defining the UDCll Configuration • •
15.4.1
• • 15-10
Assembly Procedure for UDCOM.MAC •
15.4.1.1
• • 15-10
Symbols Defined by UDCOM.MAC • • •
15.4.1.2
• 15-10
Including UDCl Symbolic Definitions in the
15.4.2
System Object Module Library • • • • •
• 15-12
Referencing the UDCll through a Global Common
15.4.3
Block
• • • • • • • • • . • •
• • 15-12
15.4.3.l
Creating a Global Common Block • • •
• 15-12
15.4.3.2
Making the Common Block Resident •
• • 15-13
15.4.3.3
Linking a Task to the UDCll Common Block • • 15-14
15.5
FORTRAN INTERFACE • • • • • • • • • •
• • 15-14
15.5.1
Synchronous and Asynchronous Process Control
I/O • • • • • • • • • • •
• • • . . • . 15-15
The isb Status Array • • • • • • • • • . • • • 15-15
15.5.2
FORTRAN Subroutine Summary • • • • • • • • • • 15-16
15.5.3
AIRD/AIRDW: Performing Input of Analog Data in
15.5.4
Random Sequence
• • • • • • • • •
• 15-17
AISQ/AISQW:
Reading Sequential Analog Input
15.5.5
Channels • • • • • • • • . • • . • .
• • 15-18
AO/AOW: Performing Analog Output • •
15-19
15.5.6
ASUDLN: Assigning a LUN to the UDCll
• 15-20
15.5.7

CONTENTS
Page
15.5.8
15.5.9
15.5.10
15.5.11
15.5.12
15.5.13
15.5.14
15.5.15
15.5.16
15.5.17
15.5.18
15.5.19
15.5.20
15.5.21
15.6
15.6.1
15.7
15.7.1
15.7.2
CHAPTER 16

CTDI: Connecting to Contact Interrupts • • • • 15-20
CTTI: Connecting to Timer Interrupts • • • • • 15-21
DFDI: Disconnecting from Contact Interrupts • 15-22
DFTI: Disconnecting from Timer Interrupts
• • 15-23
DI/DIW: Reading Several Contact Sense Fields • 15-23
DOL/DOLW: Latching or Unlatching Several
Fields . . . . . . . . . . . . . .
• • • 15-24
DOM/DOMW: Pulsing Several Fields • • • • • • • 15-25
RCIPT: Reading a Contact Interrupt Point • • • 15-25
RDCS: Reading Contact Interrupt
Change-of-State Data from a Circular Buffer • 15-26
RDDI: Reading Contact Interrupt Data from a
Circular Buffer • • • • • • . • • • • • • • • 15-27
RDTI: Reading Timer Interrupt Data from a
Circular Buffer • • • • • • • • • • • • . • • 15-28
RDWD:
Reading a Full Word of Contact
Interrupt Data from the Circular Buffer
• 15-29
RSTI: Reading a Timer Module • • •
• • 15-30
SCTI: Initializing a Timer Module • • • • • • 15-30
STATUS RETURNS • • • • • • •
• • • • • • 15-31
FORTRAN Interface Values
• • • •
15-33
PROGRAMMING HINTS • • • • •
• • • • • 15-34
Numbering Conventions
• 15-34
Processing Circular Buffer Entries •
• • • 15-34
LABORATORY PERIPHERAL SYSTEMS DRIVERS

16.1
INTRODUCTION • • • • • • • • • • • • • • • • • • 16-1
16.1.1
ARll Laboratory Peripheral System • • • • • • 16-2
16.1.2
LPSll Laboratory Peripheral System
• • • • 16-2
16.2
GET LUN INFORMATION MACRO
• • • • • • 16-2
16.3
QIO MACRO • • • • • • • • • • • • • •
16-2
16.3.1
Standard QIO Function • • • • • • • . •
16-2
16.3.2
Device-Specific QIO Functions (Immediate)
16-3
16.3.2.1
IO.LED
• • • •
• • • • • • • • • • 16-4
16.3.2.2
IO.REL • • • • • • • • • •
• • • • • 16-4
16.3.2.3
IO.SDI • • • • •
16-4
16.3.2.4
IO.SDO • • •
• • • • • • 16-4
16.3.3
Device-Specific QIO Functions (Synchronous)
16-4
16.3.3.1
IO.ADS •
• • • • • • •
• • • • • 16-6
16.3.3.2
IO.HIS • •
• • • • •
• • • • • 16-7
16.3.3.3
IO.MDA •
16-8
16.3.3.4
IO.MDI • •
• • • • • • • •
16-8
16.3.3.5
IO.MOO • • • • • • • • • • • • • •
16-8
16.3.4
Device-Specific QIO Function (IO.STP)
16-9
16.3.4.1
IO.STP • • • • • •
• • • • 16-9
16.4
FORTRAN INTERFACE • • • • • • • • •
• • • • 16-9
16.4.1
The isb Status Array • • • • • • • • • • • • • 16-9
16.4.2
Synchronous Subroutines • • • •
• • • • • 16-10
16.4.3
FORTRAN Subroutine Summary •
• • 16-11
16.4.4
ADC: Reading a Single A/D Channel
• • 16-12
16.4.5
ADJLPS: Adjusting Buffer Pointers
• 16-13
16.4.6
ASLSLN: Assigning a LUN to LSO:
• • • 16-13
16.4.7
ASARLN: Assigning a LUN to ARO:
•• 16-14
16.4.8
CVSWG: Converting a Switch Gain A/D Value to
Floating-Point • • • • • • • • • • • • • • • • 16-15
DRS: Initiating Synchronous Digital Input
16.4.9
Sampling • • • • • • • • • • • • • • • • • • • 16-15
HIST: Initiating Histogram Sampling (LPSll
16.4.10
only)
• • • • • • • • • • • • • • • •
• 16-17
!DIR: Reading Digital Input
: : • •
• . 16=19
16.4.11
16.4.12
!DOR: Writing Digital Output
• • • • • • • 16-20
IRDB: Reading Data from an Input Buffer
• 16-20
16.4.13
16.4.14
LED: Displaying in LED Lights (LPSll only) • • 16-21

CONTENTS
Page
16.4.15
16.4.16
16.4.17
16.4.18
16.4.19
16.4.20
16.5
16.5.1
16.5.2
16.5.3
16.5.4
16.6
16.6.1
16.6.2
16.6.3
16.6.4
CHAPTER 17
17.1
17.2
17.3
17.4
17.4.1
17.4.2
17.5
17.5.1
17.5.2
CHAPTER 18

LPSTP: Stopping an In-Progress Synchronous
Function • • • • • • • • • • • • • • • • • • • 16-22
POTO: Putting a Data Item into an Output
Buffer • • • • • • • • • • • • • • • • • • • • 16-22
RELAY: Latching an Output Relay (LPSll only) • 16-22
RTS: Initiating Synchronous A/D Sampling • • • 16-23
SDAC: Initiating Synchronous D/A Output
• 16-25
SDO: Initiating Synchronous Digital Output • • 16-27
STATUS RETURNS • • • • • • • • •
• 16-29
IE.RSU • • • • • • • • • • • • • • • •
• 16-31
Second I/O Status Word • • • • • •
• 16-31
IO.ADS and ADC Errors
• • • • • • • • • 16-32
FORTRAN Interface Values •
• • 16-33
PROGRAMMING HINTS • • • • • • • • • • • • • • • 16-33
The LPSll/ARll Clock and Sampling Rates • • • 16-33
Importance of the I/O Status Block • • • • • • 16-34
Buff er Management
• • • • • • • •
• 16-35
use of ADJLPS for Input and Output •
• • 16-36
PAPER TAPE READER/PUNCH DRIVERS
INTRODUCTION • • • • • • •
GET LON INFORMATION MACRO
QIO MACRO • • • •
STATUS RETURNS • • •
Error Conditions • • • •
Ready Recovery • • • • •
PROGRAMMING HINTS • • • •
Special Action Resulting
Reading Past End-of-Tape

•

17-1
17-1
17-2
17-3
•
17-4
17-4
• • • • • • • • • • • 17-5
from Attach and Detach 17-5
• • • • • •
17-5

INDUSTRIAL CONTROL SUBSYSTEMS

18.1
INTRODUCTION • • • • • • • • • • • • • • •
18-1
Hardware Configuration • • • • •
18-1
18 .1.1
ICS/ICR Address Assignments
• • • •
18-1
18.1.1.1
DSS/DRS Address Assignments
18-2
18.1.1.2
Supported ICS/ICR I/O Modules
18-3
18.1.1.3
Alternate ICSll Support
18-3
18 .1. 2
Software Support • • • • • • • •
18-4
18 .1. 3
UDCll Software Compatibility • •
18-6
18.1.4
Module Addressing Conventions
18-6
18 .1. 5
18.2
LON INFORMATION • • • • • • • •
18-8
ASSEMBLY LANGUAGE INTERFACE
18-8
18.3
General Error Status Returns • •
• • 18-12
18.3.l
Directive Conditions • • •
• • 18-12
18.3.1.1
18.3.1.2
I/O Conditions • • • • • • • • • • •
• • 18-13
18.3.2
A/D Input - Read Multiple A/D Channels • • • • 18-13
Analog Output
~ ~ ~ • • • • • • • • • • • • • 18-15
18.3.3
Momentary Digital Output - Multi-Point • • • • 18-16
18.3.4
Bistable Digital Output - Multi-Point
18-17
18.3.5
18.3.6
Unsolicited Interrupt Processing • • • • • • • 18-17
Connect to Digital Interrupts
• • • •
• 18-19
18.3.6.1
Disconnect from Digital Interrupts •
18-20
18.3.6.2
Connect to Counter Module Interrupts •
• 18-21
18.3.6.3
Set Counter Initial Value • • • •
18-22
18.3.6.4
Disconnect from Counter Interrupts •
18-22
18.3.6.5
Connect to Terminal Interrupts • • • • • , • 18-23
18.3.6.6
Disconnect from Terminal Input • • • •
• 18-24
18.3.6.7
Activating a Task by Unsolicited Interrupts • 18-24
18.3.7
Link a Task to Digital Interrupts
• 18-25
18.3.7.1
Link a Task to Counter Interrupts
• . 18-26
18.3.7.2
Link a Task to Terminal Interrupts
• • • 18-27
18.3.7.3
xii

CONTENTS
Page
18.3.7.4
Link a Task to Error Interrupts
• • • • 18-27
18.3.7.5
Read Activating Data • • • • • • •
18-28
18.3.8
Unlink a Task from Interrupts
• • 18-29
18.3.8.1
Unlink a Task from All Interrupts • • • • • 18-30
18.3.8.2
Unlink a Task from all Digital Interrupts
• 18-30
18.3.8.3
Unlink a Task from Counter Interrupts
• • • 18-30
18.3.8.4
Unlink a Task from Terminal Interrupts
• 18-31
18.3.8.5
Unlink a Task from Error Interrupts
• • 18-31
18.3.9
Terminal Output
• • • • • •
• • • 18-32
18.3.10
Maintenance Functions
• • • • • •
18-32
18.3.10.1
Disable Hardware Error Reporting •
• o • 18-32
18.3.10.2
Enable Hardware Error Reporting
• • • • • • 18-33
18.3.11
Special Functions
• • • • • •
• • 18-33
18.3.11.1
I/O Rundown
• • •
• 18-33
18.3.11.2
Kill I/O • • • • • • • • • • •
• • • 18-33
18.4
FORTRAN INTERFACE
• • • •
• • • • • 18-34
18.4.1
Synchronous and Asynchronous Process Control
I/0 • • • • • • • • • • •
• • • 18-35
18.4.2
Return Status Reporting
• • • • • • • • • 18-35
18.4.3
Optional Arguments • • •
• • • • •
• 18-37
18.4.4
Assigning Default Logical and Physical Units
for Input and Output - ASICLN/ASUDLN (ICS/ICR)
and ASISLN (DSS/DRS) • • • • • • • • • • • • • 18-38
18.4.5
Analog Input • • • • • • • • • • • • • • •
18-40
18.4.5.1
AIRD/AIRDW: Analog Input - Specified
Channel Sequence • • • • • • • • • • • • • • 18-40
18.4.5.2
AISQ/AISQW: Analog Input - Sequential
Channel Sequence • • • • • • • • • • • • • • 18-43
18.4.6
AO/AOW: Analog Output - Multichannel • •
• 18-45
18.4.7
DOL/DOLW: Digital Output - Bistable Multiple
Fields • • • • • • • • • • • • • • • • • • • • 18-46
18.4.8
Digital Input
• • • • • • • • • • • • •
• 18-48
18.4.8.1
DI/DIW: Digital Input - Digital Sense
Multiple Fields
• • • • • • • • • • •
• 18-48
18.4.8.2
RCIPT: Digital Input - Digital Interrupt
Single-Point • • • • • • • • • • • • • • • • 18-49
18.4.9
DOM/DOMW: Digital Output Momentary - Multiple
Fields • • • • • • • • • • • • • • • • •
• 18-50
18.4.10
RTO/RTOW: Remote Terminal Output • • • •
18-51
18.4.11
Unsolicited Interrupt Data - Continual
Monitoring • • • • • • • • • • • • • •
• • 18-52
18.4.11.1
CTDI: Connect a Buffer for Receiving Digital
Interrupt Data • • • • • • • • • • •
• • 18-52
18.4.11.2
Reading Digital Interrupt Data • • •
• 18-53
DFDI: Disconnect a Buffer from Digital
18.4.11.3
Interrupts • • • • • • • • • • • • • • • • • 18-57
CTTI: Connect a Buffer for Receiving
18.4.11.4
Counter Data • • • • • • • • • • • • • • • • 18-57
RDTI:
Read Counter Data from the Circular
18.4.11.5
Buffer • • • • • • • • • • • • • • • • • • • 18-59
18.4.11.6
Miscellaneous Counter Routines • • • • • • • 18-59
18.4.11.7
DFTI: Disconnect a Buffer from Counter
Interrupts • • • • • • • • • • • • • • • • • 18-60
18.4.11.8
CTTY: Connect a Circular Buffer to Terminal
Interrupts • • • • • • • • •
• • • • • • 18-61
18.4.11.9
RDTY:
Read a Character from the Terminal
Buffer • • • • • • • • • • • • • • • • • • • 18-62
18.4.11.10 DFTY: Disconnect a Circular Buffer from
Terminal Input c e e = e e e
•
•
•
•
•
•
•
18-63
18.4.11.11 Programming Example • • • • • • • • •
• 18-63
18.4.12
unsolicited Interrupt Processing - Task
Activation • • • • • • • • • • •
• 18-65
18.4.12.1
LNK: Link a Task to Interrupts
18-65
18.4.12.2
RDACT: Read Activation Data • • • • • • • • 18-67
18.4.12.3
UNLNK:
Remove Interrupt Linkage to a Task • 18-69
xiii

CONTENTS
Page
18.4.13
Maintenance Functions • • • • • • • • • •
18-70
18.4.13.1
OFLIN: Place Selected Unit in Offline
Status • • • • • • • •
• • • •
18-71
18.4.13.2
ONLIN: Return a Device to On-line Status • 18-71
18.5
ERROR DETECTION AND RECOVERY •
• • • • • 18-71
18.5.1
Serial Line Errors • • • • •
• • • • • • . 18-72
18.5.2
Power-Fail at a Remote Site
• • • • •
18-72
18.5.3
Power Recovery at the Processor
• • • • • • • 18-73
18.5.4
Unit in Off-line Status • • • • • • • • • • • 18-73
18.5.5
Error Data - !CSR and !CAR Registers • •
• 18-74
18.6
DIRECT ACCESS • • • • • • • • • • • •
• • 18-75
18.6.1
Linking a Task to the ICS/ICR Common Block • • 18-77
18.6.2
Accessing the I/O Page • • • •
• 18-77
18.6.2.1
Mapping Table Format • • • •
• • 18-78
18.6.2.2
I/O Page Global Definitions • • • • •
• 18-78
18.6.2.3
Sample Subroutine • • • • • •
• • 18-79
18.7
CONVERSION OF EXISTING SOFTWARE
• • • 18-81
18.7.1
Features • • • • • •
• • • • • • • • 18-81
18.7.2
Module Support • • •
• • • •
• 18-81
18.7.2.1
!AD-IA A/D Converter and IMX-IA Multiplexer 18-81
18.7.2.2
16-Bit Binary Counter
• • • • • • • • 18-82
18.7.2.3
Bistable Digital Output
•• 18-82
18.7.2.4
Momentary Digital Output • • • • • • • • • • 18-82
18.7.2.5
Noninterrupting Digital Input • • • • •
18-83
18.7.2.6
Analog Output
• 18-83
18.7.2.7
Interrupting Digital Input • • • • • • • • • 18-83
CHAPTER 19

NULL DEVICE DRIVER

CHAPTER 20

GRAPHICS DISPLAY DRIVER

20.1
20 .1.1
20 .1. 2
20.2
20.3
20.4
20.5
CHAPTER 21

INTRODUCTION • • • • • • • • • • •
VTll Graphics Display Subsystem
VS60 Graphics Display Subsystem
GET LUN INFORMATION MACRO
QIO MACRO • • • • • • • • •
STATUS RETURNS • •
PROGRAMMING HINTS

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

LABORATORY PERIPHERAL ACCELERATOR DRIVER

INTRODUCTION • • • • • • • • • • • • • • •
21.1
21-1
LPAll-K Dedicated Mode of Operation
21-1
21.1.1
LPAll-K Multirequest Mode of Operation •
21.1.2
21-1
GET LUN INFORMATION MACRO • • • • •
• • • • 21-2
21.2
THE PROGRAM INTERFACE • • • • • • • • • • • • • 21-2
21.3
FORTRAN Interface • • • • • • • • • • •
21-2
21.3.1
ADSWP: Initiate Synchronous A/D Sweep
21.3.l.l
21-3
CLOCKA: Set Clock A Rate •
• • • •
21-7
21.3.1.2
CLOCKB: Control Clock B • • • • • • • •
21-7
21.3.1.3
CVADF: Convert A/D Input to Floating
21.3.1.4
Point • • • • • • • • • • • • • • • • •
21-9
DASWP: Initiate Synchronous D/A Sweep
21-9
21.3.1.5
DISWP: Initiate Synchronous Digital Input
21.3.1.6
Sweep • • ~ ~ e • • • • • • • • • • • • • • 21-12
DOSWP: Initiate Synchronous Digital Output
21.3.1.7
Sweep
• • • • • • • • • • • • • • •
• 21-14
FLT16: Convert Unsigned Integer to a Real
21.3.1.8
Constant • • • • • • •
• • • • • • 21-17
IBFSTS: Get Buffer Status
• • • • • • 21-17
21.3.1.9
IGTBUF: Return Buffer Number •
• • • • • 21-17
21.3.1.10
INXTBF: Set Next Buffer
• • • • • • 21-18
21.3.1.11
xiv

CONTENTS
Page
IWTBUF: Wait for Buffer
• 21-19
21.3.1.12
LAMSKS: Set Masks Buffer
• • 21-20
21.3.1.13
RLSBUF: Release Data Buffer
• • • • • 21-21
21.3.1.14
RMVBUF: Remove Buffer from Device Queue
• • 21-22
21.3.1.15
SETADC: Set Channel Information
• 21-22
21.3.1.16
SETIBF: Set Array for Buffered Sweep
• 21-23
21.3.1.17
STPSWP: Stop Sweep • • • • • • • • •
• 21-24
21.3.1.18
XRATE: Compute Clock Rate and Preset
• • 21-25
21.3.1.19
21.3.2
MACR0-11 Interface • • • • • • • • • •
• • 21-26
Accessing Callable LPAll-K Support Routines 21-26
21.3.2.1
Standard Subroutine Linkage and CALL Op
21.3.2.2
Code
• • • • • • • • • • • • •
• 21-27
21.3.2.3
Special-Purpose Macros • • • • •
• 21-27
21.3.2.4
Device-Specific QIO Functions
• • 21-28
21.3.2.5
IO.CLK
• • • •
• • • •
• 21-29
21.3.2.6
IO.IN!
• • • • •
• • 21-29
21.3.2.7
IO.LOO •
• • • • •
• • • • 21-29
2le3o2=8
IO.STA •
• • • • • 21-30
21.3.2.9
IO.STP •
• • • •
21-30
21.3.3
The I/O Status Block (IOSB)
• • • • • 21-30
21.4
BUFFER MANAGEMENT
• • 21-32
21.5
LOADING THE LPA-11 MICROCODE •
• 21-34
21.6
UNLOADING THE DRIVER • • • •
• • • • • 21-35
21.7
TIME-OUT OF THE LPAll-K
• 21-35
21.8
22-BIT ADDRESSING SUPPORT
• • • •
• 21-36
21.9
SAMPLE PROGRAMS
• • . • • •
• • • • • 21-37
CHAPTER 22

K-SERIES PERIPHERAL SUPPORT ROUTINES

22.1
INTRODUCTION • • • • • • • • • • • •
22.1.1
K-Series Laboratory Peripherals
22.1.1.1
AAll-K D/A Converter • • • • • •
22.1.1.2
ADll-K A/D Converter • • • • • •
22.1.1.3
AMll-K Multiple Gain Multiplexer • • • • • •
22.1.1.4
DRll-K Digital I/O Interface • •
22.1.1.5
KWll-K Dual Programmable Real-Time Clock
22.1.2
Support Routine Features • • • • • •
22.1.3
Generation and Use of K-Series Routines
22.1.3.1
Generation of K-series Support Routines
22.1.3.2
Program Use of K-series Routines • • •
22.2
THE PROGRAM INTERFACE
• • • • • • • •
22.2.l
FORTRAN Interface
• • • • • • • • • • • • • •
22.2.1.1
ADINP: Initiate Single Analog Input
22.2.1.2
ADSWP: Initiate Synchronous A/D Sweep
22.2.1.3
CLOCKA: Set Clock A Rate • • • • • •
• •
22.2.1.4
CLOCKB: Control Clock B • • • • • • • • • •
22.2.1.5
CVADF: Convert A/D Input to Floating Point •
22.2.1.6
DASWP: Initiate Synchronous D/A Sweep • • •
22.2.1.7
DIGO: Digital Start Event • • • • • • • • •
22.2.1.8
DINP: Digital Input
••••••••••••
22.2.1.9
DISWP: Initiate Synchronous Digital Input
Sweep • • • • • • • • • • • • • • • •
•
DOSWP:
Initiate Synchronous Digital
22.2.1.10
Output Sweep • • • • •
•
DOUT: Digital Output • • • • •
• •
22.2.1.11
FLT16: Convert Unsigned Integer to a Real
22.2.1.12
Constant • • • • • • • • • • • • • • • • • •
GTHIST: Gather Interevent Time Data
22.2.1.13
• •
IBFSTS: Get Buffer Status
• •
22.2.1.14
22.2.1.15
ICLOKB: Read 16-bit Clock • • • • •
• •
22.2.1.16
IGTBUF~ Return Buffer Number • • • • • •
22.2.1.17
INXTBF: Set Next Buffer
•
IWTBUF: Wait for Buffer
•••••••• • •
22.2.1.18
22.2.1.19
RCLOKB: Read 16-bit Clock • • • • •
•
xv

22-1
22-1
22-2
22-2
22-2
22-2
22-3
22-3
22-4
22-5
22-5
22-6
22-7
22-8
22-8
22-11
22-12
22-13
22-14
22-16
22-16
22-17
22-19
22-20
22-21
22-21
22-23
22-23
22-24
22-25
22-25

CONTENTS
Page
RLSBUF: Release Data Buffer
• • • • •
22-26
22.2.1.20
RMVBUF: Remove Buffer from Device Queue 22-26
22.2.1.21
SCOPE: Control Scope • • • • • . • • • • • • 22-27
22.2.1.22
SETADC: Set Channel Information
22-28
22.2.1.23
SETIBF: Set Array for Buffered Sweep •
• 22-28
22.2.1.24
STPSWP: Stop Sweep • • • • • • • • • • • • • 22-29
22.2.1.25
XRATE: Compute Clock Rate and Preset • • • • 22-30
22.2.1.26
MACR0-11 Interface • • • • • • •
• • 22-31
22.2.2
Standard Subroutine Linkage and CALL Op
22.2.2.1
Code • • • • • • • •
• . • • • • • 22-31
Special-Purpose Macros • • •
• • • 22-31
22.2.2.2
The I/O Status Block (IOSB)
• • 22-32
22.2.3
BUFFER MANAGEMENT • • • • • •
• • • • • • • 22-32
22.3
22.4
SAMPLE FORTRAN PROGRAMS
• • • •
• 22-33
Sample Program Using Event Flag • • • •
22.4.1
• 22-34
Sample Program Using Completion Routine
22.4.2
• 22-35
CHAPTER 23

UNIBUS SWITCH DRIVER

23.l
INTRODUCTION • • • • • • • • • • •
23.1.l
DT07 UNIBUS Switches
23.1.2
UNIBUS Switch Driver • • • • • • • • •
23.2
GET LUN INFORMATION MACRO
23.3
QIO MACRO
•••••
23.3.1
Standard QIO Functions •
23.3.1.1
IO.ATT
.•••••••
23 • 3 •1 • 2
I 0. DET
• • • • •
• • • • •
23.3.1.3
IO.KIL
•••••
23.3.2
Device-Specific QIO Functions
23.3.2.1
IO.CON
23.3.2.2
IO.DIS • • • • • • •
23.3.2.3
IO.DPT
23.3.2.4
IO.SW! •
23.3.2.5
IO.CSR •
• ••••
23.4
POWER-FAIL RECOVERY
23.4.1
System Power-Fail Recovery •
23.4.2
UNIBUS Power-Fail Recovery •
23.5
STATUS RETURNS
•••••
23.6
FORTRAN USAGE • • • • •
• ••••
APPENDIX A
A.l
A. 2
A.3
A.4
A.5
A. 6
A. 7
A.8
A.9
A.10
A.11

A.12
A.13
A.14
A.15
A.15.l
A.15.2
A.16
A.17
A.18
A.19

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

SUMMARY OF I/O FUNCTIONS
ANALOG-TO-DIGITAL CONVERTER DRIVERS
CARD READER DRIVER • • • • • • • • • •
CASSETTE DRIVER • • • • • • • • • • •
COMMUNICATION DRIVERS (MESSAGE-ORIENTED)
DECTAPE DRIVER • • •
• • • •
DECTAPE II DRIVER
• • • • • • •
DISK DRIVER
• • • •
GRAPHICS DISPLAY DRIVER
• • • • •
INDUSTRIAL CONTROL SUBSYSTEMS • • • • •
LABORATORY PERIPHERAL ACCELERATOR DRIVER
LABORATORY PERIPHERAL SYSTEMS DRIVERS
LINE PRINTER DRIVER • • • • • •
MAGNETIC TAPE DRIVER • • • • • • • • • •
PAPER TAPE READER/PUNCH DRIVERS
PARALLEL COMMUNICATION LINK DRIVERS
Transmitter Driver Functions •
Receiver Driver Functions
• • • •
TERMINAL DRIVER • • • • • • •
•
UNIBUS SWITCH DRIVER • • • • • • • • • •
UNIVERSAL DIGITAL CONTROLLER DRIVER • •
VIRTUAL TERMINAL DRIVER
• • • • •

xvi

• A-1
• • A-1
• A-1
• • A-2
• A-2
• A-3
• • A-3
• A-3
• • • • • A-4
•
A-5
• • A-5
• • • A-6
• • • • • A-6
• • • A-6
~ A-7
• • • A-7
• • • A-7
• • • • • A-7
• • A-9
• •
• A-9
• A-9

CONTENTS
Page
APPENDIX B

I/O FUNCTION AND STATUS CODES

B.l
B.1.1
B.1.2
B.2
B.2.1
B.2.2
B.3
B.3.1
B.3.2
B.3.3
B.3.4
B.3.5

I/0 STATUS CODES • • • • •
• .. • • • • B-1
I/O Status Error Codes • • • • • •
B-1
I/O Status Success Codes • •
• • • • • • B-3
DIRECTIVES CODES • • • • • •
• • • • • • • B-4
Directive Error Codes
• • • • • • • • B-4
Directive Success Codes
B-4
I/O FUNCTION CODES • • • • •
. B-4
Standard I/O Function Codes
• • • •
• B-4
Specific A/D Converter I/0 Function Codes
• • • B-5
Specific Card Reader I/O Function Codes
B-5
Specific Cassette I/O Function Codes • • •
• B-5
Specific Communication (Message-Oriented) I/O
Function Codes • • • • • • • • . • • •
B-5
B.3.6
Specific DECtape I/O Function Codes
• B-6
B.3.7
Specific DECtape II I/O Function Codes •
• • B-6
B.3.8
Specific Disk I/0 Function Codes • • • • • • • • B-6
Specific Graphics Display I/O Function Codes • • B-7
B.3.9
B.3.10
Specific ICS/ICR, DSS/DR I/O Function Codes
• • B-7
B.3.11
Specific LPAll-K I/O Function Codes
• • • • • • B-8
B.3.12
Specific LPS I/O Function Codes
• • • • • • • • B-9
B.3.13
Specific Magtape I/O Function Codes
• • • •
B-9
B.3.14
Specific Parallel Communications Link I/O
Function Codes • • • • • • • • • • • • • • • • B-10
B.3.14.1
Transmitter Driver Functions •
B-10
B.3.14.2
Receiver Driver Functions
• • • •
B-10
B.3.15
Specific Terminal I/O Function Codes • B-10
B.3.16
Specific UDC I/O Function Codes
• • • • B-12
Specific UNIBUS Switch I/O Function Codes
B-12
B.3.17
B.3.18
Specific Virtual Terminal I/O Function Codes • B-12

APPENDIX C
C.l
C.1.1
C.1.2
C.1.2.1
C.1.2.2
C.1.2.3
C.1.3
C.1.4
C.1.5
C.2
C.3
C.4
C.5
C.6
C.6.1
C.6.2
C.6.3
C.6.4
C.6.5
C.7

QIO INTERFACE TO THE ACPS
QIO PARAMETER LIST FORMAT • • • • •
File Identification Block
The Attribute List •
• ••••
The Attribute Type • • • •
•
Attribute Size • • • • •
Attribute Buffer Address •
Size and Extend Control
••••
Window Size and Access Control •
File Name Block Pointer
PLACEMENT CONTROL
. • • • •
•
BLOCK LOCKING • • • • • • •
SUMMARY OF FllACP FUNCTIONS
• • • •
SUMMARY OF MTAACP FUNCTIONS
HOW TO USE THE ACP QIOS
• • • • •
Creating a File
• • • • • • • •
Opening a File • • • • • •
• • •
Closing a File •
• • • • • • • •
Extending a File •
Deleting a File
• • • • •
ERRORS RETURNED BY THE FILE PROCESSORS

INDEX

xvii

• • • •

• • • •
•

• • • •
• • • •
• • • •
• • • •
• •
• • • •
• • • •

• C-1
C-2
• • C-2
• • C-3
• C-4
• C-5
• • C-5
• • C-5
C-6
• • C- 7
• • C-7
• • C-7
• • C-9
C-11
• C-12
• C-12
C-12
C-12
• C-12
• C-12

CONTENTS
Page
FIGURES
FIGURE

1-1
1-2
8=1
8-2
9-1
18-1
18-2
19-1
C-1

Logical Unit Table • • • • • • • • • • • • • • • • 1-6
QIO Directive Parameter Block
• • • • . • • • • 1-14
Determination of Tape Characteristics for the
TElO/TUlO
• • • • • • • • • • • • • • • • • •
8-8
Determination of Tape Characteristics for the
TE16/TU16/TU45/TU77
• • • •
8-9
Structure of Cassette Tape • • • • • • .
• • • 9-6
Mapping Table Format • • • • • • • • • • • • • • 18-78
Mapping Table Entry Format • • • • • • •
• 18-79
Indirect TKB Command File TESTBLD.CMD. •
19-1
File Identification Block • • • • • • •
• • C-2

TABLES
TABLE

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

Get LUN Information
1-22
Directive Conditions
1-33
I/O Status Conditions
1-36
Supported Terminal Devices • • • • •
• 2-2
Standard Terminal Interfaces •
• • • •
• 2-3
Standard and Device-Specific QIO Functions for
Terminals
• • • • • • • • •
• • • • • • • 2-7
Subfunction Bits - Summary •
• • • • •
2-11
Full-Duplex Terminal Driver-Terminal
Characteristics for SF.GMC and SF.SMC Functions
2-14
Bit TC.TTP (Terminal Type) Values Set by SF.SMC
and Returned by SF.GMC • • • • • • • • • • •
2-17
Information Returned by Get Terminal Support
(IO.GTS) QIO • • • • • • • • •
2-19
Terminal Status Returns
• • • •
2-23
Terminal Control Characters
2-27
Terminal Control Characters
2-28
Special Terminal Keys
• • • • • • • •
2-30
Vertical Format Control Characters • • • • •
2-34
Supported Terminal Devices •
• • • • • • • • • 3-1
Standard Terminal Interfaces
3-2
Standard and Device-Specific QIO Functions for
Terminals
• • • • • • •
• • 3-5
Subfunction Bits • • • •
• • 3-9
Terminal Characteristics for SF.GMC and SF.SMC
Requests • • • • • • • •
• • • • • 3-11
Bit TC.TTP (Terminal Type): Values Set by SF.SMC
and Returned by SF.GMC • • • • • • • • • • •
3-11
Information Returned by Get Terminal Support
(IO.GTS) QIO • ~ ~ ~ e e ~ e =
3-12
Terminal Status Returns
• • • • 3-17
Terminal Control Characters
• • • • 3-20
Special Terminal Keys
• • • •
3-23
vertical Format Control Characters •
3-26
Standard and Device-Specific QIO Functions for
Virtual Terminals
••••••••••••
4-2
Virtual Terminal Characteristics • • • • •
4-7
Virtual Terminal Status Returns for Offspring Task
Requests • • • • • • • • • • • • • • • • •
• 4-8
Virtual Terminal Status Returns for Parent Task
Requests • • • •
4-9
Standard Disk Devices
• 5-2
Standard Q!O Functions for Disks • • • • • •
• 5-6
Device-Specific Functions for the RX01,RX02, RLOl,
and RL02 Disk Drivers
• • . • • • • • • • •
5-7
xviii

CONTENTS
Page
5-4
5-5
5-5
5-5
6-1
6-2
6-3
7-1
7-2
7-3
8-1
8-2
8-3
8-4
8-5
9-1
9-2
9-3
10-1
10-2
10-3
10-4
11-1
11-2
11-3
11-4
11-5
11-6
12-1
12-2
12-3
12-4
13-1
13-2
13-3
13-4
13-5
13-6
14-1
14-2
14-3

14-4
14-5
14-6
14-7
14-8
15-1
15-2
15-3
15-4
15-5
15-6
15-7
16-1
16-2
16-3

Device-Specific QIO Function for the RASO Disk
Driver • • • • • • • •
• • • • • • • • • • • 5-8
Disk Status Returns
• • • •
• • • •
• • 5-8
Disk Status Returns
• • • •
• • • •
5-10
Disk Status Returns
• • • • • • • • •
5-11
Standard QIO Functions for DECtape •
• 6-2
Device-Specific Functions for DECtape
• 6-3
DECtape Status Returns • • • • • • • • • • • • • • 6-4
Standard QIO Functions for the TU58
• • • • • • • 7-3
Device-Specific QIO Functions for the TU58 • • • • 7-3
TU58 Driver Status Returns • • • • •
• 7-5
Standard Magtape Devices • • • • • • • • • •
• 8-2
Standard QIO Functions for Magtape • • • • •
• 8-4
Device-Specific QIO Functions for Magtape
8-5
Magtape Status Returns •
• • • • • • •
8-10
Information Contained in the Second I/O Status
Word . . • • • . • . • • • • • • • • • • •
8-13
Standard QIO Functions for Cassette
9-2
Device-Specific QIO Functions for Cassette
• • 9-3
Cassette Status Returns
• • • • • • • •
• • 9-4
Standard Line Printer Devices
• • • • • • • • • 10-1
Standard QIO Functions for Line Printers • •
10-3
Line Printer Status Returns
• • • • • • • • • • 10-4
vertical Format Control Characters • • •
10-6
Standard QIO Functions for the Card Reader •
11-2
Device-Specific QIO Function for the Card Reader 11-3
Card Reader Switches and Indicators
• • • • 11-5
Card Reader Status Returns • • • • • • • • •
11-7
Card Reader Control Characters • • •
11-9
Translation from DEC026 or DEC029 to ASCII • • • 11-10
Message-Oriented Communication Interfaces
12-2
Standard QIO Functions for Communication
Interfaces • • • • • • • • • • • • • • • •
12-5
Device-Specific QIO Functions for Communication
Interfaces • • • • • • • • • • • • • • • • • • • 12-6
Communication Status Returns • • • • • • • • • • 12-8
Standard QIO Functions for PCLll Transmitters
13-3
Device-Specific QIO Functions for PCLll
Transmitters • • • • • • • • • • • • • • •
13-3
PCLll Transmitter Driver Status Returns
• • • • 13-7
Standard QIO Functions for PCLll Receivers
13-9
Device-Specific QIO Functions for PCLll Receivers 13-9
PCLll Receiver Driver Status Returns • • • • • • 13-11
Standard Analog-to-Digital Converters
14-1
Standard QIO Function for the A/D Converters • • 14-2
Device-Specific QIO Function for the A/D
Converters • • • • • • . . • •
. • • •
14-2
A/D Conversion Control Word
14-3
Contents of First Word of isb
• • • • 14-4
FORTRAN Interface Subroutines for the AFCll and
ADOl-D • • • • . • • • . • • •
• • • •
14-5
A/D Converter Status Returns • • • • • • • • • • 14-8
FORTRAN Interface Values • • • • • •
• • • • 14-9
Standard QIO Function for the UDCll
• • • •
15-3
Device-Specific QIO Functions for the UDCll
15-4
A/D Conversion Control Word
• • • • • • • •
15-5
Contents of First Word of isb • • • • • • • • • 15-15
FORTRAN Interface Subroutines for the UDCll
• • 15-16
UDCll Status Returns • • • • •
• • • • • 15-31
FORTRAN Interface Values • • • • • • • • • • • • 15-33
Laboratory Peripheral Systems
• • • • • • 16-1
Standard QIO Function for Laboratory Peripheral
Systems
• • . . • • • • • • • • • • • • • • • • 16-2
Device-Specific QIO Functions for the Laboratory
Peripheral Systems (Immediate) • • • • • • • • • 16-3
Q

xix

CONTENTS
Page
16-4
16-5
16-6
16-7
16-8
16-9
16-10
17-1
17-2
18-1
18-2
18-3
18-4
18-5
18-6
18-7
18-8
18-9
20-1
20-2
21-1
21-2
21-3
22-1
22-2
22-3
23-1
23-2
23-3
C-1
C-2

Device-Specific QIO Functions for the Laboratory
Peripheral Systems (Synchronous)
• • • • • • 16-5
Device-Specific QIO Function for the Laboratory
Peripheral Systems (IO.STP)
• • • • • • • • • • 16-9
Contents of First word of isb • • • • • • • • • 16-10
FORTRAN Interface Subroutines for Laboratory
Peripheral Systems • • • • • • • • • • • • • • • 16-11
Laboratory Peripheral Systems Status Returns • • 16-29
Returns to Second Word of I/O Status Block •
16-32
FORTRAN Interface Values •
• • • • • • 16-33
Standard QIO Functions for the Paper Tape
Reader/Punch • • • • • • • • • • • • • • • • • • 17-2
Paper Tape Reader/Punch Status Returns • •
17-3
ICS/ICR Address Assignments
• • • • • 18-2
Sample ICS/ICR Configuration • • • • •
18-7
Sample DSS/DRS Configuration • • • • • • • • • • 18-7
Summary of Industrial Control QIO Functions
18-8
A/D Conversion Control Word
• • • 18-15
FORTRAN Interface
• • • • 18-34
Return Status Summary
• • • • • 18-36
!CSR Contents
• • • • • • • •
• • • •
18-74
!CAR Contents
• • • • • • • • • • • • • •
• 18-75
Standard and Device-Specific QIO Functions for
Graphics Displays
• • • • •
• • • • • • 20-2
Graphics Display Status Returns
• • • • •
20-3
FORTRAN Subroutines for the LPAll-K
21-3
Device-Specific QIO Functions for the LPAll-K • 21-28
Contents of First Word of IOSB • • • • • • • • • 21-31
FORTRAN Subroutines for K-series Laboratory
Peripherals • • • • • • • • • •
• • • • 22-7
Scope Control Word Values
• • • • •
22-27
Contents of First word of IOSB • • • • • •
• 22-32
Standard QIO Functions for UNIBUS Switches
23-2
Device-Specific QIO Functions for UNIBUS Switches 23-4
UNIBUS Switch Driver Status Returns
23-7
Maximum Size for Each File Attribute
• C-4
File Processor Error Codes • • • • • •
C-13

PREFACE

MANUAL OBJECTIVES
The purpose of this manual is to provide all information necessary to
interface directly with the I/O device drivers supplied as part of the
RSX-llM/M-PLUS system.

INTENDED AUDIENCE
This manual is intended for use by experienced
RSX-llM/M-PLUS
programmers who want to take advantage of the time and/or space
savings which result from direct use of the I/O drivers. Readers are
expected to be familiar with the information contained in the
RSX-llM/M-PLUS Executive Reference Manual, and to have some experience
using the Task Builder and either MACR0-11 or FORTRAN programs and to
be familiar with the manuals describing their use.
STRUCTURE OF THE DOCUMENT
Chapter 1 provides an overview of RSX-llM input/output operations. It
is somewhat tutorial in its approach in introducing the reader to the
use of logical unit numbers, directive parameter blocks, event flags,
macro calls, etc. The discussions include the standard I/O functions
common to a variety of devices, and summarizes standard error and
status conditions relating to completion of I/O requests._
Chapters 2 through 23 describe the use of all device drivers supported
by RSX-llM and/or RSX-llM-PLUS;
refer to the preceding Summary Of
Technical Changes to determine which drivers are supported in your
operating system. Descriptions by chapter are as follows:
Chapter

Device Drivers

Full-duplex
interface

terminal

communications

line

Half-duplex
interface

terminal

communications

line

Virtual terminal driver

Disks

DECtape

DECtape II

Magnetic tape

xxi

PREFACE
Device Drivers

Chapter
9

Cassette

Line printers

Card reader

Message-oriented
interfaces

communications

line

PCLll
parallel
communications
transmitter and receiver

link

Analog-to-digital converters

Universal digital controller

Laboratory peripheral systems

Paper tape reader/punch

Industrial control subsystems

The null device

Graphics display terminals

LPAll-K laboratory peripheral accelerator

K-series laboratory peripherals

UNIBUS switch

Each of these chapters is structured in similar fashion and focuses on
the following basic elements:
•

Description of the device, including information on physical
characteristics such as speed, capacity, access, and usage

•

Summary of standard functions supported by
descriptions of device-specific functions

devices

and

•

Discussion of special characters, carriage control codes,
functional characteristics, if relevant

and

•

Summary of error and status conditions returned on
or rejection of I/O requests

•

Description of programming hints for users of the device under
RSX-llM

xxii

the

acceptance

PREFACE
Appendixes A through C provide quick reference material
functions and status codes. These include the following:

I/O

Appendix

Contents

Summary of I/O functions by device

I/O function and status codes

QIO$ interface to Ancillary
Processors

Control

ASSOCIATED DOCUMENTS
Other manuals closely allied to the purposes of this document are
described briefly in the RSX-llM/RSX-llS Information Directory and the
RSX-llM-PLUS Information Directory.
Each Directory defines
the
intended
readership
of each manual
in the RSX-llM/RSX-llS or
RSX-llM-PLUS set and provides a brief synopsis of each manual's
contents.

CONVENTIONS USED IN THIS MANUAL
There are a number of conventions and assumptions used in this manual
to present syntax and program coding examples.
These are described in
the following list.
1.

Brackets
([])
parameters.

syntactic

models

enclose

optional

The following example illustrates this format:
ASTX$S
2.

Braces ( { } ) in syntactic models indicate that
items must be selected, as in the following:
CALL

DOM }
{ DOMW

the

<inm,icont,idata,[idx] ,[isb] ,[lun]>

IO.RLV, ••• ,<stadd,size>
null

Consecutive commas in a coding example
indicate
arguments.
The following illustrates this usage:
QIO$C

one

An ellipsis ( ••• ) in a syntactic model or coding example
indicates that parameters have been omitted. As used in this
manual, an ellipsis in a QIO macro call indicates omission of
standard QIO parameters described in Section 1.5.1. This is
illustrated below:
QIO$C

[err]

IO.ATT,6,,,,ASTOl

Commas indicating null trailing
omitted, as in the following:
QIO$C

IO.KIL,9.

xx i i i

optional

arguments

may

PREFACE
6.

Certain parameters are required but ignored by RSX-llM or
RSX-llM-PLUS;
this is necessary to maintain compatibility
with RSX-llD. For example, in the following, the priority
specification (fourth parameter) is ignored:
QIO$C

IO.WLB,8.,EV,,IOSB,ASTX,<IOBUF,NBUF>

With the exception of MACR0-11 coding examples, all numbers
in the text of this manual are assumed to be decimal; octal
radix is explicitly declared as in the following:
An illegal logical block number has been specified
for DECtape. The number exceeds 577 (1101 octal).
In MACR0-11 coding examples, all numbers are assumed to be
octal;
decimal radix is explicitly designated by following
the number with a decimal point, as in the following example:
QIO$C

IO.RDB,14.,,,IOSB,,<IOBUF,80.>

In FORTRAN subroutine models, parameters which begin with the
letters i through n indicate integer variables, as in the
following example:
CALL DRS (ibuf ,ilen,imode,irate,iefn,imask,isb,
[nbuf], [istart], [istop])
In general, where hoth i and n prefixes are used in a call,
the i form indicates the name of an array and the n form
specifies the size of the array.
All integer arrays and variables are assumed to occupy one
storage word per variable (that is, INTEGER*2) and all real
arrays and variables are assumed to occupy two storage words
per variable (that is, REAL*4).

xxiv

SUMMARY OF TECHNICAL CHANGES
This update to the I/O Drivers Reference Manual contains changes and
additions to document two operating systems:
RSX-llM V4.l and
RSX-llM-PLUS V2.l. The following list contains a brief summary of
technical changes for both operating systems:
•

Terminal driver support
terminals:

has

been

added

for

the

following

LQP02
LA50
DHVll
•

I
I

Disk driver support has been added for the following new
devices:

disk

UDA50/RA81
UDA50/RA60
RC25
RD51
RXSO
•

Magnetic tape driver support has been added for the
TSVOS.

TUBO

•

Line printer driver support has been added for
printers:

following

the

and

LNOl
LP07
LP26
LP27

xxv

April 1983

CHAPTER 1
RSX-llM/M-PLUS INPUT/OUTPUT

1.1

OVERVIEW OF RSX-llM I/O

The RSX-llM/M-PLUS Real-Time Executives support a wide variety of
PDP-11 input and output devices, including disks, DECtapes, magnetic
tapes,
tape cassettes, line printers, card readers,
and
such
laboratory and industrial devices as analog-to-digital converters,
universal digital controllers, and laboratory peripheral systems.
Drivers
for
these
devices are supplied by Digital Equipment
Corporation as part of the system software. This manual describes all
of the device drivers supported by the system and the characteristics,
functions, error conditions, and programming hints associated with
each.
Devices not described in this manual can be added to basic
system configurations, but users must develop and maintain their own
drivers for
these devices.
(See the RSX-llM Guide to Writing an I/O
Driver, including Update No.
1, or the RSX-llM=-PLTIS Guide to writTng
an I/O Driver, depending upon the system you are us1n~ ~
Input/output operations under RSX-llM are extremely flexible and are
as device- and function-independent as possible.
Programs issue I/O
requests to logical units that have been previously associated with
particular physical device units.
Each program or task is able to
establish its own correspondence between physical device units and
logical unit numbers (LUNs).
I/0 requests are queued as issued;
they
are subsequently processed according to the relative priority of the
tasks that issued them.
I/O requests (for appropriate devices) can be
issued from tasks by means of either the File Control Services or
Record Management Services,
or can be interfaced directly to an I/0
driver by means of the Queue I/O (QIO) system directive.
All of the I/O services described in this manual are requested by the
user
in the form of QIO system directi~es. A function code included
in the QIO directive indicates the particular input or output
operation to be performed.
I/0 functions can be used to request such
operations as:
•

Attaching or detaching a physical device
exclusive use

unit

for

•

Reading or writing a logical or virtual block of data

•

Cancelling a task's I/O requests

task's

A wide variety of device-specific input/output operations
(for
example, reading DECtape in-reverse, rewinding cassette tape) can also
be specified with QIO directives.

1-1

RSX-llM/M-PLDS INPDT/ODTPDT
1.2

PHYSICAL, LOGICAL, AND VIRTDAL I/O

There are three possible modes in which
place: physical, logical, and virtual.

I/O

transfer

can

take

Physical I/O concerns reading and writing data in the actual physical
units accepted by the hardware (for example, sectors on a disk). For
most devices, physical I/O is identical to logical I/O. For example,
the RKOS disk has sectors of 256 words, the same size as RSX-llM
logical blocks for all disks. Thus, in this case, a logical block
maps directly into a physical block.
For other devices, the mapping
is not one to one. The RFll disk, for example, is word addressable;
however, no physical I/O may be done with the RFll. Data is always
written in 256-word logical blocks.
Another example is the RXOl
flexible disk.
Data for the RXOl is recorded in physical sectors of
64 words each. Therefore, logical blocks for the RXOl are made up of
four physical sectors.
Logical I/O concerns reading and writing data in blocks that are
convenient for the operating system.
In most cases, logical blocks
map directly into physical blocks. For block-structured devices
(for
example, disks),
logical blocks are numbered beginning at O. For
non-block-structured devices (for example, terminals), logical blocks
are not addressable.
Virtual I/O concerns reading and writing data to open files.
In this
case, the executive maps virtual blocks into logical blocks. For
file-structured devices (disks or DECtapes) , virtual blocks are the
same size as logical blocks and are numbered starting from one (1) and
are relative to the file rather than
to
the
device.
For
non-file-structured devices, the mapping from virtual block to logical
block is direct.

1.3

RSX-llM DEVICES

The devices listed below are supported by
both
RSX-llM
and
RSX-llM-PLUS, except as indicated. Drivers are supplied for each of
these devices, and I/0 operations for them are described in detail
in
subsequent chapters of this manual.
1.

A variety of terminals, including the following:
•

ASR/KSR-33 and ASR/KSR-35 Teletypesl

•

LA12 DECwriter

•

LAlOO DECwriter

•

LA30 DECwriters {serial and parallel)

LA34/LA38 DECwriter IV

LA36 DECwriter II

•

LA120 DECwriter III

•

LA180S DECprinter

•

LQP02 Letter-Quality Printer

1. Teletype is a registered trademark of the Teletype Corporation.
1-2

April 1983

RSX-llM/M-PLUS INPOT/OOTPUT

•

LASO Personal Printer

•

VT05B Alphanumeric Display Terminal

•

VT50 Alphanumeric Display Terminal

•

VT50H Alphanumeric Display Terminal

•

VT52 Alphanumeric Display Terminal

•

VT55 Graphics Display Terminal

•

VT61 Alphanumeric Display Terminal

•

VTlOO Alphanumeric Display Terminal

•

VTlOl Alphanumeric Display Terminal

•

VT102 Alphanumeric Dispiay Terminal

•

VT105 Alphanumeric Display Terminal

•

VT125 Alphanumeric Display Terminal

•

VT131 Alphanumeric Display Terminal

•

VT132 Alphanumeric Display Terminal

•

RT02 Data Entry Terminal

•

RT02-C Badge Reader and Data Entry Terminal

These terminals are supported on the
line interfaces:

following

asynchronous

•

DJll Asynchronous Communication Line Interface Multiplexer

•

DHll and DHll-DMll-BB
Interface Multiplexer

•

DHVll
Asynchronous
Multiplexer

DLll-A, DLll-B, DLll-C, DLll-D,
DLll-E
Asynchronous Communication Line Interfaces

•

DLVll-E,
DLVll-F
Interfaces

•

DZll Asynchronous Communication Line Interface Multiplexer

Asynchronous

Communication
Line

Communications

Asynchronous

Line

Interface
and

DLll-W

Communication

Line

A variety of disks, including the following:
•

ML-11 Fast Electronic Mass Storage Device

RFll/RSll Fixed-Head Disk

•

RS03/RS04 Fixed-Head Disk

•

UDA50/RA80/RA81 Fixed-Media Disk

•

UDA50/RA60 Pack Disk

•

RM80 Fixed-Media Disk

1-3

I
April 1983

RSX-llM/M-PLUS INPUT/OUTPUT

•

RP07 Fixed-Media Disk

•

RP11/RP02 or RP03 Pack Disks

•

RM02, RM03, RM05 Pack Disk

•

RP04, RP05, RP06 Pack Disks

•

RK11/RK05 or RK05F Cartridge Disks

RLll/RLOl or RL02 Cartridge Disk

•

RK611/RK06 or RK07 Cartridge Disk

•

RC25 Fixed-Media/Removable Cartridge Disk Subsystem

•

RD51 Fixed-Media Disk

•

RX50 Flexible Disk

•

RXll/RXOl Flexible Disk

•

RX211/RX02 Flexible Disk

TC11/TU56 DECtape

DL11/TU58 DECtape II

A variety of magnetic tapes including the following:

•

TOSO Magnetic Tape Subsystem

•

TSV05 Magnetic Tape Subsystem

•

TSll Magnetic Tape Subsystem

•

TMll Magnetic Tape
Drive

•

RHll/70 Controller with TM02/03 Formatter and TE16,
or TU45 Drive

•

RHll/70 Controller with TM03 Formatter and TU77 Drive

•

RH11/RH70 Controller with TM78 Formatter and TU78 Drive

Controller

TAll Tape Cassette

A variety of line printers:

I
I
8.

with

TElO,TUlO,

•

LPll Controller with LP14, LPOl, LP02, LP04,
LP07, LP26, LP27 Line Printers

•

LSll Controller and Line Printer

•

LVll Controller with LVOl Line Printer

•

LA180 Controller and Line Printer

•

LNOl Laser Printer

LP05,

TS03
TU16,

LP06,

CRll Card Reader

1-4

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT

Synchronous and asynchronous line interfaces:
Asynchronous Communication Line Interface
• DAll-B
support only)

(RSX-llM

Asynchronous Communication Line Interface
• DLll-E
support only)

(RSX-llM

• DLVll-E Asynchronous Communication Line Interface

• DMCll Synchronous Communication Line Interface
Synchronous
• DPll
support only)

Communication

Line

Interface

(RSX-llM

Synchronous
• DQll
support only)

Communication

Line

Interface

(RSX-llM

Synchronous Communication Line
• DUll
support only)

Interface

(RSX-llM

• DUPll Synchronous Communication Line Interface

1-4.1

RSX-llM/M-PLUS INPUT/OUTPUT
10.

Two analog-to-digital converters:
•

AFCll Analog-to-Digital Converter (RSX-llM support only)

•

ADOl-D Analog-to-Digital Converter (RSX-llM support only)

11.

UDCll Universal Digital Controller (RSX-llM support only)

12.

Laboratory peripheral systems:

13=

14.

•

ARll Laboratory Peripheral System (RSX-llM support only)

•

LPSll Laboratory Peripheral System (RSX-llM support only)

Paper tape devices:
•

PCll Paper Tape Reader/Punch

•

PRll Paper Tape Reader

Industrial control subsystems:
•

ICS/ICR Local and Remote Subsystems (RSX-llM support only)

DSS/DRS Digital
support only)

Input

and

15.

The "Null Device," a software
eliminating unwanted output

16.

Two graphics subsystems:

17.

Subsystems

construct

that

(RSX-llM

facilitates

•

VTll Graphics Display System (RSX-llM support only)

•

VS60 Graphics Display System (RSX-llM support only)

Laboratory Peripheral Accelerator:

e
18.

Output

LPAll-K

K-series laboratory peripherals:
Converter and Display
• AAll-K
• ADll-K Analog-to-Digital Converter
• AMll-K Multiple-Gain Multiplexer
• DRll-K Digital I/O Interface
• KWll-K Programmable Real-Time Clock
Digital~to-Analog

1.4

19.

PCLll
only)

Parallel

Communications

Link

(RSX-llM-PLUS

20.

DT07 (RSX-llM-PLUS support only) UNIBUS Switch

21.

Virtual Terminals (RSX-llM-PLUS support only)

support

LOGICAL UNITS

This section describes the construction of the logical unit table
the use of logical unit numbers.

1-5

and

RSX-llM/M-PLUS INPUT/OUTPUT
1.4.1

Logical Unit Number

A logical unit number, or LUN, is a number associated with a physical
device unit during RSX-llM/M-PLUS I/O operations. For example, LUN 1
might be associated with one of the terminals in the system, LUNs 2,
3, 4, and 5 with DECtape drives, and LUNs 6, 7, and 8 with disk units.
The association is a dynamic one; each task running in the system can
establish its own correspondence between LUNs and physical device
units, and can change any LUN/physical-device-unit association at
almost any time.
The flexibility of this association contributes
heavily to system device independence.
A logical unit number is simply a short name used to represent a
logical-unit/physical-device-unit association.
Once the association
has been made, the LUN provides a direct and efficient mapping to the
physical device unit, and eliminates the necessity to search the
device tables whenever the system encounters a reference to a physical
device unit.
The user should remember that, although a LUN/physical-device-unit
association can be changed at any time, reassignment of a LUN at run
time causes pending I/O requests for the previous LUN assignment to be
cancelled.
It is the user's responsibility to verify that all
outstanding I/O requests for a LUN have been serviced before that LUN
is associated with another physical device unit.

1.4.2

Logical Unit Table

There is one Logical Unit Table (LUT)
for each task running in a
system.
This table is a variable-length block contained in the task
header. Each LUT contains sufficient 2-word entries for the number of
logical units specified by the user at task-build time by the "UNITS="
option.
Each entry or slot contains a pointer to the physical device unit
currently associated with that LUN. Whenever a user issues an I/O
request, the system matches the appropriate physical device unit to
the LUN specified in the call by indexing into the LUT by the number
supplied as the LUN. Thus, if the call specifies 6 as the LUN, the
system accesses the sixth 2-word entry in the LUT and associates the
I/O request with the physical device unit to which the entry points.
The number of LUN assignments valid for a task ranges from 0 to 255,
but cannot be greater than the number of LUNs specified at task-build
time.
Figure 1-1 illustrates a typical Logical Unit Table.

l
~-

LUN 1

LUN 2

~ LUN 3

~--

LUN 4

NUMBER OF LUNS

UCB

-- - -

UCB

-- - -

UCB

- -

UCB

- -

ZK-004-81

Figure 1-1

Logical Unit Table
1-6

RSX-llM/M-PLUS INPUT/OUTPUT
Word 1 of each active (assigned) 2-word entry in the logical unit
table points to the Unit Control Block (UCB) of the physical device
unit with which the LUN is associated.
This linkage may be indirect;
that is, the user may force redirection of references from one unit to
another unit with the MCR command REDIRECT. Word 2 of each entry is
reserved for mountable devices.

1.4.3

Changing LUN Assignments

Logical unit numbers have no significance until they are associated
with a physical device unit by means of one of the methods described
below:

1.5

At task-build time, the user can specify an ASG keyword
option, which associates a physical device unit with a
logical unit number referenced in the task being built.

The user or system operator can issue a REASSIGN command to
MCR;
this command reassigns a LUN to another physical device
unit and thus changes
the
LUN-physical
device
unit
correspondence. Note that this reassignment has no effect on
the in-core image of a task.

At run time, a task can dynamically change a LUN assignment
by issuing the Assign LUN system directive, which changes the
association of a LUN with a physical device unit during task
execution.

ISSUING AN I/0 REQUEST

User tasks perform I/O in the RSX-llM/M-PLUS system by submitting
requests for
I/O service in the form of QIO or QIO And Wait system
directives.
See the RSX-llM/M-PLUS Executive Reference Manual for a
complete description of system directives.
In RSX-llM/M-PLUS, as in most multiprogramming systems, tasks do not
normally access physical device units directly.
Instead, they utilize
input/output services provided by the Executive, since it
can
effectively multiplex the use of physical device units over many
users.
The Executive routes I/O requests to the appropriate device
driver and queues them according to the priority of the requesting
task.
I/O operations proceed concurrently with other activities in an
RSX-llM/M-PLUS system.
Before a request is queued, it must
administered by the Executive.
If
this rejection is signalled by the
statement following
the QIO is
practice to check for directive
directive with a BCS instruction.

pass a battery of acceptance tests
the request fails, it is rejected;
setting of the C-bit when the
executed.
It is good programming
rejection by following
the QIO

After an I/O request has been queued, the system does not wait for the
operation to complete.
If at any time the user task that issued the
QIO request cannot proceed until the I/O operation has completed,
it
should specify an event flag (see Sections 1.5.1 and 1.5.2) in the QIO
request and should issue a Waitfor system directive specifying the
same event flag at the point where synchronization must occur.
The
task then waits for completion of I/O by waiting for
the specified
event flag to be set.

1-7

RSX-llM/M-PLUS INPUT/OUTPUT
The QIOW directive, QIO And Wait, is a more economical way to achieve
this
synchronization.
QIOW automatically waits until I/O has
completed before returning control to the task. Thus, the additional
Waitfor directive is not necessary.
Each QIO or QIOW directive must supply sufficient information to
identify and queue the ,I/O request. The user may also want to include
locations to receive error or status codes and to specify the address
of an asynchronous system trap service routine. Certain types of I/O
operations require the specification of device-dependent information
as well. Typical QIO parameters are the following:
•

I/O function to be performed

•

Logical unit number associated with the physical
to be accessed

•

Optional event flag number for
processing (required for QIOW)

•

Optional address of the I/O status block to which information
indicating successful or unsuccessful completion is returned

•

Optional address of an asynchronous system trap service
routine to be entered on completion of the I/O request

•

Optional device- and function-dependent parameters specifying
such items as the starting address of a data buffer, the size
of the buffer, and a block number

synchronizing

I/O

device

unit

completion

A set of system macros that facilitate the issuing of QIO directives
is supplied with the RSX-llM/M-PLUS system.
These macros, which
reside in the System Macro Library (LB: [l,l]RSXMAC.SML), must be made
available to the source program by means of the MACR0-11 Assembler
directive .MCALL. The function of .MCALL is described in Section
1.7.3.
Several of the first six parameters in the QIO directive are
optional, but space for these parameters must be reserved.
During expansion of a QIO macro, a value of 0 is defaulted for all
null
(omitted)
parameters.
Inclusion
of
the
deviceand
function-dependent parameters depends on the physical device unit and
function specified.
If the user wanted to specify only an I/O
function code, a LUN, and an address for an asynchronous system trap
service routine, the following might be issued:
QIOSC

IO.ATT,6,,,,ASTOX

IO.ATT
The I/O function code for attach.
6

The LUN.
AST OX
The AST address.

1-8

RSX-llM/M-PLUS INPUT/OUTPUT

,,,,
Null arguments for the event flag number, the
and the address of the I/O status block.

request

priority,

No additional device- or function-dependent parameters are required
for an attach function. The C form of the QIO$ macro is used here and
in most of the examples included in Chapter 1. Section 1.7 describes
the three legal forms of the macro.
For convenience, any comma may be omitted if no parameters appear to
the right of it.
The command above could therefore be issued as
follows, if the asynchronous system trap was not desired:
QIO$C

IO.ATT,6

All extra commas have been dropped.
If, however, a parameter appears
to the right of any place-holding comma, that comma must be retained.

1.5.1

QIO Macro Format

The arguments for a specific QIO macro call may be different for each
I/O device accessed and for each I/O function requested. The general
format of the call is, however, common to all devices and is as
follows:
QIO$C

fnc,lun, [efn], [pri], [isb], [ast] [,<pl,p2, ••• ,p6>]

where brackets ([]) enclose optional or function-dependent parameters.
If function-dependent parameters <pl, ••. ,p6> are required, these
parameters must be enclosed within angle brackets (<>). The following
paragraphs summarize the use of each QIO parameter. Section 1.7
discusses different forms of the QIO$ macro itself.
The fnc parameter is a symbolic name representing the I/O function
be performed. This name is of the form

IO.xxx
xxx
Identifies the particular I/O operation.
For example, a QIO request to attach the physical
associated with a LUN specifies the function code

device

unit

IO.ATT
A QIO request to cancel (or kill) all I/O requests for a specified LUN
begins in the following way:
QIO$C

IO.KIL, •••

The fnc parameter specified in the QIO request is stored internally as
a fun~tion code in the high-order byte and modifier bits in the
low-order byte of a single word. The function code is in the range 0
through 31 and is a binary value supplied by the system to match the
symbolic name specified in the QIO request.
The correspondence
between global symbolic names and function codes is defined in the

1-9

RSX-llM/M-PLUS INPUT/OUTPUT
system object module library, which is automatically searched by the
Task Builder.
Local symbolic definitions may also be obtained by the
FILIO$ and SPCIOS macros, which reside in the System Macro Library and
are summarized
in Appendix A.
Several similar functions may have
identical function codes, and may be distinguished only by their
modifier bits.
For example, the DECtape read logical forward and read
logical reverse functions have the same function code.
Only the
modifier bits for these two operations are stored differently.
The lun parameter represents the logical unit number
(LUN)
of the
associated physical device unit to be accessed by the I/O request.
The association between the physical device unit and the LUN 1s
specific to the task that issues the
I/O request, and the LUN
reference is usually device independent.
An attach request to the
physical device unit associated with LUN 14 begins in the following
way:
QIO$C

IO.ATT,14., •••

Because each task has its own LUT in which the physical device
unit-LUN correspondences are established,
the legality of a LUN
parameter is specific to the task that includes this parameter in a
QIO request.
In general, the LUN must be in the following range:
0

<LUN

<length of task's LUT (if nonzero)

The number of LUNs specified in the LUT of a
exceed 255.

particular

task

cannot

The efn parameter is a number
representing
the event flag
to be
associated with the I/O operation.
It may optionally be included in a
QIO or QIO And Wait request.
The specified event flag is cleared when
the
I/O request is queued and
is set when the I/O operation has
completed.
If the task has issued the QIO And Wait directive,
execution
is automatically suspended until the I/O completes.
If a
QIO directive has been issued (with no Waitfor directive),
then task
execution proceeds in parallel with the I/O. When the task continues
to execute, it may test the event flag whenever it chooses by using
the Read All Event Flags system directive (if group global event flags
are not being used) or the Read Extended Flags system directive
(for
all event flags,
including group-global event flags).
If the user
specifies an event flag number, this number must be in the range 1
through 9n.
If an event flag specification is not desired, efn can be
omitted or can be supplied with a value of O.
Event flags
1 through
32 are local (specific to the issuing task);
event flags 33 through
64 are global {shared by all tasks in the system).
Event .flags 65
through 96 are group-global event flags (shared by all tasks in the
same user group) • Flags 25 through 32 and 57 through 64 are reserved
for use by system software. Within these bounds, the user can specify
event flags as desired to synchronize I/O completion and task
execution.
Section 1.5.2 provides a more detailed explanation of
event flags and significant events.
NOTE
If an event flag is not specified,
the
Executive treats the directive as if it
were a simple QIO request.

1-10

RSX-llM/M-PLUS INPUT/OUTPUT

The optional pri parameter is supplied only to make RSX-llM/M-PLUS QIO
requests
compatible
with
RSX-llD.
An
RSX-llM
I/O request
automatically assumes the priority of the requesting task.
Thus, it
is recommended that a value of 0 (or a null) be used for this
parameter.
The optional isb parameter identifies the address of the I/O status
block (I/O status double-word) associated with the I/O request. This
block is a 2-word array in which a code representing the final status
of the I/O request is returned on completion of the operation. This
code is a binary value that corresponds to a symbolic name of the form
IS.xxx (for successful returns) or IE.xxx (for error returns). The
binary error code is returned to the low-order byte of the first word
of the status block.
It can be tested symbolically, by name. For
example, the symbolic status IE.BAD is returned if a bad parameter is
encountered.
The following illustrates the examination of the I/O
status block, IOST, to determine if a bad parameter has been detected:
QIO$C
BCS
WTSE$C

IO.ATT,14.,2,,IOST
DIRERR

CMPB
BNE

#IS.SUC,IOST
ERROR

The correspondence between global symbolic names and I/O completion
codes is defined in the system object module library, which is
automatically searched by TKB. Local symbolic definitions, which are
summarized in Appendix B, may also be obtained by the IOERR$ macro,
which resides in the System Macro Library.
Certain device-dependent information is returned to the high-order
byte of the first word of isb on completion of the I/O operation. If
a read or write operation is successful, the second word is also
significant.
For example, in the case of a read function on a
terminal, the number of bytes typed before a carriage return is
returned in the second word of isb. If a magtape unit is the device
and a write function is specified, this number represents the number
of bytes actually transferred. The status block can be omitted from a
QIO request if the user does not intend to test for successful
completion of the request.
The optional ast parameter specifies the address of a service routine
to be entered when an .a.synchronous system trap occurs. Section 1.5.3
discusses the use of asynchronous system traps, and Section 2.2.5 of
the RSX-11M/M-PLUS Executive Reference Manual describes traps in
detail. If the user wants to interrupt his task to execute special
code on completion of an I/O request, an asynchronous system trap
routine can be specified in the QIO request. When the specified I/O
operation completes, control branches to this routine at the software
priority of the requesting task. The asynchronous code beginning at
address ast is then executed, much as an interrupt service routine
would be.
If the user does not want to perform asynchronous
processing, the ast parameter can be omitted or a value of 0 specified
in the QIO macro call.
The additional QIO parameters, <pl,p2, ••• ,p6>, are dependent on the
particular function and device specified in the I/O request. Typical
parameters may include I/O buffer address, I/O buffer length, and so
forth.
Between zero and six parameters can be included, depending on
the particular I/O function. Rules for including these parameters and
legal values are described in subsequent chapters of this manual.

1-11

RSX-llM/M-PLUS INPUT/OUTPUT
1.5.2

Significant Events

"Significant event" is a term used in real-time systems to indicate a
change in system status.
In RSX-llM/M-PLUS, a significant event is
declared when an I/O operation completes.
This signals the system
that a change in status has occurred and indicates that the Executive
should review the eligibility of all tasks in the system to determine
which task should run next.
The use of significant events helps
cooperating tasks in a real-time system to communicate with each
other, and thus allows these tasks to control their own sequence of
execution dynamically.
Significant events are normally set by system directives, either
directly or indirectly, by completion of a specified function.
Event
flags associated with tasks may be used to indicate which significant
event
has
occurred.
Of
the
96
event flags available in
RSX-llM/M-PLUS, the flags numbered 1 through 32 are local to an
individual task and are set or reset only as a result of that task's
operation.
The event flags numbered 33 through 64 are common to all
tasks.
Flags 25 through 32 and 57 through 64 are reserved for system
software use.
The event flags numbered 65 through 96 are group-global
event flags, which are common to all tasks running under the same user
group.
An example of the use of significant events follows.
A task issues a
QIO directive with an efn parameter specified. A Waitfor directive
follows the QIO and specifies as an argument the same event flag
number.
The event flag is cleared when the I/O request · queued by
the Executive, and the task is blocked when it executes the Waitfor
directive until the event flag
is set and a significant event is
declared at the completion of the I/O request.
The task resumes when
the appropriate event flag
is set, and execution resumes at the
instruction following the Waitfor directive.
During the time that the
task is blocked, other tasks have a chance to run, thus increasing
throughput in the system.

1.5.3

System Traps

System traps are used to interrupt task execution and to cause a
transfer of control to another memory location for special processing.
Traps are handled by the Executive and are relevant only to the task
in which they occur.
To use a system trap, a task must contain a trap
service routine, which is automatically entered when the trap occurs.
There are two types of system traps:
synchronous and asynchronous.
Both are used to handle error or event conditions, but the two traps
differ in their relation to the task that is running when they are
detected.
Synchronous traps signal error conditions within the
executing task.
If the same instruction sequence were repeated,
the
same synchronous trap would occur at the same place in the task.
Asynchronous traps signal the completion of an external event such as
an I/O operation. An asynchronous system trap (AST) usually occurs as
the result of initiating or completing an external event rather than a
program condition.
The Executive queues ASTs in a first-in-first-out queue for each task
and monitors all asynchronous service routine operations~
Because
asynchronous traps may be the end result of I/0-related activity, they
cannot be controlled directly by the task that receives them.
However, the task may, under certain circumstances, block recognition
of ASTs to prevent simultaneous access to a critical data region.

1-12

RSX-llM/M-PLUS INPUT/OUTPUT
When access to the critical data region has been completed, the queued
ASTs may again be honored.
The DSAR$S (Disable AST Recognition) and
ENAR$S
(Enable AST Recognition)
system directives
provide
the
mechanism for accomplishing this. An example of an asynchronous trap
condition is the completion of an I/O request.
The timing of such an
operation clearly cannot be predicted by the requesting task.
If an
AST service routine is not specified in an I/O request,
a trap does
not occur and normal task execution continues.
Asynchronous system traps associated with
I/O requests enable the
requesting task to be truly event driven.
The AST service routine
contained in the initiating task is executed as soon as possible,
consistent with the task's priority.
Using the AST routine to service
I/0-related events provides a
response time that is considerably
better than a polling mechanism, and provides for better overlap
processing than the simple QIO and Waitfor sequence.
Asynchronous
system traps also provide an ideal mechanism for use in multiple
buffering of I/O operations.
All ASTs are inserted in a first-in-first-out queue on a per task
basis as they occur (that is, the event that they are to signal has
expired).
They are effected one at a time whenever the task does not
have ASTs disabled and is not already in the process of executing an
AST service routine.
The process of effecting an AST involves storing
certain information on the task's stack, including the task's Waitfor
mask word and address, the Directive Status Word (DSW), the PS, the PC
and
any trap dependent parameters.
The task's general-purpose
registers RO-RS are not saved, and thus it is the responsibility of
the AST service routirie to save and restore the registers it uses.
After an AST is processed, the trap-dependent parameters (if any) must
be removed from the task's stack and an AST Service Exit directive
executed.
The ASTX$S macro described in Section 1.7.6 of this manual
is used to issue the AST Service Exit directive.
On AST service exit,
control is returned to another queued AST, to the executing task, or
to another task that has been waiting to run.
The RSX-llM/M-PLUS
Executive Reference Manual describes in detail
the purpose of AST
service routines and all system directives used to handle them.

1.6

DIRECTIVE PARAMETER BLOCKS

A Directive Parameter Block (DPB) is a fixed-length area of contiguous
memory that contains the arguments specified in a system directive
macro call. The DPB for a QIO directive has a length of 12 words.
It
is generated as the result of expanding a QIO macro call.
The first
byte of the DPB contains the directive identification code
(DIC)
-- always 1 for QIO.
The second byte contains the size of the DPB in
words -- always 12 for RSX-llM/M-PLUS.
During assembly of a user task
containing QIO requests,
the MACR0-11 Assembler generqt~s a DPB for
each I/O request specified in a QIO macro call.
At run time,
the
Executive uses the arguments stored in each DPB to create, for each
request, an I/O packet in system dynamic storage.
The packet is
entered by priority into a queue of I/O requests for the specified
physical device unit.
This queue is created and maintained by the
Executive and is ordered by the priority of the tasks that issued the
requests.
The I/O drivers examine their respective queues for the I/O
request with the highest priority capable of being executed.
This
request is dequeued (removed from the queue) and the I/O operation is
performed= The process is then repeated until the queue is emptied of
all requests.

1-13

RSX-llM/M-PLUS INPUT/OUTPUT
After the I/O request has been completed,
the Executive declares a
significant event and may set an event flag, cause a branch to an
asynchronous system trap service routine, and/or return the
I/O
status, depending on the arguments specified in the original QIO macro
call.
Figure 1-2 illustrates the layout of a sample DPB.

WORD 0 SIZE OF DPB - - -

2
3 PRIORITY

---

BYTE

DIC FOR 010
- - - DIRECTIVE

FNC

MODIFIERS

- - - 1/0 FUNCTION

~{{sf~;g~
~

LUN

- - - LOGICAL UNIT NUMBER

PAI

EFN

- - - EVENT FLAG NUMBER

ISB

AST

DEVICE-

---- ADDRESS OF 1/0
ST A TUS BLOCK
___ ADDRESS OF
ASYNCHRONOUS TRAP
SERVICE ROUTINE

DEPENDENT
PARAMETERS

11
ZK-005-81

Figure 1-2

1.7

QIO Directive Parameter Block

I/0-RELATED MACROS

Several system macros are supplied with the RSX-llM/M-PLUS system to
issue and return information about I/O requests.
These macros reside
in the System Macro Library and must be made available during assembly
by the MACR0-11 assembler directive .MCALL.
Also supplied are FORTRAN-callable subroutines that perform the same
functions as the system macros.
See the RSX-llM/M-PLUS Executive
Reference Manual for details.
There are three distinct forms of most of the system directive macros
discussed in this section.
The following list summarizes the forms of
QIO$, but the characteristics of each form also apply to QIOW$, ALUN$,
GLUN$, and other system directive macros described below.
1.

QIO$ generates a directive parameter block for the
I/O
request
at
assembly
time, but does not provide the
instructions necessary to execute the request.
This form of
the request is actually executed using the DIR$ macro.
It is
useful if the DPB is to be used in several different places
in the task and/or modified or referenced by the task at run
time.

1-14

RSX-llM/M-PLUS INPUT/OUTPUT

QIO$S generates a directive parameter block for the
I/O
request on the stack, and also generates code to execute the
request.
This is a useful form for reentrant, shareable code
since the DPB is generated dynamically at execution time.

QIO$C generates a directive parameter block for the I/O
request at assembly time, and also generates code to execute
the request.
The DPB is generated
in a separate program
section called $DPS$$.
This approach incurs little system
overhead and is useful when an I/O request is executed from
only one place in the program.

Parameters for both the QIO$ and QIO$C forms of the macro must be
valid expressions to be used in assembler data-generating directives
such as .WORD and .BYTE.
Parameters for the QIO$S form must be valid
source
operand
address
expressions
to be used
in assembler
instructions such as MOV and MOVB.
The following example references
the same parameters in the three distinct forms of the macro call.
QIO$

IO.RLB,6,2,,,ASTOl,<RDBUF,80.>

QIO$C

IO.RLB,6,2,,,ASTOl,<RDBUF,80.>

QIO$S

#IO.RLB,#6,#2,,,#ASTOl,<#RDBUF,#80.>

Only the QIO$S form of the macro produces the DPB dynamically.
The
other
two
forms
generate
the
DPB
at assembly time.
The
characteristics and use of these different forms are described
in
greater detail in the RSX-llM/M-PLUS Executive Reference Manual.
The following Executive directives and assembler macros are
in this section:
1.

QIO$, which is used to request an I/O
parameters for that request

QIOW$, which is equivalent to QIOS followed by WTSE$

DIR$, which specifies the address of a directive parameter
block as its argument, and generates code to execute the
directive

.MCALL, which is used to make available from the System Macro
Library all macros referenced during task assembly

ALUNS, which is used to associate a logical unit number
a physical device unit at run time

GLUN$, which requests that the information about a physical
device unit associated with a specified LUN be returned to a
user-specified buffer

ASTX$S, which is used to terminate
execution
asynchronous system trap (AST) service routine

WTSE$, which instructs the system to block execution
issuing task until a specified event flag is set

the

1-15

operation

described
and

supply

with

RSX-llM/M-PLUS INPUT/OUTPUT
1.7.1

The QIO$ Macro: Issuing an I/O Request

As described in Section 1.7, there are three distinct forms of the
QIO$ macro.
QIO$S generates a DPB for the I/O request on the stack,
and also generates code to execute the request.
QIO$C generates a DPB
and code, but the DPB is generated in a separate program section.
QIO$ generates only the DPB for the I/O request.
This form of the
macro call
is used
in conjunction with DIR$ (see Section 1.7.2) to
execute an I/O request.
In the following example, the DIR$ macro
actually generates the code to execute the QIO$ directive.
It
provides no QIO parameters of its own, but references the QIO
directive parameter block at address QIOREF by supplying this label as
an argument.

1.7.2

QIOREF:

QIO$

IO.RLB,6,2,,,ASTOl,<BUFFER,80.>
CREATE QIO DPB

READl:

DIR$

#QIOREF

ISSUE I/O REQUEST

READ2:

DIR$

#QIOREF

ISSUE I/O REQUEST

The QIOW$ Macro: Issuing an I/O Request and Waiting for an
Event Flag

The QIOW$ macro is equivalent to a QIO$ followed by a WTSE$.
It is
more economical to issue a QIO And .Wait request than to use the two
separate macros.
An event flag {efn parameter) must be specified with
QIOW$.

1.7.3

The DIR$ Macro: Executing a Directive

The DIR$ (execute directive) macro has been
task to reference a previously defined DPB.
DIR$

implemented to allow a
It is issued in the form:

[addr] [,err]

addr
The address of a directive parameter block to be used
in the
directive.
If addr
is not included,
the DPB itself or the
address of the DPB is assumed to already be on the stack.
This
parameter must be a valid source operand for a MOV instruction
generated by the DIR$ macro.
err
An optional argument which specifies the address of an error
routine to which control branches if the directive is rejected.
The branch occurs by means of a JSR PC, err if the C-bit is set,
indicating rejection of the QIO directive.

1-16

RSX-llM/M-PLUS INPUT/OUTPUT
1.7.4

The .MCALL Directive: Retrieving System Macros

.MCALL is a MACR0-11 Assembler directive that retrieves macros from
the System Macro Library (LB: [l,l]RSXMAC.SML) for use during assembly.
It must be included in every user task invoking system macros.
.MCALL
is usually placed at the beginning of a user-task source module and
specifies, as arguments in the call, all system macros that must be
made available from the library.
The following example illustrates the use of this directive:
.MCALL

QIO$,QIO$S,DIR$,WTSE$S

MAKE MACROS AVAILABLE

ATTACH: QIO$S

#IO.ATT,#6,,,IOSB,#AST02

ATTACH DEVICE

QIOREF: QIO$

IO.RLB,6,,,IOSB,ASTOl, •••

CREATE ONLY QIO DPB

READl:

#QIOREF,DIRERR

ISSUE I/O REQUEST

DIR$

As many macro references as can fit on a line can be included
in a
single
.MCALL directive.
There is no limit to the number of .MCALL
directives that can be specified.

1.7.5

The ALUN$ Macro: Assigning a LUN

The Assign LUN macro is used to associate a logical unit number with a
physical device unit at run time.
All three forms of the macro call
may be used. Assign LUN does not request I/O for the physical device
unit, nor does it attach the unit for exclusive use by the issuing
task.
It simply establishes a LUN-physical device unit relationship,
so that when the task requests
I/O for that particular LUN, the
associated physical device unit is referenced.
The macro is issued
from a MACR0-11 program in the following way:
ALUN$

lun,dev,unt

lun
The logical unit number
physical device unit.

associated

with

the

specified

dev
The device name of the physical device or a logical device
assigned to a physical device (see MCR ASN command).
unt
The unit number of that device specified above.

1-17

name

RSX-llM/M-PLUS INPUT/OUTPUT
For example, to associate LUN 10 with terminal unit 2,
macro call could be issued by the task:
ALUN$C

the

following

10.,TT,2

A unit number of 0 represents unit 0 for multiunit devices such as
disk,
DECtape, or terminals;
it indicates the single available unit
for devices without multiple units, such as card readers and line
printers.
Logical devices are SYSGEN options that allow the user to assign
logical names to physical devices by means of the MCR command ASN.
See the RSX-llM/M-PLUS MCR Operations Manual for a full description.
The example included below illustrates the use of the three
the ALUN$ macro.

forms

DATA DEFINITIONS
ASSIGN: ALUN$

10.,TT,2

GENERATE DPB

EXECUTABLE SECTION
DIR$

#ASSIGN

EXECUTE DIRECTIVE

ALUN$C

10.,TT,2

GENERATE DPB IN SEPARATE PROGRAM
SECTION, THEN GENERATE CODE TO
EXECUTE THE DIRECTIVE

ALUN$S

#10.,#"TI,#0

GENERATE DPB ON STACK, THEN
EXECUTE DIRECTIVE

1.7.5.1 Physical Device Names - The following list contains physical
device names,
listed alphabetically,
that may be included as dev
parameters:
Name

Device

ADOl-D Analog-to-Digital Converter (not
RSX-llM-PLUS systems)

supported

AFCll Analog-to-Digital Converter
RSX-llM-PLUS systems)

(not

supported

ARll Laboratory Peripheral System
RSX-llM-PLUS systems)

(not

supported

1-18

RSX-llM/M-PLUS INPUT/OUTPUT

Name

Device

DT03/DT07 UNIBUS
systems only)

CDll Card Reader

Central Processor Unit
(CPU)
in a multiprocessor
system (supported in RSX-llM-PLUS systems only)

CRll/CMll Card Reader

TA11/TU60 Tape Cassette

RP04, RPOS, RP06 Pack Disk

TU58 DECtape II

RFll/RSll Fixed-Head Disk

RK11/RK05 Cartridge Disk

RL11/RL01/RL02 Cartridge Disk

RK611/RK06 and RK711/RK07 Cartridge Disk

RP11/RP02/RP03 Pack Disk

RM02/RM03/RM05 Pack
Disk

RS03 and RS04 Fixed-Head Disks

TC11/TU56 DECtape

RA80/RA81 Fixed-Media Disk, RA60 Pack Disk, RC25 Disk
Subsystem, RD51 Fixed-Media Disk, and RX50 Flexible
Disk

RXll/RXOl Flexible Disk

RX211/RX02 Flexible Disk

ML-11 Fast Electronic Mass Storage Device

VT11/VS60
Graphics
RSX-llM-PLUS systems)

ICS/ICR Industrial Control Local and Remote Subsystems
(not supported in RSX-llM-PLUS systems)

DSS/DRS Digital Input and Output
supported in RSX-llM-PLUS systems)

LPAll-K Laboratory Peripheral Accelerator

LA180/LP11/LS11/LV11
Printer

LPSll Laboratory Peripheral System (not
RSX-llM-PLUS systems)

Switch

Disk

1-19

(supported

and

Systems

Line

RSX-llM-PLUS

RM80/RP07

(not

Printers

Fixed-Media

supported

Subsystems

and

LNOl

(not

Laser

supported

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT
Name

Device

TU78 Magnetic Tape

TU16/TE16/TU45/TU77/TM02/TM03 Magnetic Tape

TSll, TOSO, or TSV05 Magnetic Tape

TMll/TUlO/TUll or TS03 Magnetic Tape

The Null Device

PCll Paper Tape Punch

PCll or PRll Paper Tape Reader

PCLll-A/PCLll-B
Receiver
RSX-llM-PLUS systems only)

Terminals (regardless of interface)

PCLll-A/PCLll-B
Transmitter
RSX-llM-PLUS systems only)

Port

(supported

UDCll Universal Digital Controller (not
RSX-llM-PLUS systems)

supported

DAll-B Parallel Unibus
RSX-llM-PLUS systems)

supported

DLll-E Asynchronous Communication Line Interface
supported in RSX-llM-PLUS systems)

(not

DMCll Synchronous Communication Line Interface

DPll Synchronous Communication Line
supported in RSX-llM-PLUS systems)

Interface

(not

DQll Synchronous Communication Line
supported in RSX-llM-PLUS systems)

Interface

(not

DUll Synchronous Communication Line
supported in RSX-llM-PLUS systems)

Interface

(not

DUPll Synchronous Communication Line Interface

DHll or DHVll
Multiplexer

DLll-A/DLll-B/DLll-C/DLll-D/DLll-E
Asynchronous
Communications Line Interface (DLll-B, DLll-E, DPll,
DQll, and DUll are not supported in RSX-llM-PLUS
systems)

DZll Asynchronous Communications Line Multiplexer

ZA-ZZ

Reserved for customer use (not used by DIGITAL)

Link

Asynchronous

1-20

Port

(not

Communications

Line

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT
1.7.5.2 Pseudo-Device Names - A pseudo-device is a logical device
that can normally be redirected by the operator to another physical
device unit at any time, without requiring changes in programs that
reference the pseudo-device. Dynamic redirection of a physical device
unit affects all tasks in the system;
reassignment by means of the
MCR
REASSIGN
command
affects
only one task.
The following
pseudo-devices are supported, as indicated:

Code

Device

Console listing, normally the line printer.

Console output, normally the main operator's console.

Network remote terminal

System library device, normally the device from which
the system was bootstrapped. For example, LB:
is the
device that tasks such as TKB and MAC access for
default library files.

Null device.

Network pseudo-device for NSP.

Network pseudo-device for DLX.

On-line
only) •

Spooling scratch disk device.

User default device.
On nonmultiuser systems, SY:
is
normally
the
disk
from
which
the system was
bootstrapped. On multiuser systems, SY:
is normally
the default login device.

Virtual Device.

Pseudo-input terminal;
TIO:
which a task was requested.

reconfiguration

pseudo-device

the

(RSX-UM-PLUS

terminal

from

The pseudo-device TI cannot be redirected, since such
redirection would have to be handled on a per-task
rather than a system-wide basis (that is, change the TI
device
for
one
task
without affecting the TI
assignments for other tasks) •
VT

1.7.6

Virtual terminal.
Used by some RSX-llM-PLUS offspring
tasks as TI:
for command and data I/O.
(Supported in
RSX-llM-PLUS systems only).

The GLUN$ Macro:

Retrieving LON Information

The Get LUN Information macro requests that information about a
LUN-physical device unit association be returned in a 6-word buffer
specified by the issuing task.
Upon successful completion of the
directive processing; the buffer contains the information listed in
Table 1-1, as appropriate for the specific device.
All three forms of
the macro call may be used.
It is issued from a MACR0-11 program in
the following way:
GLUN$

lun,buf

1-21

RSX-llM/M-PLUS INPOT/OOTPOT
lun
The logical unit number associated with the physical device
for which information is requested.

unit

buf
The 6-word buffer to which information is returned.
For example, to request information on the disk unit
LON 8, the following call is issued:
GLUN$C

associated

with

8.,IOBUF
Table 1-1
Get LUN Information

Numerical Offset
Word Byte Bit
0
1

Word

Symbolic Offset
Byte
Bit

G.LUNA

Contents
Name of device associated
LUN (ASCII bytes)

with

G.LUNU

Unit number of associated device

G.LUFB

Driver flag value.
Returned as
200
octal
if the driver is
resident, or as 0 if a loadable
driver is not in the system

G.Lucwl

2
0

(U .CWl)

First
word:
(DV .REC)

device

characteristics

Unit record-oriented device
example,
card
reader,
printer) (1 = yes)

(for

line

(DV.CCL)

Carriage-control
device
(for
example, line printer, terminal)
(1 = yes)

(DV.TTY)

Terminal device (1 = yes)

(DV.DIR)

Directory device
DECtape, disk) (1

(DV.SDI)

Single directory
device
(for
example, ANSI-standard mag tape)
(1 = yes)

(DV. SQD)

Sequential device
(for example,
ANSI-standard magtape) (1 = yes)

(DV.MSD)

Mass storage device (for example,
disks and tapes) (1 = yes)

(for

= yes)

example,

1. The following word and bit symbols shown in parentheses are symbols used in
defining and referencing corresponding items in the device UCB.

(continued on next page)

1-22

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT

Table 1-1
(Cont.)
Get LUN Information
Numerical Off set
Word Byte Bit

Symbolic Offset
Byte
Bit
(DV.UMD)

User-mode
(1 = yes)

(DV.EXT)

Device supports
addressing

(DV.SWL)

Unit
software
(1 = yes)

(DV.ISP)

= yes)
Output spooled device (1 = yes)
Pseudo-device (1 = yes)

supported

22-bit

direct

write-locked

Input spooled device (1

(DV.OSP)

(DV.PSE)

(DV.COM)

Device
mountable
as
a
communications
channel
for
Digital network
support
(for
example, DPll, DUll) (1 = yes)

(DV.Fll)

Device mountable as a
device
(for example,
DECtape) (1 = yes)

FILES-11
disk or

(DV.MNT)

Device mountable {logical
bi ts 13 and 14) (1 = yes)

G.LUCW+02

Second
word:
(U2 .xxx)

device

characteristics

Device-specific information

G.LUCW+04
(U.CW3)

diagnostics

(U.CW2)
4

Contents

Word

Third
word:
{U3.xxx)

device

characteristics

Device-specific information2

G.LUCW+06

Fourth
word:

(U.CW4)

Default buffer size {for example,
for disks, and line length for
terminals) •

device

characteristics

2. For mass storage devices, such as disks, DECtape, and DECtape II, this is
the number of blocks (maximum logical block number plus one). For the proper
use of the RX211/RX02 flexible disk, it is important to be able to test
G.LUCW+4 to determine the media density.

1-23

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT
The example included below illustrates the use of the three
the GLUN$ macro.

forms

DATA DEFINITIONS
GETLUN: GLUN$

6,DSKBUF

GENERATE DPB

EXECUTABLE SECTION

1.7.7

DIR$

#GETLUN

EXECUTE DIRECTIVE

GLUN$C

6,DSKBUF

GENERATE DPB IN SEPARATE PROGRAM
SECTION, THEN GENERATE CODE TO
EXECUTE THE DIRECTIVE

GLUN$S

#6,#DSKBUF

GENERATE DPB ON STACK, THEN
EXECUTE DIRECTIVE

The ASTX$S Macro:

Terminating AST Service

The AST Service Exit macro is used to terminate execution of an AST
service routine.
All forms of the macro are provided. However, the
S-form is preferred because it requires less space and executes at
The macro is
least as fast as the ASTX$ or ASTX$C form of the macro.
issued in the following way:
ASTX$S

[err]

err
An optional argument which specifies the address of an error
routine to which control branches if the directive is rejected.
On completion of the operation specified in this macro call,
if
another AST is queued and asynchronous system traps have not been
disabled, then the next AST is immediately entered.
Otherwise, the
task's state before the AST was entered is restored (it is the AST
service routine's responsibility to save and restore the registers it
uses) •

1.7.8

The WTSE$ Macro:

Waiting for an Event Flag

The Wait For Single Event Flag macro instructs the system to suspend
execution of the issuing task until the event flag specified in the
macro call is set.
This macro is extremely useful
in synchronizing
activity on completion of an I/0 operation. All three forms of the
macro call may be used.
It is issued as follows:
WTSE$

efn

1-24

RSX-llM/M-PLUS INPUT/OUTPUT

efn
The event flag number.
WTSE$ causes the task to be blocked from execution until the specified
event flag is set. Frequently, an efn parameter is also included in a
QIO$ macro call, and the event flag is set on completion of the I/O
operation specified in that call. The following example illustrates
task blocking until the setting of the specified event flag occurs.
This example also illustrates the use of the three forms of the macro
call.
DATA DEFINITIONS
WAIT:
IOSB:

WTSE$
.BLKW

5
2

GENERATE DPB
I/0 STATUS BLOCK

EXECUTABLE SECTION

1.8

ASSIGN LON 14 TO MAGTAPE UNIT ZERO
ATTACH DEVICE
EXECUTE WAITFOR DIRECTIVE

ALUN$S
QIO$C
DIR$

#14. ,# 11 MM
IO.ATT,14.,5
#WAIT

QIO$S

#IO.RLB,#14.,#2,,#IOSB,,<#BUF,#80.>
; READ RECORD, USE EFN2

WTSE$S

QIO$C

IO.WLB,14.,3,,IOSB,,<BUF,80.>
; WRITE RECORD, USE EFN3

WTSE$C

WAIT FOR WRITE TO COMPLETE

QIO$C

IO.DET,14.

DETACH DEVICE

WAIT FOR READ TO COMPLETE

STANDARD I/0 FUNCTIONS

The number of input/output operations that can be specified by means
of the QIO directive is large.
A particular operation can be
requested by including the appropriate function code as the first
parameter of a QIO macro call. Certain functions are standard. These

1-25

RSX-llM/M-PLUS INPUT/OUTPUT
functions are almost totally device independent and can thus be
requested ·for nearly every device described in this manual. Others
are device dependent and are specific to the operation of only one or
two I/O devices.
This section summarizes the function codes and
characteristics of the following device-independent I/O operations:

• Attach to an I/O device
• Detach from an I/O device
• Cancel I/O requests
• Read a logical block
• Read a virtual block

• Write a logical block

• Write a virtual block
For certain physical device units discussed in this manual, a standard
I/O function may be described as being a NOP. This means that no
operation is performed as a result of specifying the function, and an
I/O status code of rs.sue is returned in the I/O status block
specified in the QIO macro call.
In the following descriptions and in formats shown in subsequent
chapters, the five QIO directive parameters lun, efn, pri, isb, and
ast are represented by the ellipsis ( ••• ) (see Section 1.5.1).

1.8.1

IO.ATT:

Attaching to an I/O Device

The function code IO.ATT is specified by a user task when that task
requires exclusive use of an I/O device.
This function code is
included as the first parameter of a QIO macro call in the following
way:
QIO$C

IO.ATT, .••

Successful completion of an IO.ATT request causes the specified
physical device unit to be dedicated for exclusive use by the issuing
task. This enables the task to process input or output in an unbroken
stream and is especially useful on sequential, non-file-oriented
devices such as terminals, card readers, and line printers.
An
attached physical device unit remains under control of the issuing
task until it is explicitly detached by that task.
To detach the
device, the task can specify any LUN previously assigned to the
attached device.
While a physical device unit is attached, the I/O driver for that unit
dequeues only I/O requests issued by the task that issued the attach.
Thus, a request to attach a device unit already attached by another
task will not be processed until the attachment is broken and no
higher priority request exists for the unit. A LUN that is associated
with an attached physical device unit may not be reassigned by means
of an Assign LON directive except when at least one LUN is still
assigned to the attached device.

1-26

April 1983

RSX-llM/M-PLUS INPUT/OUTPUT
If the task that issued an attach function exits or is aborted before
it issues a corresponding detach, the Executive automatically detaches
the physical device unit.

1.8.2

IO.DET: Detaching from an I/O Device

The function code IO.DET is used to detach a physical device unit that
has been previously attached by means of an IO.ATT request for
exclusive use of the issuing task.
This function code is included as
the first parameter of a QIO macro call in the following way:
QIO$C

IO.DET, •••

The LUN specifications of both IO.ATT and IO.DET must be the same,
as
in the following example, which also illustrates the use of s- forms
of several macro calls.

LOOP:

1.8.3

.MCALL
ALUN$S

ALUN$S,QIO$S
#14.,#"CR

ASSOCIATE CARD READER WITH LUN 14

QIO$S

#IO.ATT,#14.

ATTACH CARD READER

QIO$S

#IO.RLB,#14., •••

QIO$S

#IO.DET,#14.

READ CARD

DETACH CARD READER

IO.KIL: Canceling I/O Requests

The function IO.KIL is issued by a task to cancel all of
I/O requests for a particular physical device unit.

that

task's

For I/O requests waiting for service -- that is, in the
I/O driver's
queue -- a status code of IE.ABO is returned in the I/O status block.
An event flag is set, if specified.
But any AST service routine that
may have been specified is not initiated.
For I/O requests being processed by an I/O driver -- other than the
disk or DECtape drivers -- the IE.ABO status code is returned.
Other
status information (byte count, and so forth) is also returned in the
I/O status block. An AST, if specified, is activated.
For disk, DECtape, or DECtape II I/O requests being processed when an
IO.KIL is issued, the IO.KIL acts as a NOP.
The request is allowed to
complete, except in the case in which a DECtape transfer is blocked by
a select error.
Because disk and DECtape operate quickly, IO.KIL
simply causes the return of rs.sue in the I/O status block.
This function code is included as the first parameter of a
in the following way:
QIO$C

QIO

macro

IO.KIL, •••

IO.KIL is useful in such special cases as canceling an I/O request on
a
physical device unit from which a response is overdue (for example,
a read on a paper tape reader) •

1-27

RSX-llM/M-PLUS INPUT/OUTPUT
1.8.4

IO.RLB: Reading a Logical Block

The function code IO.RLB.is specified by a task to read a block of
data from the physical device unit specified in the macro call. This
function code is included as the first parameter of a QIO macro in the
following way:
QIO$C

IO.RLB, ••• ,<stadd,size,pn>

stadd
The starting address of the data buffer.
size
The data buffer size in bytes.
pn
One to four optional parameters, used to specify such
information as block numbers for certain devices.

1.8.5

additional

IO.RVS: Reading a Virtual Block

The function code IO.RVS is used to read a virtual block of data from
the physical device unit specified in the macro call. A "virtual"
block indicates a relative block position within a file and is
identical to a "logical" block for such sequential, record-oriented
devices as terminals and card readers.
For these
sequential,
record-oriented devices, IO.RVB is converted to IO.RLB before being
issued.
NOTE
Any subfunction bits specified in the
IO.RVB request (see Sections 2.3.1 and
3.3.1) are
stripped
off
in
this
conversion.
It is recommended that all tasks use virtual rather than logical
reads.
However, if a virtual read is issued for a file-structured
device (disk, DECtape, or DECtape II), the user must ensure that a
file is open on the specified physical device unit. This function
code is included as the first parameter of a QIO macro call in the
following way:
QIO$C

IO.RVB, ••• ,<stadd,size,pn>

stadd
The starting address of the data buffer.
size
The data buffer size in bytes.

1-28

RSX-llM/M-PLUS INPUT/OUTPUT
pn
One to four optional parameters, used to specify such
information as block numbers for certain devices.

1.8.6

additional

IO.WLB: Writing a Logical Block

The function code IO.WLB is specified by a task to write a block of
data to the physical device unit specified in the macro call. This
function code is included as the first parameter of a QIO macro call
in the following way:
QIO$C

stadd
The starting address of the data buffer.
size
The data buffer in bytes.
pn
One to four optional parameters, used to specify such additional
information as block numbers or format control characters for
certain devices.

1.8.7

IO.WVB: Writing a Virtual Block

The function code IO.WVB is used to write a virtual block of data to a
physical device unit.
A "virtual" block indicates a block position
relative to the start of a file.
For sequential, record-oriented
devices such as terminals and line printers, the function IO.WVB is
converted to IO.WLB.
NOTE
Any subfunction bits specified in the
IO.WVB request (see Sections 2.3.1 and
3.3.1) are
stripped
off
in
this
conversion.
It is recommended that all tasks use virtual rather than logical
writes.
However, if a virtual write is issued for a file-structured
device (disk, DECtape, or DECtape II), the user must ensure that a
file is open on the specified physical device unit. This function
code is included as the first parameter of a QIO macro call in the
following way:
QIO$C

IO.WVB, .•• ,<stadd,size,pn>

stadd
The starting address of the data buffer.

1-29

RSX-llM/M-PLUS INPUT/OUTPUT
size
The data buffer size in bytes.
pn
One to four optional parameters, used to specify such additional
information as block numbers or format control characters for
certain devices.

1.8.8

User-Mode Diagnostic Functions

The I/O function code subfunction bit, IQ.UMD, provides support for
user-mode diagnostics.
To perform a diagnostic function, you must
specify in the QIO directive parameter block the logical OR of IQ.UMD
and the function you want to perform.
For example, to perform a
diagnostic Read Logical Block operation, specify IO.RLB!IQ.UMD as the
I/O function code parameter to the QIO directive. You can perform
standard I/O functions such as Read
Logical Block, Write Logical
Block, Attach to Device, and Detach from Device in diagnostic mode.
Support for user-mode diagnostics is always present for RSX-llM-PLUS,
but
not
all
drivers
support user-mode diagnostic functions.
Unpredictable device and driver behavior results when you set the
IQ.UMD subfunction bit in QIOs that are directed to the device if it
does not support user-mode diagnostics.
Problems can be avoided if
you do a Get LUN directive and check the user-mode diagnostics bit
before emitting the user-mode diagnostic QIO.
To support user-mode diagnostics, the DV.UMD bit in the
set.
DV.UMD is at offset U.CWl in the UCB.

must

In addition to standard
I/O functions,
RSX-llM-PLUS provides
following device-dependent, user-mode diagnostic functions:

the

UCB

Disk diagnostic functions
•

IO.HMS

Home seek or recalibrate

IO.BLS

Block seek (explicit seek)

IO.OFF

Offset position

IO.ROH

Read disk header

IO.WDH

Write disk header

•

IO.WCK

Writecheck

DECtape diagnostic functions
•

IO.RNF

Read block number forward

IO.RNR

Read block number reverse

Magtape diagnostic functions
e

IO.LPC

Read longitudinal parity character

•

IO.ERB

Erase tape

UMDIO$ is the macro that defines these functions.

1-30

RSX-llM/M-PLUS INPUT/OUTPUT

To execute a us~r-mode diagnostic function, you must first attach
diagnostics using I/O function code IO.ATT!IQ.UMD.
Execute
diagnostic functions and then detache

for
the

The parameter list in words 1 through 6 of the DPB should contain
following information:

the

•

I/O buff er address

•

I/O buffer size

•

Offset factor for disks with offset recovery (to determine the
offset factor, refer to the offset register in the hardware
reference manual); this parameter is not used if the device
does not have offset recovery.

•

Double-precision logical block number

•

User's register buffer address {the I/O driver copies
hardware registers to this buffer in the user's program);
a hardware reference manual for the length of the address

see

A typical DPB for a diagnostic function might look like the following:
$DSKPB::
• BYTE
.WORD
.WORD
.BYTE
.WORD
.WORD
$IOBUF:: .WORD
.WORD
.WORD
SLBH::
.WORD
$LBL::
• WORD
.WORD

Size of the DPB, QIOWAIT directive code
I/O function code
Logical Unit Number
Event flag number
I/O status block address
AST address
Buffer address
Transfer size in bytes
Device dependent
High-order logical block number
Low-order logical block number
Register buffer address

3,12 •
IO.WDH!IQ.UMD
THELUN
THEEFN,O
$IOSTS
0
0

0
0

$RGBUF

The user-mode diagnostic functions return either Success (IS.SUC) or
Device Not Ready (IE.DNR). No other error codes are returned. All
error recovery is completely up to the user. Any errors that occur
will not be logged in the error log.
A typical program fragment, using the user-mode diagnostic
might look like the following:

functions,

.MCALL UMDIO$,ALUN$S,QIO$S
UMDIO$
ALUN$S
QIO$S

#14.,#"DM,#0
#14.,#"DM,#0

QIO$S

#IO.ATT!IQ.UMD,#14.

QIOSS

#IO~RDH!IQ.UMD,#14.,,,,,<#$IOBUF,#512.,,#LBH,ILBL,#$RGBUF>

Read disk header

QIO$S

#IO.RLB!IQ.UMD,#14.,,,,~<1$IOBUF,l512.,,ILBH,ILBL,l$RGBUF>

Read logical block

QIO$S

#IO.DET!IQ.UMD,114.

Define diagnostic functions
; Associate DMO with lun 14
; Associate DMO with lun 14

Attach DM for diagnostic I/O

Detach DM

1-31

RSX-llM/M-PLUS INPUT/OUTPUT

1.9

I/O COMPLETION

When an I/O request has been completed, either successfully or
unsuccessfully, one or more actions may be taken by the Executive.
Selection of return conditions depends on the parameters included in
the QIO macro call. There are three major returns:
1.

A significant event is declared on completion of an I/O
operation.
If an efn parameter was included in the I/O
request, the corresponding event flag is set.

If an isb parameter was specified in the QIO macro call, a
code identifying the type of success or failure is returned
in the low-order byte of the first word of the I/O status
block at the location represented by isb.
This status return code is of the form IS.xxx (success) or
IE.xxx (error).
For example, if the device accessed by the
I/O request is not ready, a status code of IE.DNR is returned
in isb. The section below (Return Codes) summarizes general
codes returned by most of the drivers described in this
manual.
If the isb parameter was omitted, the requesting task cannot
determine whether the I/O request was successfully completed.
A carry clear return from the directive itself simply means
that the directive was accepted and the I/O request was
queued, not that the actual input/output operation was
successfully performed.

If an ast parameter was specified in the QIO macro call, a
branch to the AST servic~ routine that begins at the location
identified by ast occurs on completion of the I/O operation.
See Section 1.5.3 for a detailed description of AST service
routines.

RETURN CODES

1.10

There are two kinds of status conditions recognized
RSX-llM/M-PLUS when they occur in I/O requests:
the

and

handled

acceptance

•

Directive conditions, which indicate
rejection of the QIO directive itself

•

I/O status conditions, which indicate the success
of the I/O operation

Directive conditions relevant to I/O operations may
the following:
•

Directive acceptance

•

Invalid buffer specification

•

Invalid efn parameter

•

Invalid lun parameter

•

Invalid DIC number or DPB size

•

Unassigned LUN

•

Insufficient memory

1-32

indicate

failure
any

RSX-llM/M-PLUS INPUT/OUTPUT

A code indicating the acceptance or rejection of a directive is
returned to the Directive Status Word at symbolic location $DSW. This
location can be tested to determine the type of directive condition.
I/O conditions indicate the success or failure of the I/O operation
specified in the QIO directive.
I/O driver errors include such
conditions as device not ready, privilege violation, file already
open, or write-locked device.
If an isb parameter is included in the
QIO directive, identifying the address of a 2-word I/O status block,
an I/O status code is returned in the low-order byte of the first word
of this block on completion of the I/O operation.
This code is a
binary value corresponding to a symbolic name of the form IS.xxx or
IE.xxx. The low-order byte of the word can be tested symbolically, by
name, to determine the type of status return. The correspondence
between global symbolic names and directive and I/O completion status
codes is defined in the system object module library. Local symbolic
definitions may also be obtained by the DRERR$ and IOERR$ macros,
which reside in the System Macro Library and are summarized in
Appendix B.
Binary values of status codes always have the following meanings:
Meaning

Code
Positive (greater than 0)

Successful completion

Operation still pending

Negative

Unsuccessful completion

A pending operation means that the I/O request is still in the queue
of requests for the respective driver, or the driver has not yet
completely serviced the request.

1.10.1

Directive Conditions

Table 1-2 summarizes the directive conditions that may be encountered
in QIO directives.
The acceptance condition is first, followed by
error codes indicating various reasons for rejection, in alphabetical
order.
Table 1-2
Directive Conditions
Reason

Code

rs.sue

Directive accepted
The first six parameters of the QIO directive were
valid, and sufficient dynamic memory was available
to allocate an I/O packet.
The directive is
accepted.

IE.ADP

Invalid address
The I/O status block or the QIO DPB was outside of
the issuing task's address space or was not aligned
on a word boundary.
(continued on next page)
1-33

RSX-llM/M-PLUS INPUT/OUTPUT

Table 1-2 (Cont.)
Directive Conditions
Reason

Code
IE.IEF

Invalid event flag number
The efn specification in a QIO directive
than 0 or greater than 96.

IE.ILU

was

less

Invalid logical unit number
The lun specification in a QIO directive was
invalid for the issuing task. For example, there
were only 5 logical unit numbers associated with
the task, and the value specified for lun was
greater than 5.

IE.SOP

Invalid DIC number or DPB size
The directive identification code (DIC) or the size
of
the
Directive
Parameter Block (DPB) was
incorrect; the legal range for a DIC is from 1
through 127, and all DIC values must be odd. Each
individual directive requires a DPB of a certain
size.
If
the size is not correct for the
particular directive, this code is returned.
The
size of the QIO DPB is always 12 words.

IE.ULN

Unassigned LUN
The logical unit number in the QIO directive was
not associated with a physical device unit. The
user may recover from this error by issuing a valid
Assign
LUN
directive and then reissuing the
rejected directive.

IE.UPN

Insufficient dynamic memory
There was not enough dynamic memory to allocate an
I/O packet for the I/O request~ The user can try
again later by blocking the task with a Waitfor
Significant Event directive.
Note that Waitfor
Significant Event is the only effective way for the
issuing task to block its execution, since other
directives that could be used for this purpose
themselves
require
dynamic
memory for their
execution (for example, Mark Time).

1.10.2

I/O Status Conditions

The following list summarizes status codes that may be returned in the
I/O status block specified in the QIO directive on completion of the
I/O request. The I/O status block is a 2-word block with the
following format:
•

The low-order byte of the first word receives a status code of
the form IS.xxx or IE.xxx on completion of the I/O operation.

•

The high-order byte of the first word is usually device
dependent;
in cases where the user might find information in
this byte helpful, this manual identifies that information.

1-34

RSX-llM/M-PLUS INPUT/OUTPUT

•

The second word contains the number of bytes transferred or
processed if the operation is successful and involves reading
or writing.

If the isb parameter of the QIO directive is omitted, this information
is not returned.
The following illustrates a sample 2-word
completion of a terminal read operation:

Word 0
l

1-10.

I/O

status

block

Byte

Number of bytes read

where -10 is the status code for IE.EOF (end of file).
If this code
is returned, it indicates that input was terminated by typing CTRL/Z,
which is the end-of-file termination sequence on a terminal.
To test for a particular error condition, the user generally compares
the low-order byte of the first word of the I/O status block with a
symbolic value, as in the following:
CMPB

#IE.DNR,IOSB

However, to test for certain types of successful completion of the I/O
operation, the entire word value must be compared. For example, if a
carriage return terminated a line of input from the terminal, a
successful completion code of IS.CR is returned in the I/O status
block. If an Escape (or Altmode) character was the terminator, a code
of IS.ESC is returned.
To check for these codes, the user should
first test the low-order byte of the first word of the block for
rs.sue and then test the full word for rs.cc, IS.CR, IS.ESC, or
IS.ESQ.
(Other success codes that must be read in this manner are
listed in Appendix B, Section B.1.2.)
Note that both of the following comparisons will test as
the low-order byte in both cases is +l.
CMP

#IS.CR,IOSB

CMPB

#IS.SUC,IOSB

equal

since

In the case of a successful completion where the carriage return is
the terminal indicator (IS.CR), the following illustrates the status
block:

Word 0
1

J+1

Byte

Number of bytes read
(excluding the CR)

where 15 is the octal code for carriage return and +l
code for successful completion.

the

status

The codes described in Table 1-3 are general status codes that apply
to the majority of devices presented in subsequent chapters. Error
codes specific to only one or two drivers are described only in
relation to the devices for which they are returned. The list below
describes successful and pending codes first, then error codes in
alphabetical order.

1-35

RSX-llM/M-PLUS INPUT/OUTPUT
Table 1-3
I/O Status Conditions
Code

rs.sue

Reason
Successful completion
The I/O operation specified in the QIO directive
was completed successfully.
The second word of the
I/O status block can be examined to determine the
number
of
bytes processed,
if the operation
involved reading or writing.

IS.PND

I/O request pending
The I/O operation specified in the QIO directive
has not yet been executed.
The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified
I/O operation was cancelled with
IO.KIL while in progress or while still in the I/O
queue.

IE.ALN

File already open
The task attempted to open a file on the physical
device unit associated with the specified LUN, but
a file has already been opened by the issuing task
on that LUN.

IE.BAD

Bad parameter
An illegal specification was supplied for one or
more of the device-dependent QIO parameters (words
6-11).
For example, a bad channel number or gain
code
was
specified
in
an analog-to-digital
converter I/O operation.

IE.BBE

Bad block on device
One or more bad blocks were found by executing the
BAD utility.
Data cannot be written on bad blocks.

IE.BLK

Illegal block number
An
illegal block number was specified for
a
file-structured physical device unit.
This code is
returned, for example, if block 4800 is specified
for an RK05 disk,
on which legal block numbers
extend from 0 through 4799.

IE.BYT

Byte-aligned buffer specified.
Byte alignment was specified for a buffer, but only
word
(or double-word)
alignment is legal for the
physical device unit.
For example, a disk function
requiring word alignment was requested, but the
buffer
was
aligned
on
a
byte
boundary.
Alternately,
the length of a buffer was not an
appropriate multiple of bytes.
For example, all
RP03 disk transfers must be an even multiple of
four bytes.
(continued on next page)
1-3~

RSX-llM/M-PLUS INPUT/OUTPUT
Table 1-3
(Cont.)
I/O Status Conditions
Code
IE.DAA

Reason
Device already attached
The physical device unit specified in an IO.ATT
function was already attached to the issuing task.
This code indicates that the issuing task has
already attached the desired physical device unit,
not that the unit was attached by another task.

IE.DNA

Device not attached
The physical device unit specified
in an
IO.DET
function was not attached
to the issuing task.
This code has no bearing on the attachment status
with respect to other tasks=

IE.DNR

Device not ready
The physical device unit specified
in the QIO
directive was not ready to perform the desired I/O
operation.
This code is often returned as the
result of an interrupt time-out;
that is, a
"reasonable" amount of time has passed,
and
the
physical device unit has not responded.

IE.EOF

End-of-file encountered
An end-of-file mark, record, or control
was recognized on the input device.

IE.FHE

character

Fatal hardware error
Controller is physically unable to reach
the
location where
input/output is to be performed on
the device.
The operation cannot be completed.

IE.IFC

Illegal function
A function code was specified
in an I/O request
that was illegal for the specified physical device
unit.
This code is returned if the task attempts
to execute an illegal function or if, for example,
a read function
is requested on an output-only
device, such as the line printer.

IE.NLN

File not open
The task attempted to close a file on the physical
device unit associated with the specified LUN, but
no file was currently open on that LUN.

IE.NOD

Insufficient buffer space
Dynamic storage space has been depleted, and
there
was insufficient buffer space available to allocate
a secondary control block.
For example, if a
task
attempts to open a
file,
buffer space for the
window and file control block must be supplied by
the Executive.
This code is returned when there is
not enough space for such an operation.
(continued on next page)
1-37

RSX-llM/M-PLUS INPUT/OUTPUT
Table 1-3
(Cont.)
I/O Status Conditions
Code
IE.OFL

Reason
Device off line
The physical device unit associated with the
LUN
specified
in the QIO directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE.OVR

Illegal read overlay request
A read overlay was requested and the physical
device unit specified in the QIO directive was not
the physical device unit from which the task was
installed.
The
read overlay function can only be
executed on the physical device unit from which the
task image containing the overlays was installed.

IE.PRI

Privilege violation
The task that issued a request was not privileged
to execute that request.
For example, for the
UDCll and LPSll, a checkpointable task attempted to
connect to
interrupts or to execute a synchronous
sampling function.

IE.SPC

Illegal address space
The buffer requested for a read or write request
was partially or totally outside the address space
of the issuing task.
Alternately, a byte count of
0 was specified.

IE.VER

Unrecoverable error
After the system's standard number of retries have
been attempted
upon encountering an error, the
operation still could not be completed.
This code
is returned in the case of parity, CRC, or similar
errors.

IE.WCK

Write check error
An error was detected during
following a write operation.

IE.WLK

the

check

(read)

Write-locked device
The task attempted to
physical device unit.

1-38

write

write-locked

RSX-llM/M-PLUS INPUT/OUTPUT
1.11

POWER-FAIL RECOVERY PROCEDURES FOR DISKS AND DECTAPE

Power-fail recovery recommendations for various devices are included
in the following chapters, as appropriate, to assist the user in
restoring device operation after a power failure.
For disks and
DECtape, it is recommended that power recovery ASTs be used. The AST
service routine should provide a sufficient time delay, prior to
returning for normal I/O operations, that will allow the disk to
attain normal operating speed before actually attempting read and
write operations.
If QIOs are being used for disk or DECtape I/O operations during
power-fail recovery, an IE.DNR error status may be returned if the
device is not up to operating speed when the request is issued.
When
this error is returned, it is recommended that the user task wait a
sufficient time for the device to attain operating speed, and attempt
the I/O operation again prior to reporting an error. For example, an
RKOS disk may require approximately 1 minute to attain operating speed
after a power failure.

1-39

CHAPTER 2

FULL-DUPLEX TERMINAL DRIVER

2.1

INTRODUCTION

Two terminal drivers are
RSX-llM systems:

available

SYSGEN

options

for

use

A compact, half-duplex terminal driver for use with a wide
variety of terminals, containing all basic features required
for RSX-llM terminal support.
(This terminal driver is not
available on RSX-llM-PLUS systems.) This terminal driver is
described in Chapter 3.

A full-duplex terminal driver, as described in this chapter,
containing all features of the half-duplex terminal driver,
plus the following:
•

Full-duplex operation

•

Type-ahead buffering

•

Eight-bit characters

•

Detection of hard receive errors

•

Increased byte transfer length (8128 bytes)

•

Additional terminal characteristics

•

Additional terminal types

•

Optional time-out on solicited and/or unsolicited input

•

Device-independent cursor control

•

Redisplay of prompt buffer upon CTRL/R or CTRL/U

•

Automatic XOFF character generation upon completion of a
read (except when in the full-duplex mode) , if requested

•

Autobaud speed detection

•

Added hardware support

Note that either terminal driver can be selected during RSX-llM
SYSGEN.
RSX-llM-PLUS systems use the full-duplex terminal driver
only.

2-1

April 1983

•

FULL-DUPLEX TERMINAL DRIVER
Throughout the remainder of this chapter, references made to MCR can
generally be applied to other command line interpreters (for example,
DCL).
In addition, the prompt displayed on a terminal in response to
invoking a command line interpreter will be appropriate for the
specific command line interpreter in use.
For example, when MCR is
invoked, the MCR prompt is displayed as follows:
MCR>
Terminal driver support is provided for a variety of terminal devices,
as listed in Table 2-1. Subsequent sections describe each device in
greater detail.
Table 2-1
Supported Terminal Devices

Model

Columns

ASR-33/35
KSR-33/35
LA12
LAlOO
LA30-P
LA30-S
LA34
LA36
LA38
LA120
LA180S
LQP02
LASO
RT02
RT02-C
VT05B
VT50
VT50H
VT52
VT55
VT61
VTlOO
VT101
VT102
VT105
VT125
VT131
VT132

72
72
132
132
80
80
132
132
132
132
132
132/158
80/96/132
64
1
64
1
72
20
80
12
80
12
80
24
I 24
80
80
24
24
80-132
80-132
24
24
80-132
80-132
24
24
80-132
24
80-132
24
80-132

Lines/
Character
1
Screen
Set
64
64
96
96
64
64
96
64-96
96
96
96
64
64
64
64
64
96
96
96
96
96
96
96
96
96
96

Baud
Range
110
110
50-9600
110-9600
300
110-300
110-300
110-300
110-300
50-9600
300-9600
110-9600
110-4800
110-1200
110-1200
110-2400
110-9600
110-9600
110-9600
110-9600
110-9600
50-9600
50-19200
50-9600
50-19200
50-9600
50-19200
50-19200

U...E.E_er- & Lowercase?
Send
Receive

yes
yes

yes
yes
yes
yes

yes
yes2
yes
yes
yes

yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes

yes
yes
yes
yes
yes
yes
yes
yes
yes
yes

1. Applies only to video terminals.
2. Only for 96-character terminal.
The terminal driver supports the
terminal interfaces summarized in Table 2-2. These interfaces are
described in greater detail in Section 2.9.
Programming is identical
for all interfaces.

2-2

Apr:t,l 1983

FULL-DUPLEX TERMINAL DRIVER
Table 2-2
Standard Terminal Interfaces
Model

Type

DHll

16-line multiplexerl

DHVll

8-line multiplexerJ

DHll-DMll-BB

16-line multiplexer with modem control2

DJll

16-line multiplexer

DLll-A/B/C/D/E/W

Single-line interfaces

DLVll-E/F

Single-line interfaces3

DZll

8-line multiplexer with modem control3

1. Direct memory access
(OMA)
full-duplex terminal driver only.
2. Full-duplex control only.
Bell 103A-type modem.

supported

For example, in

the

USA, a

3. DLVll and DHVll support with modem control is provided
in the full-duplex terminal driver only.
Terminal input lines can have a maximum length of 8128 (8K minus 64)
bytes.
Extra characters of an input line that exceed the maximum line
length generally become an unsolicited input line if the terminal is
not attached with typeahead enabled.

2.1.1

ASR-33/35 Teletypes*

The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals.
No paper-tape reader or punch capability is supported.

2.1.2

KSR-33/35 Teletypes*

The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals.

2.1.3

LA12 Portable Terminal

The LA12 is a personal, portable, hard-copy terminal.

2.1.4

LAlOO DECprinter

The LAlOO is a desk-top, matrix, hard-copy terminal.

1. Teletype is a registered trademark of the Teletype Corporation.
2-3

April 1983

FULL-DUPLEX TERMINAL DRIVER
2.1.5

LA30 DECwriters

The LA30 DECwriter is an asynchronous, hard-copy terminal that is
capable of producing an original and one copy.
The LA30-P is a
parallel model and the LA30-S is a serial model.

2.1.6

LA36 DECwriter

The LA36 DECwriter is an asynchronous terminal that produces hard copy
and operates
in serial mode.
It has an impact printer capable of
generating multipart and special preprinted forms.
The LA36 can
receive and transmit both uppercase and lowercase characters.

2.1.7

LA34/38 DECwriters

The LA34 DECwriter is an asynchronous terminal that produces hard copy
and uses a platen paper feed mechanism.
The LA38 DECwriter includes a detachable tractor
use with continuous forms.

2.1.8

feed

mechanism

for

LA120 DECwriter

The LA120 DECwriter is a hard-copy,
upper- and lowercase terminal,
capable
of
printing
multipart
forms
at
speeds up to 180
characters-per-second. Serial communications speed is selected from
14 baud rates ranging from 50 to 9600 bps;
split transmit and receive
baud rates are supported by the terminal driver.
Hardware features
allow bidirectional printing for maximum printing speed, and also
allow user-selected features, including font size, line spacing, tabs,
margins, and forms control.
These functions can also be set up by the
system by issuing appropriate ANSI-standard escape sequences.

2.1.9

LA180S DECprinter

The LA180S DECprinter is a serial version of the LA180.
It
is a
print-only device
(it has no keyboard) that can generate multipart
forms.
The LA180S can print uppercase and lowercase letters.

2.l.9A

LQP02 Letter-Quality Printer

The LQP02 Letter-Quality Printer
is a
formed character, desktop
printer
incorporating daisywheel
technology.
This letter-quality
printer offers over 100 character sets and handles regular office
stationery up to a maximum of 15 inches, but the print capacity is
13.5 inches.
The lines per inch and characters per inch are software
selectable;
characters at 10 and 12 and lines at 2, 3, 4, 6, and 8.
At 10 characters per inch you get 132 columns and at 12 characters you
get 158 columns.
The buffer capacity is 256 characters.

2-4

April 1983

FULL-DUPLEX TERMINAL DRIVER
2.l.9B

LASO Personal Printer

The LASO Personal Printer is a desktop dot-matrix impact printer.
It
has two print modes;
text mode and enhanced print mode.
In text
mode, it prints at 100 characters per second.
The enhanced print
quality mode prints at 50 characters per second and creates a crisper,
more uniform character than an ordinary dot-matrix printer.
You can
choose characters per inch at 10, 12, or 16 which gives columns at 80,
96, or 132 and lines per inch can be 6, 8, or 12. The buffer capacity
is 255 characters.

2.1.10

RT02 Alphanumeric
Display
Terminal
Reader/Alphanumeric Display Terminal

and

RT02-C

Badge

The RT02 is a compact, alphanumeric display terminal designed for
applications in which source data is primarily numeric. A shift key
permits the entry of 30
discrete characters,
including uppercase
alphabetic characters. The RT02 can, however, receive and display 64
characters.
The RT02-C model also contains a badge reader. This option provides a
reliable method of identifying and controlling access to the PDP-11 or
to a secure facility. Furthermore, data in a format corresponding to
that of a badge (22-column fixed data) can be entered quickly.

2-4.1

April 1983

FULL-DUPLEX TERMINAL DRIVER
2.1.11

VTOSB Alphanumeric Display Terminal

The VTOSB is an alphanumeric display terminal that consists of a CRT
display and a self-contained keyboard. From a programming point of
view, it is equivalent to other terminals, except that the VT05B
offers direct cursor addressing.

2.1.12

VTSO Alphanumeric Display Terminal

The VT50 is an alphanumeric display terminal that consists of a CRT
display and a keyboard. It is similar to the VT05B in operation, but
does not offer direct cursor addressing.

2.1.13

VTSOH Alphanumeric Display Terminal

The VT50H is an alphanumeric display terminal with CRT display,
keyboard, and numeric pad. It offers direct cursor addressing.
(The
VT50H's direct cursor addressing is not compatible with that of the
VTOSB.)

2.1.14

VT52 Alphanumeric Display Terminal

The VT52 is an upper- and lowercase alphanumeric terminal with numeric
pad
and
direct cursor addressing.
(The VT52's direct cursor
addressing is compatible with that of the VT50H, not with that of the
VTOSB.) The VT52 can be configured with a built-in thermal printer.

2.1.15

VT55 Graphics Display Terminal

The VT55 is similar to the VT52 in its operation as an alphanumeric
terminal.
The VT55 offers graphics display features that are not
supported by RSX-llM, although the system allows a knowledgeable task
to access the explicitly special features of the VT55.

2.1.lo

VT61 Alphanumeric Display Terminal

The VT61 is an "intelligent" upper- and lowercase alphanumeric
terminal with an integral microprocessor. It offers two 128-member
character sets and numerous built-in functions for editing and forms
preparation as well as a block-transfer mode.
(None of these special
features is supported by RSX-llM.)

2.1.17

VTlOO DECscope

The VTlOO DECscope is an
upperand
lowercase
alphanumeric
keyboard/video display terminal. It is capable of displaying 24 lines
of 80 to 132 characters (each line). Serial communications speed is
selected from baud rates ranging from 50 to 9600 bps. Hardware
features allow user selection of display characteristics and functions
including smooth scroll, reverse video, and so forth. These functions
can also be set up by the system by issuing appropriate ANSI-standard
escape sequences.

2-5

FULL-DUPLEX TERMINAL DRIVER
2.1.18

VTlOl DECscope

The VT101 DECscope is functionally identical to the
it does not support the advanced video features.

2.1.19

VTlOO.

However,

VT102 DECscope

The VT102 DECscope is functionally identical to the VTlOO.
However,
it does not have any expansion capability and does not support the
advanced video features.
It has enhanced modem control and it
includes a port for a printer.

2.1.20

VTlOS DECscope

The VT105 DECscope is a video terminal.
It has both alphanumeric and
graphic display. The VT105 can display two graphs, two shaded graphs,
or two strip charts. These graphs may have alphanumeric labels.

2.1.21

VT131 DECscope

The VT131 is the same as the
editing features.

2.2

VT102

with

the

addition

built-in

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for terminals.
A setting of 1 indicates that the
described characteristic is true for terminals.
Bit

Setting

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

2-6

FULL-DUPLEX TERMINAL DRIVER
Bit

Setting

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 of the buffer
(the
default buff er size
screen).

2.3

Meaning

are
undefined.
Word
5 indicates the
width of the terminal carriage or display

QIO MACRO

Table 2-3 lists the standard and device-specific functions of the QIO
macro that are valid for terminals.
Some device-specific functions
are options that may be selected during SYSGEN.
Two device-specific functions, SF.SMC and SF.GMC,
have nonstandard
retained
for compatibility with
function names.
These names are
RSX-llD.
Table 2-3
Standard and Device-Specific QIO Functions for Terminals
Function

Format
STANDARD FUNCTIONS:
QIO$C IO.ATT, •••

Attach device.

QIO$C IO. DET, •••

Detach device.

QIO$C IO.KIL, •.•

Cancel I/O requests.

QIO$C IO.RLB, ••• ,<stadd,size[,tmo]>

READ logical block
(read typed input into
buffer) •

QIO$C IO.RVB, ••• ,<stadd,size[,tmo]>

READ virtual block
(read typed input into
buffer) •

QIO$C IO.WLB, ••• ,<stadd,size,vfc>

WRITE logical block
(print buffer
contents) •

QIOSC IO.WVB, ••• ,<stadd,size,vfc>

WRITE virtual block
(print butfer
contents) •
(continued on next page)

2-7

FULL-DUPLEX TERMINAL DRIVER
Table 2-3 (Cont.)
Standard and Device-Specific QIO Functions for Terminals
Format

Function

DEVICE-SPECIFIC FUNCTIONS:
QIO$C IO.ATA, ••• ,<ast,
[parameter 2] [ , as t 2] > 1

ATTACH device, specify
unsolicited-inputcharacter AST.

QIO$C IO.CCO, ••• ,<stadd,size,vfc>

CANCEL CTRL/O (if in
effect), then write
logical block.

QIO$C SF.GMC, ••• ,<stadd,size>l

GET multiple
characteristics.

QIO$C IO.GTS, ••• ,<stadd,size>l

GET terminal support.

QIO$C IO. HNG, •••

HANGUP remote line.

QIO$C IO.RAL, ••• ,<stadd,size[,tmo]>

READ logical block,
pass all bi ts.

QIO$C IO.RNE, ••• ,<stadd,size[,tmo]>

READ logical block, do
not echo.

QIO$C IO.RPR, ••• ,<stadd,size,
[ tm o] , pr add , pr s i z e , v f c > 1

READ logical block
after prompt.

QIO$C IO.RST, ••• ,<stadd,size[,tmo]>

READ logical block
ended by special
terminators.

QIO$C IO.RTT, ••• ,<stadd,size,
[tmo] ,table>

READ logical block
ended by specified
special terminator.

QIO$C SF.SMC, ••• ,<stadd,size>l

SET multiple
characteristics.

QIO$C IO.WAL, ••• ,<stadd,size,vfc>

WRITE logical block,
pass all bi ts.

QIO$C IO.WBT, ••• ,<stadd,size,vfc>l

WRITE logical block,
break through any I/O
conditions at
terminal.

ast
The entry point for an unsolicited- input-character AST.
parameter 2
A number that can be used to identify this terminal as the
source upon entry to an unsolicited character AST routine.
l. SYSGEN options in RSX-iiM.

2-8

input

FULL-DUPLEX TERMINAL DRIVER
ast2
The entry point for an unsolicited CTRL/C AST.
pr add
The starting address of the
stored.

byte

buffer

where

the

prompt

prsize
The size of the pradd prompt buffer in bytes. The specified size
must be greater than 0 and less than or equal to 8128.
The
buffer must be within the task's address space.

size
The size of the stadd data buffer in bytes.
The specified size
must be greater than 0 and less than or equal to 8128.
The
buffer must be within the task's address space.
For SF.GMC,
IO.GTS, and SF.SMC functions, size must be an even value.
st add
The starting address of the data buffer.
The address must be
word aligned for SF.GMC, IO.GTS, and SF.SMC;
otherwise, stadd
may be on a byte boundary.
table
The address of the 16-word special terminator table.
tmo
An optional time-out count in 10-second intervals for
the
full-duplex terminal driver.
If 0 is specified, no time-out can
occur. Time-out is the maximum time allowed between two input
characters before the read is aborted.
The maximum timeout value
is 255.
vf c
A character for vertical format
Section 2.7).

2.3.1

control

from

Table

2-11

(see

Subfunction Bits

Most device-specified functions supported
by
terminal
drivers
described in this section are selected using "subfunction bits." One
or more functions can be selected by ORing their relative bits in a
~iv
function.
Table 2-4 contains a
listing of QIO functions and
relative subfunction bits that can be issued.

2-9

April 1983

FULL-DUPLEX TERMINAL DRIVER
Each subfunction bit and subfunction selected when it is included in a
QIO function is listed as follows:
Symbolic
Name

Subfunction

•
TF.AST
TF .BIN
TF.CCO
TF.ESQ
TF.NOT
TF.RAL
TF.RCU
TF.RNE
TF.RST
TF.TMO
TF.WAL
TF.WBT
TF.XCC
TF.XOF

Unsolicited-input-character AST
Binary prompt
Cancel CTRL/O
Recognize escape sequences
Unsolicited input AST notification;
unsolicited
characters are stored in the type-ahead buffer
until they are read by the task
Read all bi ts
Restore cursor position
Read with no echo
Read with special terminators
Read with time-out
Write all bits
Break-through write
CTRL/C starts a command line interpreter command
line
(Command line characters are not sent to
the task.)
Send XOFF

Table 2-4 lists subfunction bits that can be ORed with QIO functions.
Additional details for using subfunction bits are included in Section
2.3.2.
If a task invokes a subfunction bit that is not supported on the
system,
the subfunction bit is ignored, but the QIO request is not
rejected.
For example,
if break-through write
(TF.WBT)
is not
selected, an
IO.WBT or IO.WLB!TF.WBT function is interpreted as an
IO.WLB function.
The following example is a QIO request using more than one subfunction
bit:
a nonechoed
(TF.RNE) read, terminated by a special terminator
character (TF.RST) and preceded by a prompt.
QIO$C IO.RPR!TF.RNE!TF.RST, ••. ,<stadd,size,,pradd,prsize,vfc>

2.3.2

Device-Specific QIO Functions

Some device-specific functions described in this section are SYSGEN
options.
All except SF.GMC, IO.RPR, SF.SMC, IO.RTT, and IO.GTS can be
issued by ORing a particular subfunction bit with another QIO
function.
These subfunction bits are specified in the following
descriptions;
subfunction bits are described in general in Section
2.3.l.
In addition to the device-specific QIO functions,
this section also
describes the use of subfunction bits TF.ESQ, TF.BIN, and TF.XOF.

2-10

April 1983

Table 2-4
Subfunction Bits - Summary

~~
~~ion

Equivalent
Subfunctions

-·

Allowed Subfunction Bits

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

TF.AST TF. BIN TF.CCO TF.ESQ TF.NOT TF.RAL TF.RCU TF.RNE TF.RST TF.TMO TF WAL TF.WBT TF.XCC TF.XOF

·-

1--·

STANDARD FUNCTIONS

IO.A'fT
IO.DET
IO. KIL
IO.RLB
IO.RVB
IO.WLB
IO.WVB

x
1
2

x
x

1
2

DEVICE-SPECIFIC FUNCTIONS
IO.A'rA
Io.cco
SF.GMC
IO. G'.PS
IO. RAL
IO.RNE
IO.RJ?R
IO.RST
IO.R'.PT
SF.SMC
IO. WAL
IO.WBT

IO.ATT!TF.AST
IO.WLB!TF.CCO
IO.HLB!TF.RAL
IO.HLR!TF.RNE

x
x
1

1
1

IO.HLB!TF.RST
1

IO.WLB!TF.WAL
IO.WLB!TF.WBT

x
x

x
x
x
x

1. Exercise great care when using Read All and Read with Special Terminators together.
2. These subfunctions are allowed but are not effective.
converted to a read or write logical operation.

x
x
x
x

3
-------'---·

Obscure problems can result.

They are stripped off when the read or write virtual operation

3. During a write-pass-all operation
(IO.WAL or IO.WLB!TF.WAL)
interpretation;
it does not keep track of cursor position.

the

terminal

driver

outputs

characters

without

FULL-DUPLEX TERMINAL DRIVER

2.3.2.1 IO.ATA - IO.ATA is a variation of the Attach function.
The
use of this function is eased by the addition of TF.NOT and TF.XCC
subfunction bits, described later in this section.
IO.ATA specifies
asynchronous
system
traps (ASTs)
to process unsolicited input
characters. When called as follows:
QIO$C

IO.J..TA, ••• ,<[AST] I [PARAMETER2] [ ,AST2] >
NOTE
A minimum of one AST parameter
ast2) is required.

(ast

This function attaches the terminal and identifies "ast" and "ast2" as
entry points for an unsolicited-input-character AST. Control passes
to ast whenever an unsolicited character (other than CTRL/Q, CTRL/S,
CTRL/X, or CTRL/O) is input. If the ast2 parameter is specified, an
unsolicited CTRL/C character will result in entering the AST specified
in that parameter.
If ast2 is not specified, an unsolicited CTRL/C
will result in entering the AST specified in the ast parameter.
Unless the TF.XCC subfunction is specified, CTRL/C is trapped by the
task and does not reach MCR. Thus, any task that uses IO.ATA without
the TF.XCC subfunction should recognize some input sequence as a
request to terminate; otherwise, MCR cannot be invoked to abort the
task in case of difficulty.
Note that either ast2 or TF.XCC can be used, but not both in the same
QIO request. If both are specified in the request, an IE.SPC error is
returned.
Upon entry to the AST routines, the unsolicited character and
parameter 2 are in the top word on the stack, as shown below. That
word must be removed from the stack before exiting the AST.
SP+lO

Event flag mask word

SP+06

PS of task prior to AST

SP+04

PC of task prior to AST

SP+02

Task's directive status word

SP+OO

Unsolicited character in low byte; parameter 2, in the
high byte, is a user-specified value that can be used
to identify individual terminals in a multiterminal
environment

The processing of unsolicited input ASTs is eased through the use of
TF.NOT and TF.XCC subfunction bits. When TF.XCC is included in the
IO.ATA function, all characters (except CTRL/C) are handled in the
manner previously described. CTRL/C marks the beginning of a command
line interpreter (CLI) line that will be processed by a CLI task (for
example, MCR); none of the characters, including the CTRL/C, are sent
to the task issuing the function.
When unsolicited terminal input (except CTRL/C)
is received by the
full-duplex terminal driver and the TF.NOT subfunction is used, the
resulting AST serves only as notification of unsolicited terminal
input;
the terminal driver does not pass the character to the task.
Upon entry to the AST service routine, the high byte of the first word
on the stack identifies the terminal causing the AST (parameter 2).

2-12

FULL-DUPLEX TERMINAL DRIVER
After the AST has been effected, the AST becomes "disarmed" until a
read request is issued by the task.
If multiple characters are
received before the read request is issued, they are stored in the
type-ahead buffer. Once the read request is received, the contents of
the type-ahead buffer, including the character causing the AST,
is
returned to the task;
the AST is then "armed" again for new
unsolicited input characters.
Thus, using the TF.NOT subfunction
allows a task to monitor more than one terminal for unsolicited input
without the need to continuously read each terminal for possible
unsolicited input.
Note that the TF.NOT subfunction cannot be used
with the CTRL/C AST; an unsolicited CTRL/C character flushes the
type-ahead buffer.
See the RSX-llM/llM-PLUS
details on ASTs.

Executive

Reference

Manual

for

further

IO.ATA is equivalent to IO.ATT ORed with the subfunction bit TF.AST.

2.3.2.2 IO.ATT!TF.ESQ - The task issuing this function attaches a
terminal and notifies the driver that it recognizes escape sequences
input from that terminal. Escape sequences are recognized only for
solicited input.
(See Section 2.6 for a discussion of escape
sequences.}
If the terminal has not been declared capable of generating escape
sequences,
IO.ATT!TF.ESQ has no effect other than attaching the
terminal. No escape sequences are returned to the task because any
ESC sent by the terminal acts as a line terminator.
The SF.SMC
function or the MCR SET /ESCSEQ command are used to declare the
terminal capable of generating escape sequences (see Table 2-5 and
Section 2.3.2.12}.

2.3.2.3 IO.CCO - This write function directs the driver to write to
the terminal regardless of a CTRL/O condition that may be in effect.
If CTRL/O is in effect, it is cancelled before the write is done.
IO.CCC is equivalent to IO.WLB!TF.CCO.

2.3.2.4 SF.GMC - The Get Multiple Characteristics
terminal characteristics information, as follows:

function

returns

QIO$C SF.GMC, •.. ,<stadd,size>

st add
The starting address of a data buffer
Each word in the buffer has the form
.BYTE
.BYTE

length

"size"

bytes.

characteristic-name
0

characteristic-name
One of the bit names given in Table 2-5. The value returned in
the high byte of each byte-pair is 1 if the characteristic is
true for the terminal and 0 if it is not true.
For the TC.TTP characteristic (terminal type}, one of the values shown
in Table 2-6 is returned in the high byte.

2-13

FULL-DUPLEX TERMINAL DRIVER
Table 2-5
Full-Duplex Terminal Driver-Terminal Characteristics
for SF.GMC and SF.SMC Functions
Bit
Name

Octal
Value

TC.ABO

Auto-baud detection

SET /ABAUD=TTnn:

TC.ACR

Wrap-around mode

SET /WRAP=TTnn:

TC.AN!

122

ANSI CRT terminal

TC.ASPl

Remote line answer speed

TC.AVO

123

VTlOO-family terminal display

Binary input mode (read-pass-all)
no characters are interpreted
as control characters.

TC.BLK

Terminal is capable of block
mode transfers

TC.CTS

Suspend output to terminal
0 = resume
1 = suspend

TC.DEC

124

Digital CRT terminal

TC.DLU4

Dial-up line

TC.EDT

125

Terminal performs editing functions

TC.EPA

When TC.PAR is enabled:
O=odd parity
l=even parity

~C.ESQ

Input escape sequence
recognition

SET /ESCSEQ=TTnn:

/:"" TC.FOX

Full-duplex mode

SET /FDX=TTnn:

-tTC.HFF

Hardware form-feed capability
(If 0, form-feeds are simulated
using TC.LPP.)

SET /FORMFEED=TTnn:

.11 TC.HFL

Number of fill characters to
insert after a carriage return (0-7=x)
(Use a value of 7 for the LA30-S.)

SET /HFILL=TTnn:x

{TC.HHT

SET /HHT=TTnn:

Horizontal tab capability (if O,
horizontal tabs are simulated using
spaces.)

TC. HLDl

Hold screen mode

SET /HOLD=TTnn:

TC. ISL

Subline on interface (=0-15)

l TC. LPP

I
I

) TC.BIN

I
I

Corresponding
MCR Command

Meaning (if asserted)

SET /REMOTE=TTnn:speed

SET /RPA=TTnn:

SET /REMOTE=TTnn:

l Page length (1-255.=x)

(Read only)

-SET /LINES=TTnn:x

(continued on next page)

2-14

April 1983

FULL-DUPLEX TERMINAL DRIVER
Table 2-5
(Cont.)
Full-Duplex Terminal Driver-Terminal Characteristics
for SFeGMC and SF.SMC Functions
Bit
Name

Octal
Value

TC.NBR

102

Broadcast disabled

SET /NOBRO=TTnn:

Echo suppressed

SET /ECHO=TTnn:

Generate and check parity

f TC.NEC
TC.PAR
TC.PR!

I TC. RAT

I 51
7

Corresponding
MCR Command

Meaning (if asserted)

Terminal is privileged (Read only)

Type-ahead buffer:
0 = 1-character type-ahead
1 = 36-character type-ahead
(RSX-llM only)

II SET /PRIV=TTnn:
I

SET /TYPEAHEAD=TTnn:

TC.RGS

126

TC. RSP2

Receiver speed (bits-per-second)

SET /SPEED=TTnn:rcv:xmit

./-1'C.SCP

Terminal is a scope (CRT)

SET /CRT=TTnn:

TC.SLV

Terminal is a slave

SET /SLAVE=TTnn:

('rc.SMR

Upper-case conversion disabled

SET /LOWER=TTnn:

TC.TBF

Type-ahead buffer count (read),
or flush (write)

TC.TBS

100

Type-ahead buffer size (0-255=x)
(RSX-llMPLUS only)

TC.TBM

101

Type-ahead buffer mode
O=task typeahead
l=CLI typeahead
(RSX-llM-PLUS only)

' TC.TTP

Terminal type (=0-255.=x)

SET /X=TTnn:
SET /TERM=TTnn:x

J.'Tc. VFL

Send four fill characters after
line feed

SET /VFILL=TTnn:

Tc. wrn3

Page width (=l-255.=x)

SET /BUF=TTnn:x

Tc.xsp2

Transmitter speed (bits-per-second)

SET /SPEED=TTnn:rcv:xmit

" TC. 8BC

Pass eight bits on input, even
if not binary input mode
(TC .BIN)

SET /EBC=TTnn:

Terminal supports REGIS
instructions

2-15

SET /TYPEAHEAD=TTnn:x

April 1983

FULL-DUPLEX TERMINAL DRIVER

1. Effective for VT5x and VT61 only.

2. TC.RSP, TC.XSP, TC.ASP and corresponding MCR SET /SPEED and SET /REMOTE
command values for terminal receiver and transmitter speeds are listed below.
(The valid combinations for each interface are in the RSX-llM/M-PLUS MCR
Operations Manual.)
NOTE
The MCR SET /SPEED command requires parameters for
and transmitter (xmit) baud rates, as follows:

both

receiver

(rev)

SET /SPEED=TTnn:rcv:xmit
TC.ASP
TC.RSP or
TC.XSP
value

Actual baud rate (in bps)
and val id MCR SET /SPEED" or SET /REMOTE
values

s.o
S.50

(disabled)
50 (Baudot codes are not
supported)
S.75
75
S.110
110
S.134
134
S.150
150
S.200
200
S.300
300
S.600
600
S.1200
1200
S.1800
1800
s.2000
2000
S.2400
2400
S.3600
3600
S.4800
4800
s. 7200
7200
S.9600
9600
S.EXTA (DHll external speed A)
S.EXTB (DHll external speed B)
S.19.2
19200
NOTE
Speed can be set only on DHll and DZll controllers. DZll transmitter and
receiver speeds must be equal (no split baud rates permitted). Only one
value may be specified for the remote answer speed. This value applies
to both the transmitter and receiver.
3. Unsolicited input that fills the buffer before a terminator is received is
likely invalid. When this happens, the driver discards the input by simulating
a CTRL/O and echoing Au.

4. A program can enable the auto-call feature of the DF03 modem by setting
TC.DLU to a value of two.
(This is in addition to receiving incoming calls.)
While in this mode, read and write requests are serviced even when a line is not
in use.
Consequently, I/O requests will not fail when the line is hung-up,
which is the case for remote lines (TC.DLO=l).

2-16

April 1983

FULL-DUPLEX TERMINAL DRIVER
The TC.TTP characteristic, when read by the terminal driver,
sets
implicit values for terminal characteristics TC.LPP, TC.WID, TC.HFF,
TC.HHT, TC.VFL, and TC.SCP as shown in Table 2-6.
These values can be
changed
(overridden)
by subsequent Set Multiple Characteristics
requests.
In addition, TC.TTP is used by the terminal driver to
determine cursor positioning commands, as appropriate.
Table 2-6
Bit TC.TTP {Terminal Type) Values Set by SF.SMC
and Returned by SF.GMC

ITerminal
Ilvaluel
octal
Symbolic I
Type

0
1
2
3
4
5
6
7
10
11

12
13
14
15
16
20
21
22
23
24
25
26
27
30
31
32
33
34

T.UNKO
T.AS33
T.KS33
I T.AS35
T.L30S
T.L30P
T.LA36
T.VTOS
T.VTSO
T.VT52
T.VTSS
T.VT61
T.Ll80
T.VlOO
T.Ll20
T.LA12
T.LlOO
T.LA34
T.LA38
T.VlOl
T.Vl02
T.VlOS
T.Vl25
T.Vl31
T.Vl32
T.LASO
T.LQPl
T. LQP2

Unknown
ASR33
KSR33
ASR35
LA30S
LA30P
LA36
VTOS
VTSO
VT52
VTSS
VT61
LA180S
VTlOO
LA120
LA12
LAlOO
LA34
LA38
VTlOl
VT102
VT105
VT125
VT131
VT132
LASO
LQPOl
LQP02

Implicit Characteristics2

TC.LPP

66
66
66
66
66
66
20
12
24
24
24
66
24
66
66
66
66
66
24
24
24
24
24
24
60
66
66

TC.WID

TC.HFF I TC.HHT

TC.HFL

72
72

l.Octal values 0-177 are reserved by DIGITAL.
customer use to define non-DIGITAL terminals.

I
TC. SCPJ

1
l

1
7

80
80
132
72
80
80
80
80
132
80
132
132
132
132
132
80
80
80
80
80
80
80
132
132

TC.VFL

1
1
1
1
1

1
1
1

1
1
1
1
1
1
1
1
1
1
1
1
1

values

200-377

1
1
1
1
1
1

I
are

available

for

2.Implicit characteristics are shown as supported by the driver.
Values not shown
are not automatically set by the driver.
An "unknown" terminal type has no
implicit characteristics.

The TC.CTS characteristic returns the present suspend (CTRL/S), resume
(CTRL/Q), or suppress
(CTRL/O)
state set via the SF.SMC function.
Values returned are as follows:

Value
Returned

State

0
1
2
3

Resume (CTRL/Q)
Suspend (CTRL/S)
Suppress (CTRL/0)
Both suppress and suspend

2-17

April 1983

FULL-DUPLEX TERMINAL DRIVER
When a value of 0 is used with the SF.SMC function, the suspend
is cleared; a value of 1 selects the suspend state.

state

The TC.TBF characteristic returns the number of unprocessed characters
in the type-ahead buffer for the specified terminal. This allows
tasks to determine if any characters were typed that did not require
AST processing.
In addition, the value returned can be used to read
the exact number of characters typed, rather than a typical value of
80. or 132. characters for the terminal.
NOTES
1.

It is necessary that the task attach
the terminal to receive characters
from the type-ahead buffer.

The
maximum
capacity
of
the
type-ahead buffer is 36. characters
for
RSX-llM
systems
and
255.
characters for RSX-llM-PLUS systems.

Using TC.TBF in an SF.SMC function
will flush the type-ahead buffer.

2.3.2.5 IO.GTS - This function is a Get Terminal Support request that
returns information to a 4-word buffer specifying which SYSGEN-option
features are part of the terminal driver. Only two of these words are
currently defined.
Table 2-7 gives details for these words. The
IO.GTS function is a SYSGEN option.
If IO.GTS is issued on a system
without IO.GTS support, IE.IFC is returned in the I/O status block.
The various symbols used by the IO.GTS, SF.GMC, and SF.SMC functions
are defined in a system module, TTSYM. These symbols include: Fl.xxx
and F2.xxx (Table 2-7); T.xxxx (Table 2-6); TC.xxx (Table 2-5); and
the SE.xxx error returns described in Table 2-8, Section 2.4. These
symbols may be defined locally within a code module by using:
.MCALL

TTSYM$

TTSYM$
Symbols that are not defined locally are automatically defined by
Task Builder.
Octal values shown for the symbols are subject to change.
it is recommended that only the symbolic names be used.

2-18

the

Therefore,

FULL-DUPLEX TERMINAL DRIVER
Table 2-7
Information Returned by Get Terminal Support (IO.GTS) QIO

Bit

Octal
Value

Mnemonic

Meaning When Set to 1

Word 0 of Buffer:
Fl.ACR
Fl.BTWl
Fl. BUF
Fl.UIA 1

1
2
4

3
4
5

10
20
40

6
7
8

12
13
14

100
200
400
1000
2000
4000
10000
20000
40000

Fl. HLD
FLLwcl
Fl. RNE
Fl. RPRl
Fl.RST
Fl. RUBl
Fl. SYN
Fl.TRW
Fl.UTB

100000

Fl.VBF

10
11

Fl. CCO .

Fl.ESQl

Automatic CR/LF on long lines
Break-through write
Checkpointing during terminal input
Unsolicited-input-character AST
Cancel CTRL/O before writing
Recognize escape sequences in solicited
input
Hold-screen mode
Lower- to uppercase conversion
Read with no echo
Read after prompting
Read with special terminators
CRT rubout
CTRL/R terminal synchronization
Read all and write all
Input characters buffered in task's
address space
Variable-length terminal buffers

Word 1 of Buffer:
0

1
5
()

1
2

40
100
200

F2.SCH1
F2.GCH 1
F2.SFF
F2.CUP 1
F2.FDX

Set characteristics QIO (SF.SMC)
Get characteristics QIO (SF.GMC)
Formfeed can be simulated
Cursor positioning
Full Duplex Terminal Driver

1. SYSGEN options on RSX-llM systems.

2.3.2.6 IO.RAL - The Read All function causes the driver to pass all
bits to the requesting task.
The driver does not intercept control
characters or mask out the "parity" (high-order)
bit.
For example,
CTRL/C,
CTRL/Q, CTRL/S, CTRL/O, and CTRL/Z are passed to the program
and are not interpreted by the driver.
NOTE
IO.RAL echoes the characters that are
read.
The terminal driver in Version 2
of RSX-llM did not echo a Read All.
To
read
all bits without echoing,
use
IO.RAL!TF.RNE.
IO.RAL is equivalent to IO.RLB ORed with the subfunction bit TF.RAL.
The IO.RAL function can be terminated only by a full character count
(input buffer full).

2-19

FULL-DUPLEX TERMINAL DRIVER
2.3.2.7 IO.RNE - The IO.RNE function reads terminal input characters
without echoing the characters back to the terminal for immediate
display.
This feature can be used when typing sensitive information
(for example, a password or combination) or when reading a badge with
the RT02-C terminal.
(Note that the no-echo mode can also be
function;
see Table 2-5, bit TC.NEC.)

selected

with

the

SF.SMC

CTRL/R is ignored while an IO.RNE is in progress.
The IO.RNE function is equivalent to IO.RLB ORed with the
bit TF.RNE.

subfunction

2.3.2.8 IO.RPR - The IO.RPR Read After Prompt functions as an IO.WLB
(to write a prompt to the terminal) followed by IO.RLB.
However,
IO.RPR differs from this combination of functions as follows:
•

System overhead is lower with the IO.RPR because only one
is processed.

QIO

•

When using the IO.RPR function, there is no "window" during
which a response to the prompt may be ignored.
Such a window
occurs if IO.WAL/IO.RLB is used, because no read may be posted
at the time the response is received.

•

If the issuing task is checkpointable, it can be checkpointed
during both the prompt and the read requested by the IO.RPR.

•

A CTRL/O that may be in effect prior to issuing the IO.RPR
canceled before the prompt is written.

Subfunction bits may be ORed with IO.RPR to write the prompt as a
Write All
(TF.BIN)
and to send XOFF after the read (TF.XOF).
In
addition, read subfunction bits TF.RAL, TF.RNE, and TF.RST can be used
with IO.RPR.
NOTE
If an IO.RPR function
is in progress
when the driver receives a CTRL/R or
CTRL/U, the prompt is redisplayed.

2.3.2.9 IO.RPR!TE.BIN - This function results in a read after a
"binary" prompt;
that is, a prompt is written by the driver with no
character interpretation (as if it were issued as an IO.WAL).

2.3.2.10 IO.RPR!TE.XOF - This function causes the driver to send an
XOFF to the terminal after its prompt-and-read.
The XOFF or CTRL/S
may have the effect of inhibiting input from the terminal,
if the
terminal
recognizes XOFF for this purpose.
TF.XOF is ignored when
full-duplex I/O is in use.

2-20

FULL-DUPLEX TERMINAL DRIVER
2.3.2.11 IO.RST - This function
is similar to an IO.RLB, except
certain special characters terminate the read.
These characters are
in the ranges 0-037 and 175-177. The driver does not interpret the
terminating character, with certain exceptions.l For example, a
horizontal TAB (011) is not expanded, a RUBOUT (or DEL, 177) does not
erase, and a CTRL/C does not produce an MCR prompt.
Upon successful completion of an IO.RST request that was
terminated by filling
the input buffer, the first word of the
status block contains the terminating character in the high byte
the
rs.sue status code in the low byte. The second word contains
number of bytes contained in a buffer. The terminating character
not put in the buffer.

not
I/O
and
the
is

IO.RST is equivalent to IO.RLB!TF.RST.

2.3.2.12 SF.SMC - This function enables a task to set and reset the
characteristics of a terminal.
Set Multiple Characteristics is the
inverse function of SF.GMC.
Like SF.GMC,
it is called
in the
following way:
QIO$C SF.SMC, ••• ,<stadd,size>
stadd
The starting address of a buffer of length
word in the buffer has the form

"size"

bytes.

Each

.BYTE characteristic-name
.BYTE value
characteristic-name
One of the symbolic bit names given in Table 2-5.
value
Either 0 (to clear
characteristic).

given

characteristic)

(to

set

Table 2-5 notes the restrictions that apply to these characteristics.
If the characteristic-name is TC.TTP (terminal type), value
any of the values listed in Table 2-6.

can

have

A nonprivileged task can only issue an SF.SMC request for
its own
terminal (TI:).
A privileged task can issue SF.SMC to any terminal.
Terminal output can be suspended or resumed
(simulated CTRL/S and
CTRL/Q,
respectively)
by specifying an appropriate value for TC.CTS.
A value of 0 resumes output and a value of 1 suspends output.

1. If upper- to lowercase conversion is disabled, characters 175 and
176 do not act as terminators. CTRL/O, CTRL/Q, and CTRL/S (017, 021,
and 023,
respectively)
are not special terminators.
The driver
interprets them as output control characters in a normal manner.
2-21

FULL-DUPLEX TERMINAL DRIVER
Specifying any value for TC.TBF flushes (clears)
(forces the type-ahead buffer count to 0).

the type-ahead buffer

2.3.2.13 IO.RTT - This QIO function reads characters in a manner like
the
IO.RLB function, except a user-specified character terminates the
read operation.
The specified character's code can range from 0-377.
It
is user designated by setting the appropriate bit in a 16-word
table that corresponds to the desired character.
Multiple characters
can be specified by setting their corresponding bits.
The 16-word table starts at the address specified by the table
parameter.
The first word contains bits that represent the first 16
ASCII character codes (0-17);
similarly,
the second word contains
bits that represent the next ln character codes (20-37), and so forth,
through the sixteenth word, bit 15, which represents character code
377.
For example,
to specify the % symbol (code 045) as a read
terminator character, set bit 05 in the third word, since the third
word of the table contains bits representing character codes 40-57.
If the CTRL/S (023), CTRL/Q (021), and/or any characters whose codes
are greater than 177 is/are desired as the terminator character(s),
the terminal must be set to
read-pass-all operation
(TC.BIN=l), or
read-pass 8-bits (TC.SBC), as listed in Table 2-5.
The optional time-out count parameter can be included, as desired.

2.3.2.14 IO.WAL - The Write All function causes the driver to pass
all output from the buffer without interpretation.
It does not
intercept control characters.
Long lines are not wrapped around
if
input/output wrap-around has been selected.
IO.WAL is equivalent to the IO.WLB!TF.WAL function.

2.3.2.15 IO.WBT - The IO.WBT function instructs the driver to write
the buffer regardless of the I/O status of the receiving terminal.
If
an IO.WBT function is issued on a system that does not support IO.WBT,
it is treated as an IO.WLB function.
If another write function
is currently in progress,
it
• finishes
the current request and the IO.WBT is the next write
issued.
The effect of this is that a CTRL/S can stop IO.WBT
functions.
Therefore,
it may be desirable for tasks to time
out on IO.WBT operations.
and an
If a read is currently posted, the
IO.WBT proceeps,
• automatic
CTRL/R is performed to redisplay any input that was
received before the break-through write was effected
terminal is not in the full-duplex mode).
•

CTRL/O, if in effect, is canceled.

•

An escape sequence that was interrupted is rubbed out.

An IO.WBT function cannot break through
progress.

another

IO.WBT

Break-through write may only be issued by a
privileged
privileged MCR command BRO (broadcast) uses IO.WBT.

2-22

(if

the

that
task.

The

FULL-DUPLEX TERMINAL DRIVER
2.3.2.16 IO.HNG - The IO.HNG function disconnects a terminal that
on a remote line.
This function has no arguments.

A nonprivileged task can only issue an IO.HNG request for
its own
terminal (TI:). A privileged task can issue IO.HNG to any terminal.

2.4

STATUS RETURNS

Table 2-8 lists error and status conditions that are returned
terminal driver to the I/O status block.

the

Most RSX-llM error and status codes returned are byte values.
For
example,
the value for IS~SUC is 1.
However; IS:CC 1 IS=CR; IS.ESC;
and IS.ESQ are word values. When any of these codes are returned, the
low byte indicates successful completion, and the high byte shows what
type of completion occurred.
To test for one of these word-value return codes, first test the low
byte of the first word of the I/O status block for the value rs.sue.
Then, test the full word for rs.cc, IS.CR, IS.ESC, or IS.ESQ.
(If the
full word
tests equal to rs.sue, then its high byte is O, indicating
byte-count termination of the read.)
The "error" return IE.EOF may be considered a successful
read since
characters returned to the task's buffer can be terminated by a CTRL/Z
character.
The SE.xxx codes are returned by the SF.GMC and SF.SMC functions as
described
in Sections 2.3.2.4 and 2.3.2.12.
When any of these codes
are returned, the low byte in the first word in the I/O status block
will contain IE.ABO.
The second
IOSB word contains an offset
(starting from 0) to the byte in error in the QIO's stadd buffer.
Table 2-8
Terminal Status Returns
Code

Reason

IE.EOF

rs.sue

Successful completion

The operation specified
in the QIO directive was
completed successfully.
If the operation involved
reading or writing, you can examine the second word
of the
I/O status block to determine the number of
bytes processed.
The
input buffer contains those
bytes.
{continued on next page)

2-23

FULL-DUPLEX TERMINAL DRIVER
Table 2-8
(Cont.)
Terminal Status Returns
Code

Reason

IS.CC

Successful completion on a read
The line of input read
terminated by a CTRL/C.
the bytes read.

I IS.CR

from the terminal
was
The input buffer contains

Successful completion on a read
The line of input read from the terminal
was
terminated by a carriage return. The input buffer
contains the bytes read.

IS.ESC

Successful completion on a read
The line of input read from the terminal
was
terminated by an Altmode character. The input buffer
contains the bytes read.

IS.ESQ

Successful completion on a read
The line of input read from the terminal
was
terminated by an escape sequence. The input buffer
contains the bytes read and the escape sequence.

IS.PND

I/O request pending
The operation specified in the QIO directive has not
yet been executed.
The I/O status block is filled
with Os.

IS.TMO

Successful completion on a read
The line of input read from the terminal
was
terminated by a time-out (TF.TMO was set and the
specified time interval was exceeded).
The input
buffer contains the bytes read.

IE.ABO

Operation aborted
The specified I/O operation was cancelled by IO.KIL
while in progress or while in the I/O queue. The
second word of the I/O status block indicates the
number of bytes that were put in the buffer before
the kill was effected.

IE.BAD

Bad parameter
The size of the buffer exceeds 8128 bytes.

IE.BCC

Framing error
A framing error was hardware-detected and returned by
the controller.
All characters up to (but not
including) the erroneous character are in the buffer.
This condition can result by pressing the BREAK key
on some terminals, or by hardware problems.
(continued on next page)

2-24

FULL-DUPLEX TERMINAL DRIVER

Table 2-8
(Cont.)
Terminal Status Returns
Code
IE.DAA

Reason
Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code indicates that the issuing task has already
attached the desired physical device unit, not that
the unit was attached by another task.
If the attach
specified TF.AST or TF.ESQ, these subfunction bits
have no effect.

IE.DAO

Data overrun error
A data overrun error was hardware-detected
and
returned by the controller.
All characters up to
(but not including) the erroneous character are in
the buffer.
This error occurs when a hardware
failure or incompatibility causes characters to be
received by the controller faster than they can be
processed (that is, an incorrect serial I/O baud rate
or format exists).

IE.DNA

Device not attached
The physical device unit specified in an IO.DET
function was not attached by the issuing task. This
code has no bearing on the attachment status of other
tasks.

IE.DNR

Device not ready
The physical device unit specified in the
QIO
directive was not ready to perform the desired I/O
operation. This code is returned to indicate one of
the following conditions:

IE.IES

•

A time-out occurred on the physical
(that is, an interrupt was lost).

device

unit

•

An attempt was made to perform a function on a
remote DHll or DZll line without carrier present.

Invalid escape sequence
An escape sequence was started but escape-sequence
syntax
was
violated
before
the sequence was
completed.
(See Section 2.6.4.)
The
character
causing the violation is the last character in the
buffer.

IE.IFC

Illegal function
A function code specified in an I/O request was
or, the function code
illegal
for
terminals;
specified was a SYSGEN option not selected for this
system.
(continued on next page)

2-25

FULL-DUPLEX TERMINAL DRIVER
Table 2-8
(Cont.)
Terminal Status Returns
Code
IE.NOD

Reason
Buffer allocation failure
System dynamic storage has been depleted resulting in
insufficient
space
available
to
allocate
an
intermediate buffer for an input request or an AST
block for an attach request.

IE.OFL

Device off line
The physical device unit associated with the
LUN
specified in the QIO directive was not on line. When
the system was booted, a device check indicated
that
this
physical
device
unit
was
not
in the
configuration.
In RSX-llM-PLUS systems, the physical
device unit could have been configured off line.

IE.PES

Partial escape sequence
An escape sequence was started, but read-buffer space
was exhausted before the sequence was completed.
See
Section 2.6.4.3.

IE.PRI

Privilege violation
In a multiuser system, a nonprivileged task issued an
IO.WBT, directed an SF.SMC to a terminal other than
TI:, or it attempted to set its privilege bit.

IE.SPC

Illegal address space
The buffer specified
partially or totally
issuing task, a byte
odd or 0 AST address

IE.VER

for a read or write request was
outside the address space of the
count of 0 was specified, or an
was specified.

Character parity error
A parity error was hardware-detected and returned by
the controller.
All characters up to
(but not
including) the erroneous character are in the buffer.

SE.NIH

A terminal characteristic other than those

SE.FIX

An attempt was made to change a fixed characteristic
in a
SF.SMC subfunction request
(for example, an
attempt was made to change the unit number).

SE.VAL

The new value specified in an SF.SMC request for
the
TC.TTP terminal characteristic was not one of those
listed in Table 2-6.

in Table
2-5 was named
in an SF.GMC or SF.SMC request, or a
task attempted to assert TC.PRI.

(continued on next page)

2-26

FULL-DUPLEX TERMINAL DRIVER
Table 2-8
(Cont.)
Terminal Status Returns
Code

Reason

SE.NSC

change
An attempt was made to
a
nonsettable
characteristic. This error can occur when an attempt
is made to make a local-only line a remote line when
the controller does not support remote lines, or when
no remote line support was specified during SYSGEN.

SE.SPD

The new speed specified in an SF.SMC subfunction
request was not valid for the controller associated
with the specified terminal.

2.5

CONTROL CHARACTERS AND SPECIAL KEYS

This section describes the meanings of special terminal control
characters and keys for RSX-llM.
Note that the driver does not
recognize control characters and special keys during a Read All
request (IO.RAL), and recognizes only some of them during a Read with
Special Terminators (IO.RST).

2.5.1

Control Characters

A control character is input from a terminal by holding the control
key (CTRL) down while typing one other key. Three of the control
characters described in Table 2-9, CTRL/R, CTRL/U, and CTRL/Z, are
echoed on the terminal as AR, AU, and AZ, respectively.
Table 2-9
Terminal Control Characters
Character
CTRL/C

Meaning
Typing CTRL/C causes unsolicited input on
that
terminal to be directed to a control line interpreter
task, such as MCR.
(Command line interpreters are
invoked and display a prompt in a manner similar to
that of MCR; therefore, for the purposes of this
discussion, it is assumed that MCR is the command
line interpreter in use, although the terminal driver
will respond to other command line interpreters in a
similar manner.) The "MCR>" prompt is echoed when the
terminal driver is ready to accept an unsolicited MCR
command line for input. When the unsolicited input
is terminated, the command line is passed to MCR.
If the last character typed on the terminal was a
CTRL/S (suspend output) , CTRL/C restarts suspended
output and directs subsequent input to MCR.
,.. .c
.LL
the hold~screen mode SYSGEN option has been
selected and the terminal is a VT5x or VT61 in
hold-screen mode, typing a CTRL/C
removes
the
terminal from hold-screen mode.

(continued on next page)

2-27

FULL-DUPLEX TERMINAL DRIVER
Table 2-9 (Cont.)
Terminal Control Characters
Character

Meaning
CTRL/C characters can also be directed to a task if
the task has attached a terminal and has specified an
unsolicited-input-character
AST
(see
Section
2.3.2.1).
CTRL/C characters are also passed to a
task if an IO.RAL or IO.RST function is effected.
NOTE
If the terminal driver receives a CTRL/C
character during a read operation (except
during a Read-Pass-All operation or a Read
With Special Terminators operation), the read
operation is terminated,
the
type-ahead
buffer is cleared, and an IS.CC status code
is returned to the task.

CTRL/I

CTRL/I or TAB characters initiate a horizontal tab,
and the terminal spaces to the next tab stop. Tabs
at every eighth character position are simulated by
the terminal driver.

CTRL/J

CTRL/J is equivalent to a LINE FEED character.

CTRL/K

CTRL/K initiates a vertical tab, and the terminal
For a CRT
tabs to the next vertical tab stop.
terminal, four LINE FEEDs are output.

CTRL/L

CTRL/L initiates a formfeed.
If the terminal has
hardware formfeed support, the driver echos AL.
Otherwise, the driver simulates the formfeed by
outputting enough LINE FEED characters to advance the
next character position to the top of the next page.
If a CRT terminal is in use, four LINE FEEDs are
output.

CTRL/M

CTRL/M is equivalent to a carriage
(see Section 2. 5. 2).

CTRL/O

CTRL/O suppresses terminal output.
For attached
terminals,
CTRL/O remains in effect (output is
suppressed) until one of the following occurs:

RETURN

•

The terminal is detached.

•

Another CTRL/O character is typed.

An IO.CCO or IO.WBT function is issued.

•

Input is entered.

character

For unattached terminals, CTRL/O suppresses output
for only the current output buffer (typically one
line) •
CTRL/Q

CTRL/Q resumes terminal output
by means of CTRL/S.

previously

suspended

(continued on next page)
2-28

FULL-DUPLEX TERMINAL DRIVER

Table 2-9
(Cont.)
Terminal Control Characters
Character

Meaning

CTRL/S

CTRL/S suspends terminal output.
resumed by typing CTRL/Q or CTRL/C.)

CTRL/R

CTRL/R response is a terminal driver feature that can
be selected during RSX-llM V3.2 SYSGEN.
Typing
CTRL/R results in a carriage return and line feed
being
echoed,
followed
by
the
incomplete
(unprocessed) input line. Any tabs that were input
are expanded and the effect of any rubouts is shown.
On hardcopy terminals, CTRL/R allows verifying the
effect of tabs and/or rubouts in an input line*
CTRL/R is also useful for CRT terminals when the CRT
rubout SYSGEN option has been selected (see Section
2.8). For example, after rubbing out the left-most
character on the second displayed line of a wrapped
input line, the cursor does not move to the right of
the first displayed line.
In this case, CTRL/R
brings the input line and the cursor back together
again.

CTRL/U

Typing CTRL/U before typing a line terminator deletes
previously typed characters back to the beginning of
the line. The system echoes this character as AU
followed by a carriage return and a line feed.

CTRL/X

This character clears the type-ahead buffer.

CTRL/Z

CTRL/Z indicates an end-of-file for the current
terminal input. It signals MAC, PIP, TKB, and other
system tasks that terminal input
is
complete,
allowing the task to exit. The system echoes this
character as AZ, followed by a carriage return and a
line feed.

2.5.2

(Output

can

Special Keys

The ESCape, carriage RETURN, and RUBOUT keys have special significance
for terminal input, as described in Table 2-10.
A line can be
terminated by an ESCape (or Altmode), carriage RETURN, or CTRL/Z
characters, or by completely filling the input buffer (that is, by
exhausting the byte count before a line terminator is typed).
The
standard buffer size for a terminal can be determined for a task by
issuing a Get LUN Information system directive and examining Word 5 of
the buffer. An operator can obtain the same information with the MCR
SET /BUF=TI: command.

2.n

ESCAPE SEQUENCES

Escape sequences are strings of two or more characters beginning with
an ESC (033) character. In RSX-llM systems, escape sequence support
described in this section is' a SYSGEN option. Some terminals generate
an escape sequence when a special key is pressed (for example, the FCN
key on the VTnl).
On any terminal, an escape sequence may be
generated manually by typing ESCape followed by the appropriate
characters.
2-29

FULL-DUPLEX TERMINAL DRIVER
Escape sequences provide a way to pass
input to a
task without
interpretation by the operating system.
This could be done with a
number 1-character Read All functions, but escape sequences allow them
to be read with IO.RLB requests.

Table 2-10
Special Terminal Keys
Meaning

Key
ESCape

If escape sequences are not recognized, typing ESCape
or Altmode signals the terminal driver that there is
no rurther input on the current line.
This line
terminator allows further
input on the same line,
because the carriage or cursor is not returned to the
first column position.
If escape sequences are
recognized,
ESCape signals
the beginning of an escape sequence.
(See Section
2.6.)

RETURN

Typing RETURN terminates the current line and causes
the carriage or cursor to return to the first column
on the line.

RUBOUT

Typing RUBOUT deletes the last character typed on an
input line.
Only characters typed since the last
line terminator may be deleted.
Several characters
can be deleted
in sequence by typing successive
RUBOUTs.
For example, on a printing terminal, the first RUBOUT
echoes a backslash (\) followed by the character that
has been deleted, even if the terminal
is in the
no-echo mode.
Subsequent RUBOUTs cause only the
deleted character to be echoed.
The next character
typed
that is not a RUBOUT causes another backslash
to be printed, followed by the new character.
The
non-RUBOUT character will not be echoed
if the
terminal
is
in the no-echo mode;
however,
a
backslash
is
echoed
in response to
the
first
non-RUBOUT
character.
The
following
example
illustrates rubbing out ABC and then typing CBA:
ABC\CBA\CBA
The second backslash
is not displayed
if a
line
terminator
is typed after rubbing out the characters
on a line, as in the following example:
ABC\CBA
At SYSGEN time,
the
"CRT rubout"
feature can be
selected.
This feature applies to a terminal only
after a SET MCR directive has been issued:
SET /CRT=TI:
(continued on next page)

2-30

FULL-DUPLEX TERMINAL DRIVER
Table 2-10 (Cont.)
Special Terminal Keys
Key

Meaning

2.6.1

If the CRT rubout feature was selected, RUBOUT causes
the last typed character (if any) to be removed from
the
incomplete
input
line
and
a
backspace-space-backspace sequence of characters for
that terminal are echoed.
If the
last
typed
character was a tab, enough backspaces are issued to
move the cursor to the character position before the
tab was typed.
If a long input line was split, or
"wrapped," by the automatic-carriage-return option,
and a RUBOUT erases the last character of a previous
line, the cursor is not moved to the previous line.
CTRL/R must be used to resynchronize the current.
display with the contents of the incomplete input
line.

Definition

The format of an escape sequence as defined in
Standard X 3.41-- 1974 and used in the VTlOO is:
ESC

American

National

ESC
The introducer control character_ (33(8)) that is named escape.

The intermediate bit combinations that may or may not be
present.
I
characters are bit combination 40(8) to 57(8)
inclusive in both 7- and 8-bit environments.
F

The final character. F characters are bit combinations 60(8)
to 176(8) inclusive in escape sequences in both 7- and 8-bit
environments.
The occurrence of characters in the inclusive ranges 0(8) to 37(8)
is technically an error condition whose recovery is to execute
immediately the function specified by the character and then
continue with the escape sequence execution. The exceptions are:
if the character ESC occurs, the current escape sequence is aborted,
and a new one commences, beginning with the ESC just received; if
the character CAN (30(8)) or the character SUB (32(8)) occurs, the
current escape sequence is aborted, as is the case with any control
character.
There are five exceptions to this general
exceptions are discussed in Section 2.6.5.

2-31

definition;

these

FULL-DUPLEX TERMINAL DRIVER
2.6.2

Prerequisites

Two prerequisites must be satisfied before escape sequences
received by a task.

can

First, the task must "ask" for them by issuing
and invoking the subfunction bit TF.ESQ.

function

IO.ATT

Second, the terminal must be declared capable of generating
sequences.
This may be done with an MCR SET command:

escape

SET /ESCSEQ=TI:
An alternative way to tell the driver that the terminal can generate
escape sequences is by issuing the Set Multiple Characteristics
request.
(See Section 2.3.2.12).
If either of these prerequisites is not satisfied, the
is treated as a line terminator.

ESC

character

If both prerequisites are satisfied, CTRL/SHIFT/O (037) may be used as
an Altmode character.l This character does not act as an Altmode from
a terminal that cannot generate escape sequences.

2.6.3

Characteristics

Escape sequences always act as line terminators.
That is, an input
buffer may contain other characters that are not part of an escape
sequence, but an escape sequence always comprises the last characters
in the buffer.
Escape sequences are not echoed.
However,
if a non-CRT rubout
sequence is in progress, it is closed with a backslash when an escape
sequence is begun.
Escape sequences are not recognized
in unsolicited input streams.
Neither are they recognized
in a Read with Special Terminators
(subfunction bit TF.RST) nor in a Read All (subfunction bit TF.RAL).

2.6.4

Escape Sequence Syntax Violations

A violation of the syntax defined in Section 2.6.1 causes the driver
to abandon the escape sequence and to return an error (IE.IES).

2.6.4.1 DEL or RUBOUT (177) - The character DEL or RUBOUT is not
legal within an escape sequence.
Typing it at any point within an
escape sequence causes the entire sequence to be abandoned and deleted
from the
input buffer.
Thus, use DEL or RUBOUT to abandon an escape
sequence, if desired, once you have begun it.

1. An Altmode is a line terminator that does not cause the cursor to
advance to a new line.
On terminals that cannot generate escape
sequences, the ESCape key acts as an Altmode.
Characters 175 and 176
also function as Altmodes if the terminal has not been declared
lowercase (MCR command SET /LOWER).
2-32

FULL-DUPLEX TERMINAL DRIVER
2.6.4.2 Control Characters (0-037} - The reception of any character
in the range O to 037 (with four exceptions -- see footnotel) is a
syntax violation that terminates the read with an error (IE.IES).

2.6.4.3 Full Buffer - A syntax error results when an escape sequence
is terminated by running out of read-buffer space, rather than by
receipt of a final character.
The error IE.PES is returned.
For
example,
after a task issues an IO.RLB with a buffer length of 2, and
you type:
ESC !

the buffer contains "ESC ! ", and the I/O status block contains:
IOSB

The "A" is treated as unsolicited input.

2.6.5

Exceptions to Escape-Sequence Syntax

Five "final characters" that normally terminate an escape sequence are
treated as special cases by the terminal driver for use with certain
terminals:
ESC
ESC
ESC
ESC
ESC

? •••
0 •••
p •••
y •••
[

...

Refer to documentation supplied with the specific terminal(s)
for correct use of escape sequences.

2.7

use

VERTICAL FORMAT CONTROL

Table 2-11 is a summary of all characters used for vertical format
control on the terminal. Any one of these characters can be specified
as the value of the vfc parameter in IO.WLB, IO.WVB,
IO.WBT,
IO.CCO,
or IO.RPR functions.

1. Four control characters are allowed:
CTRL/Q, CTRL/S, CTRL/X, and
CTRL/O.
These characters are handled normally by the operating system
even when an escape sequence is in progress.
For example, entering:
ESC CTRL/S A
gives:
IOSB

IS.ESQ
2

with the additional effect of turning off the output stream.
2-33

FULL-DUPLEX TERMINAL DRIVER
2.8

AUTOMATIC CARRIAGE RETURN

Individual terminals can be set for wrap-around, as desired, using the
MCR SET command
>SET /WRAP=TTxx:
Once wrap-around has been selected, the column at
occurs can be selected using the MCR SET command

which

wrap-around

>SET /BUF=TI:n

>
The SET /BUF command can also be used without an argument
the current buffer width for a terminal:

display

>SET /BUF=TI:
BUF=TI:00072.

>
Table 2-11
Vertical Format Control Characters
Octal
Value

Character

040

blank

SINGLE SPACE - Output one line feed,
print the
contents of the buffer, and output a carriage
return.
Normally, printing immediately follows
the previously printed line.

060

DOUBLE SPACE - Output two line feeds, print the
contents of the buffer, and output a carriage
return.
Normally,
the buffer contents
are
printed
two
lines below the previously printed
line.

061

PAGE EJECT - If the terminal
supports
FORM
FEEDs, output a form feed, print the contents of
the buffer, and output a carriage return.
If
the terminal does not support FORM FEEDs, the
driver simulates the FORM FEED character by
either outputting four
line feeds
to a crt
terminal, or by outputting enough line feeds
to
advance the paper to the top of the next page on
a printing terminal.

053

OVERPRINT - Print the contents of the buffer and
output a carriage return, normaLly overprinting
the previous line.

044

000

null

Meaning

I PROMPTING

OUTPUT
Output one line feed
and
print the contents of the buffer.
This mode of
output is intended for use with a
terminal on
which a
prompting message is output, and input
I is then read on the same line.

INTERNAL VERTICAL FORMAT - Print
the
buffer
contents without addition of vertical format
control characters.
In this mode, more than one
line of guaranteed contiguous output can be
printed for each I/O request.

2-34

FULL-DUPLEX TERMINAL DRIVER
All other vertical format control characters are interpreted as blanks
(040).
A task can determine the buffer width by issuing a Get LUN Information
directive and examining word 5 returned in the buffer.
After the SET has been done, typing beyond the buffer width results in
a carriage return and line feed being output before the next character
is echoed. Although only one line only was input, it is displayed on
two terminal lines.
It is possible to lose track of where you are in the input buffer if
wrap-around is enabled for your terminal.
For example, while deleting
text on a wrapped line, the cursor will not back up to the previous
line.
In order to resynchronize the cursor with the contents of the
incomplete input buffer, type CTRL/R (if this SYSGEN option has been
selected).

2.9

FEATURES AVAILABLE BY RSX-llM SYSGEN OPTION

A number of terminal-driver features are available as RSX-llM SYSGEN
options.
(See the RSX-llM System Generation and Installation Guide).
Features previously discussed that are not repeated
in this section
include:
•

Some device-specific QIO functions

•

Special keys:

(see Section 2.3.2)

CTRL/R -- Write incomplete input buffer
Section 2.5.1)

(see

CRT rubout (see Section 2.5.2)
•

Escape sequences (see Section 2.6)

The only
remaining
features
selected
at
SYSGEN
time
are
terminal-independent cursor control
(described in Section 2.15),
private buffer pool size, and hard receive error detection, described
in the following sections.

2.9.1

Private Buffer Pool Size

The private buffer pool is contained within the full-duplex terminal
driver.
The size of the whole driver is established during SYSGEN by
the VMR command to load the driver as follows:
LOA TT:/SIZE=nnn
The private buffer pool occupies all of the space from the top of the
actual driver code up to nnn.
The argument nnn is expressed in octal
words, and the maximum value is 20000,
corresponding to 8K words.
Depending on driver options selected, the code requires from 2.5 to
4.5k words.
Thus, the maximum buffer pool size is from 3.5k to 5.5k
words.
Alternatively, on an RSX-llM-PLUS system, it is possible to allocate
the private pool in a separate common block called TTCOM.
This block
can range in size up to 4k words.
The default size is 4k words, but
it is modifiable, using the SIZE keyword with the VMR LOA command.
In
this case, the private pool
is used almost exclusively for data
buffers.
Other driver-specifc data is allocated from secondary pool.

2-35

FULL-DUPLEX TERMINAL DRIVER
2.9.2

Hard Receive Error Detection

All terminal interfaces supported by the full-duplex terminal driver
are capable of detecting and flagging hard receive errors. Hard
receive errors include framing errors, enable character parity error,
and data overrun error.
NOTE
The driver does not
enable
parity
generation and checking on DHli and DZll
interfaces.
If the hard receive error detection SYSGEN option (T$$RED)
selected, the driver handles hard receive errors as follows:
1.

If a read request is being processed and the character can be
processed immediately, the read request is terminated with
one of the following error codes returned in the status
block:
Error
Code

Hard Receive Error

IE.BCC
IE.DAO
IE.VER

Framing error
Data overrun
Character parity error

If a command line is being input for a command line
interpreter
task
and
the character can be processed
immediately, a CTRL/U is simulated, AU is echoed, and the
input is terminated. No command line is sent to the task.

If the character would normally cause an AST if no error
detected, the character is ignored and no AST occurs.

If the character cannot be processed immediately, it is
stored in the type-ahead buffer. A flag is set for the line,
indicating that the last character in the type-ahead buffer
has an error, disabling further storage in the type-ahead
buffer. When the character is retrieved from the buffer, the
appropriate action previously described is taken and the flag
is cleared. Any characters received in the meantime are
discarded, with a bell echoed for each character.

was

If the T$$RED option is not selected, hard receive errors are ignored.

2.10

TASK BUFFERING OF RECEIVED CHARACTERS

When task-buffering received characters, characters read from the
terminal are sent directly to the task's buffer. Thus, there is no
need to allocate a terminal driver buffer.
Task buffering of received characters does not necessarily reduce
system overhead. For example, in a mapped system each character must
be mapped to the task's buffer. However, if terminal driver buffering
was used, the mapping is only done once for all characters to be
transferred.

2-36

FULL-DUPLEX TERMINAL DRIVER
With the full duplex
performed.

terminal

driver,

output

buffering

always

Task buffering is overridden during checkpointing.
If a task js
checkpointable, a driver buffer is allocated and the task is made
eligible for checkpointing by any task, regardless of priority, while
the read operation is in progress.
(Checkpointing only occurs in this
situation when there is another task that can be made active.)
Since
checkpointability is controlled by the task, the user retains control
over this operation.

2.11

TYPE-AHEAD BUFFERING

Characters received by the terminal driver are either processed
immediately or stored in the type-ahead buffer.
The type-ahead buffer
allows characters to be temporarily stored and retrieved FIFO.
The
type-ahead buffer is used as follows:
1.

Store in buffer:
An input character is stored in the type-ahead buffer if
or more of the following conditions are true:
•

The driver is not ready to accept
process pending or in progress).

the

•

There is at least
type-ahead buffer.

presently

one

character

one

character

(fork

the

character input requires echo and the output line
• The
the terminal is presently busy outputting a character.

read request is in progress, no unsolicited
• No
is specified, and the terminal is attached.

AST

input

NOTE
Depending on the terminal mode and the presence of a
read function,
read subfunctions and an unsolicited
input AST, the CTRL/C, CTRL/O, CTRL/Q, CTRL/S, and
CTRL/X characters may be processed immediately and
not stored in the type-ahead buffer.
A character is not echoed when it is stored in the buffer.
Echoing a character is deferred until it is retrieved from
the
buffer,
since
the
read
mode
(for
example,
read-without-echo) is not known by the driver until then.
2.

Retrieve from buffer:

When the driver becomes ready to process input, or when a task issues
a read request, an attempt is made to retrieve a character from the
buffer. If this attempt is successful, the character is processed and
echoed, if required.
The driver then loops, retrieving and processing
characters until either the buffer is empty, the driver becomes unable
to process another character, or a read request is finished with the
terminal attached.

2-37

April 1983

•

FULL-DUPLEX TERMINAL DRIVER
3.

Flush the buffer:

The buffer is flushed (cleared) when:
1.

CTRL/C is received.

CTRL/X is received.

The terminal becomes detached.

Exceptions:
CTRL/C and CTRL/X do not
flush
the
buffer
read-pass-all or read-with-special-terminators is in effect.
If the buffer becomes full, each character that cannot
causes a BELL character to be echoed to the terminal.

entered

If a character is input and echo is required, but the transmitter
section is busy with an output request, the input character is held in
the type-ahead buffer until output (transmitter) completion occurs.

2.12

FULL-DUPLEX OPERATION

When a terminal line is in the full-duplex mode, the full-duplex
driver attempts to simultaneously service one read request and one
write request. The Attach, Detach and Set Multiple Characteristics
functions are only performed with the line in an idle state (not
executing a read or a write request).

2.13

PRIVATE BUFFER POOL

The driver has a private buffer pool for intermediate input and output
buffers on both RSX-llM and RSX-llM-PLUS systems, and type-ahead
buffers and UCB extensions on RSX-llM systems only.
Whenever the
driver needs dynamic memory, it first attempts to allocate a buffer in
the private pool.
If this fails, a second attempt is made in the
system pool.
If the allocation in the system pool fails during
command line input, a CTRL/U is simulated and echoed.
Command line interpreter task buffers are handled in a special way.
When unsolicited input begins, a buffer is allocated, as previously
described, for the command line (a string of characters, followed by
an appropriate terminator character). When the input is completed,
the contents of the buffer is sent directly to the command line
interpreter task if the buffer was allocated in the system pool.
However, if the buffer was allocated in the driver's private pool,
it
must first be moved into a buffer in the system pool to provide access
for the task.

2.14

INTERMEDIATE INPUT AND OUTPUT BUFFERING

Input buffering for checkpointable tasks with checkpointing enabled is
provided in the private pool.
As each buffer becomes full, a new
buffer is automatically allocated and linked to the previous buffer.
The Executive then transfers characters from these buffers to the task
buffer and the terminal driver deallocates the buffers once the
transfer has been completed.

2-38

FULL-DUPLEX TERMINAL DRIVER
If the driver fails to allocate the first input buffer, the characters
are transferred directly into the task buffer.
If the first buffer is
successfully allocated, but a subsequent buffer allocation fails,
the
input request terminates with the error code IE.NOD.
In this case,
the I/O status block contains the number of characters actually
transferred to the task buffer.
The task may then update the buffer
pointer and byte count and reissue a read request to receive the rest
of the data.
The type-ahead buffer ensures that no input data is
lost.
All terminal output is buffered. As many buffers as required are
allocated by the terminal driver and linked to a list.
If not enough
buffers can be obtained for all output data, the transfer is done as a
number of partial transfers, using available buffers for each partial
transfer. This is transparent to the requesting task.
If no buffers
can be allocated, the request terminates with the error code IE.NOD.
The unconditional output buffering serves three purposes:

2.15

It reduces time spent at system state.

It enables long DMA transfers for DHll controllers.

It enables task checkpointing during the transfer
terminal (if all output fits in one buffer list).

the

TERMINAL-INDEPENDENT CURSOR CONTROL

Terminal-independent cursor control capability is provided at SYSGEN
time.
The terminal driver responds to task I/O requests for cursor
positioning without the task requiring information about the type of
terminal in use.
I/O functions associated with cursor positioning are
described as follows.
Cursor position is specified in the vfc parameter of the IO.WLB or
IO.RPR function.
The parameter is interpreted simply as a vfc
parameter if the high byte of the parameter is O.
However, if the
parameter is used to define cursor position, the high byte must be
nonzero, the low byte is interpreted as column number
(x-coordinate),
and the high byte is interpreted as line number (y-coordinate) • Horne
position, the upper left corner of the display,
is defined as 1,1.
Depending
upon
terminal
type,
the driver outputs appropriate
cursor-positioning commands appropriate for the terminal in use that
will move the cursor to the specified position.
If the most
significant bit of the line number is set, the driver clears the
display before positioning the cursor.
When defining cursor position in an IO.WLB function,
the TF.RCU
subfunction can be used to save the current cursor position. When
included in this manner, TF.RCU causes the driver to first save the
current cursor position,
then position the cursor and output the
specified buffer, and, finally, restore the cursor to the original
(saved) position once the output transfer has been completed.

2.16

TERMINAL INTERFACES

This section summarizes the
characteristics
of
the
standard
communication-line interfaces supported by RSX-llM.
Refer to the
Terminals and Communications Handbook for additional details.

2-39

April 1983

•

FULL-DUPLEX TERMINAL DRIVER
2.16.1

DHll Asynchronous Serial Line Multiplexer

The DHll multiplexer interfaces up to 16
asynchronous
serial
communications lines for terminal use.
The DHll supports programmable
baud rates.
Input and output baud rates may differ;
the input rate
may be set to 0 baud, thus effectively turning off the terminal.
The
DMll-BB option may be included to provide modem control for dial-in
iines. These lines must be interfaced by means of a full duplex modem
(for example, in the United States, a Bell 103A or equivalent modem).

2.16.2

DHVll Asynchronous Serial Line Multiplexer

The DHVll multiplexer interfaces up to eight asynchronous serial
communications lines for terminal use. This multiplexer is the Q BUS
version of the DHll UNIBUS multiplexer.
The
DHVll
supports
programmable baud rates with the option of selecting split speed
operation.
(Split speed operation allows different transmit and
receive speeds.)
Also provided is modem control for full-duplex
point-to-point operation.

2.16.3

DJll Asynchronous Serial Line Multiplexer

The DJll multiplexer interfaces as many as 16 asynchronous serial
lines to the PDP-11 for local terminal communications. The DJll does
not provide a dial-in capability. Baud rates are jumper selectable.

2.16.4

DLll Asynchronous Serial Line Interface

The DLll supports a single asynchronous serial line and handles
communication between the PDP-11 and a terminal. A number of standard
baud rates are available to DLll users.
However, since the DLll does
not have an input silo, baud rates greater than 1200 baud are not
recommended.
Higher baud rates may cause input characters to be lost.
For hardware reasons, a DLll is susceptible to
interrupt enable in its Receiver Status Register.
the receiver interrupt bit causes the terminal
requests but not to respond to input (for example,
not echo input characters). The terminal driver has
recognizing the disabling.
Therefore,
it cannot
must be reset with an MCR OPEN command, the console
or a periodically rescheduled task.

2.16~5

losing receiver
The disabling of
to print output
the terminal does
no mechanism for
recover.
The bit
switch register,

DZll Asynchronous Serial Line Multiplexer

The DZll multiplexer interfaces up to eight asynchronous serial
communication lines for use with terminals.
It supports programmable
baud rates; however, transmit and receive baud rates must be the
same. The DZll can control a full duolex modern in auto-answer mode.

2-40

April 1983

FULL-DUPLEX TERMINAL DRIVER
2.17
2.17.1

PROGRAMMING HINTS
ESCape Code Conversion

If escape sequences are recognized, the character code 037 will
terminate input and a status code IS.ESC is returned.
In addition,
character codes will terminate input and return the IS.ESC status if
upper- to lowercase conversion is not enabled.

2.17.2

RT02-C Control Function

Because the screen of an RT02C Badge Reader and Data Entry Terminal
holds only one line of information, special care must be taken when
sending a control character {for example, vertical tab) to the RT02-C.
Use the IO.WAL {Write All) function for this purpose.
It is recommended that read without echoing be used when reading a
badge with the RT02-C.
Use IO.RAL or IO.RNE functions, followed by
the IO.WAL function, to echo the information for display.

2-40.l

FULL-DUPLEX TERMINAL DRIVER
2.17.3

Using IO.WVB Instead of IO.WLB

Using IO.WVB instead of IO.WLB is recommended when writing to a
terminal.
If the write actually goes to a terminal, the Executive
converts the IO.WVB to an IO.WLB request. However, if the LUN has
been redirected to an inappropriate device (for example, a disk), the
use of an IO.WVB function will be rejected because a file is not open
on the LUN.
This prevents privileged tasks from overwriting block
zero of the disk.
Note that any subfunction bits specified in the IO.WVB request (for
example, TF.CCO, TF.WAL, or TF.WBT) are stripped when the IO.WVB is
converted to an IO.WLB.

2.17.4

Remote DLll-E, DHll, and DZll Lines

Bef0re a remote line is answered, the driver clears certain terminal
characteristics (see Table 2-5) that may have been set by an MCR SET
command, or by an SF.SMC function. The characteristics cleared are:
TC.SCP, TC.ESQ, TC....R'LD, TC.SMR, TC.)1-E'C, TC.~X, TC.JI.Pf', TC.Hfi'T,
TC.)iF"L, TC.,aFL, TC,.;M'P, TC'61fc, and TC_.a..t'N.
(Clearing TC.TTP means
that a terminal type of "unknown" will be returned in an SF.GMC
request.) The TC~ACR characteristic (automatic wrap around)
is set.
Buffer size is set to 72.
A DZll remote line must be declared to be remote before
driver will handle the modern.

2.17.5

the

J
/

term1:J

Side Effects of Setting Characteristics

Certain terminal characteristics that a task may set or that an
operator may set using MCR commands may have undesirable side effects.
In particular, these characteristics include the hold-screen mode and
the lower- to uppercase conversion disable mode. Their effects are
described as follows.
TC.HLD -- Unexpected behavior can result from a terminal in the
hold-screen mode if its reception rate is much greater than its
transmission rate.
(The DHll supports split baud rates.) When in the
hold-screen mode, the terminal automatically sends a CTRL/S during
reception of an output stream when the screen is nearly full.
Output
is resumed -- another screen-full -- when you type SHIFT/SCROLL (the
terminal generates CTRL/Q). Thus, no output is lost as a result of
scrolling off the screen before you can read it. However, if the
terminal's transmission rate is far below its reception rate, some
unread output may scroll out of sight before the CTRL/S can be
transmitted.
Note that some terminals and interfaces are hardware buffered.
This
can cause obscure timing problems for tasks that attempt to invoke the
hold-screen mode.
TC.SMR -- If this characteristic is asserted
(lower- to uppercase
conversion is disabled), octal characters 175 and 176 are interpreted
as "right brace (})" and "tilde (rv) ," respectively.
If TC.SMR is
not asserted, these characters are interpreted as an Altrnode (that is,
they function as line terminators that do not advance the cursor to a
new line).

2-41

FULL-DUPLEX TERMINAL DRIVER
2.17.6

Modem Support

The terminal driver supports the following modem control operations:
•

Local or remote operation

•

Answer speed

•

Auto-baud speed detection

The characteristics bit that controls local or remote operation
is
TC.DLU.
This bit can be set with the MCR command SET /REMOTE (or SET
/NOREMOTE for local operation) • The DCL command SET TERMINAL REMOTE
(or SET TERMINAL LOCAL) can also be used.
When there
is an
incoming call on a
remote line,
the TC.ASP
characteristic determines the baud rate for the answering modem.
Split baud rates (different
supported for answer speed.

transmit

and

receive

speeds)

are

not

The default answer speed is set at SYSGEN time.
However, _the answer
speed can be set on line using the MCR command SET /REMOTE=TTnn:speed.
VMR can also be used to set the answer speed.
The terminal driver can determine the speed of the
incoming call by
sampling
the first
input character after dial-up for the following
speeds:
110
150
300
1200
This is called auto-baud speed detection.
This option can be selected
for
each line using
the SET /ABAUD command.
This command sets the
TC.ABD terminal characteristic. When TC.ABD is set for a given line,
the
terminal driver makes three attempts to determine the incoming
speed.
If the auto-baud speed detection fails,
the terminal driver
will use the default answer speed discussed above.
For auto-baud speed detection to work correctly,
the first
input
character after dial-up must be either carriage return or CTRL/C.

2-42

CHAPTER 3
HALF-DUPLEX TERMINAL DRIVER

3.1

INTRODUCTION

The half-duplex terminal driver provides support for a variety of
terminal
devices under RSX-llM.
(This terminal driver is not
supported on RSX-llM-PLUS systems.) The half-duplex terminal driver is
generally
used in RSX-llM systems where small driver size is
essential, and the additional functional capability provided by the
larger full-duplex terminal driver
(described in Chapter 2) is not
required.
Table 3-1 summarizes the
terminals
supported,
and
subsequent sections describe these devices in greater detail.
Table 3-1
Supported Terminal Devices
Model

Columns

ASR-33/35
KSR-33/35
LA12
LAlOO
LA30-P
LA30-S
LA34
LA36
LA38
LA120
LA180S
RT02
RT02-C
VT05B
VT50
VT50H
VT52
VT55
VT61
VTlOO
VTlOl
VT102
VT105
VT125
VT131
VT132

72
72
132
132
80
80
132
80-132
132
132
132
64
64
72

80
80
80
80
80
80-132
80-132
80-132
80-132
80-132
80-132
80-132

Lines/
Screenl

Character
Set

Baud
Range

1
1
20
12
12
24
24
24
24
24
24
24
24
24
24

64
64
96
96
64
64
96
64-96
96
96
96
64
64
64
64
64
96
96
96
96
96
96
96
96
96
96

110
110
50-9600
110-9600
300
110-300
110-300
110-300
110-300
50-9600
300-9600
110-1200
110-1200
110-2400
110-9600
110-9600
110-9600
110-9600
110-9600
50-9600
50-19200
50-9600
50-9200
50-9600
50-19200
50-19200

UpperSend

Lowercase?
Receive

yes
yes

yes
yes
yes
yes

yes
yes2
yes
yes
yes

yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes

yes
yes
yes
yes
yes
yes
yes
yes
yes
yes

1. Applies only to video terminals.
2. Only for 96-character terminal.
The terminal
the terminal interfaces summarized in Table 3-2.
are described in greater detail in Section 3.9.
identical for all.
3-1

driver supports
These interfaces
Programming is

HALF-DUPLEX TERMINAL DRIVER
Table 3-2
Standard Terminal Interfaces
Model
DHll
DHll-DMll-BB
DJll
DLll-A/B/C/D/W
DLVll-F
DZll

Type
16-line multiplexerl
16-line multiplexer with modem control2
16-line multiplexer
Single-line interfaces
Single-line interface
8-line multiplexer with modem control2

1. Direct memory access (DMA) not supported.
2. Full-duplex control only.
Bell 103A-type modem.

For example,

the

USA,

Terminal input lines can have a maximum length of 255 bytes
(the
maximum is set in the system generation, or SYSGEN, dialog). The
extra characters of an input line that exceeds the maximum length
generally become an unsolicited input line.

3.1.1

ASR-33/35 Teletypesl

The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals.
No paper tape reader or punch capability is supported.

3.1.2

KSR-33/35 Teletypesl

The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals.

3.1.3

LA30 DECwriters

The LA30 DECwriter is an asynchronous, hard-copy terminal that is
capable of producing an original and one copy. The LA30-P is a
parallel model and the LA30-S is a serial model.

3.1.4

LA36 DECwriter

The LA36 DECwriter is an asynchronous terminal that produces hard copy
and operates in serial mode.
It has an impact printer capable of
generating multipart and special preprinted forms.
The LA36 can
receive and transmit both uppercase and lowercase characters.

1. Teletype is a registered trademark of the Teletype Corporation.
3-2

HALF-DUPLEX TERMINAL DRIVER
3.1.5

LA120 DECwriter

The LA120 DECwriter is a hard-copy, upper- and lowercase terminal
capable
of
printing
multipart
forms
at
speeds up to 180
characters-per-second. Serial communications speed is selected from
14 baud rates ranging from 50 to 9600 bps. Hardware features allow
bidirectional printing for maximum printing speed, and also allow
user-selected features, including font size, line spacing, tabs,
margins, and forms control. These functions can also be set up by
user tasks that issue appropriate ANSI-standard escape sequences.

3.1.6

LA180S DECprinter

The LA180S DECprinter is a serial v~rsion of the LA180.
It is a
print-only device (it has no keyboard) that can generate multipart
forms. The LA180S can print uppercase and lowercase letters.

3.1.7

RT02 Alphanumeric Display Terminal
Alphanumeric Display Terminal

and

RT02-C

Badge

Reader/

The RT02 is a compact, alphanumeric display terminal designed for
applications in which source data is primarily numeric. A shift key
permits the entry of 30
discrete characters, including uppercase
alphabetic characters. The RT02 can, however, receive and display 64
characters.
The RT02-C model also contains a badge reader. This option provides a
reliable method of identifying and controlling access to the PDP-11 or
to a secure facility. Furthermore, data in a format corresponding to
that of a badge (22-column fixed data) can be entered quickly.

3.1.8

VTOSB Alphanumeric Display Terminal

The VT05B is an alphanumeric display terminal that consists of a CRT
display and a self-contained keyboard. From a programming point of
view, it is equivalent to other terminals, except that the VT05B
offers direct cursor addressing.

3.1.9

VTSO Alphanumeric Display Terminal

The VTSO is an alphanumeric display terminal that consists of a CRT
display and a keyboard. It is similar to the VT05B in operation, but
does not offer direct cursor addressing.

3.1.10

VTSOH Alphanumeric Display Terminal

The VT50H is an alphanumeric display terminal with CRT display,
keyboard, and numeric pad. It offers direct cursor addressing.
(The
VTSOH's direct cursor addressing is not compatible with that of the
VT05B.)

3-3

HALF-DUPLEX TERMINAL DRIVER
3.1.11

VT52 Alphanumeric Display Terminal

The VT52 is an upper- and lowercase alphanumeric terminal with numeric
pad
and
direct cursor addressing.
(The VT52's direct cursor
addressing is compatible with that of the VTSOH, but not with that of
the VTOSB.)
The VT52 can be configured with a built-in thermal
printer.

3.1.12

VT55 Graphics Display Terminal

3.1.13

VT61 Alphanumeric Display Terminal

The VT61 is an "intelligent"
upper- and lowercase alphanumeric
terminal with an integral microprocessor.
It offers two 128-member
character sets and numerous built-in functions for editing and
preparing forms,
as well as a block-transfer mode.
(None of these
special features is supported by RSX-llM.)

3.1.14

VTlOO DECscope

The VTlOO DECscope
is an
upperand
lowercase
alphanumeric
keyboard/video display terminal.
It is capable of displaying 24 lines
of 80 characters (each line).
Serial communications speed is selected
from baud rates ranging from 50 to 9600 bps.
Hardware features allow
user selection of display characteristics and functions
including
smooth scroll, reverse video, and so forth.
These functions can also
be set up by user tasks that issue appropriate ANSI-standard escape
sequences.

3.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for
terminals.
A setting of 1
indicates that the
described characteristic is true for terminals.
Bit

Setting

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

3-4

HALF-DUPLEX TERMINAL DRIVER
Bit

Setting

Meaning

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 are undefined. Word 5
indicates the default buffer
size for the device:
for terminals the width of the terminal carriage
or display screen.

3.3

QIO MACRO

Table 3-3 lists the standard and device-specific functions of the QIO
macro that are valid for terminals.
All device-specific functions are
options that may be selected at system generation.
Two device-specific functions, SF.SMC and SF.GMC, have nonstandard
function names.
These names are designed for compatibility with IAS.
Table 3-3
Standard and Device-Specific QIO Functions for Terminals
Format

Function

STANDARD FUNCTIONS:
QIO$C IO.ATT, •••

Attach device

QIO$C IO. DET, •••

Detach device

QIO$C IO.KIL, .••

Cancel I/O requests

QIO$C IO.RLB, ••• ,<stadd,size>

READ logical block
(read typed input into buffer)

QIOSC IO.RVB, ••• ,<stadd,size>

READ virtual block
(read typed input into buffer)

QIO$C IO.WLB, ••• ,<stadd,size,vfc>

WRITE logical block
1... •• .C.C-(print UULLt:L
contents)

QIO$C IO.WVB, ••• ,<stadd,size,vfc>

WRITE virtual block
(print buffer contents) •
(continued on next page)

3-5

HALF-DUPLEX TERMINAL DRIVER
Table 3-3 (Cont.)
Standard and Device-Specific QIO Functions for Terminals
Function

Format
DEVICE-SPECIFIC FUNCTIONS
(ALL SYSGEN OPTIONS):
QIO$C IO.ATA, ••• ,<ast>

ATTACH
device,
specify
unsolicitedinput-character
AST

QIO$C IO.CCO, ••• ,<stadd,size,vfc>

CANCEL CTRL/O (if in effect),
then write logical block

QIO$C SF.GMC, ••• ,<stadd,size>

GET multiple characteristics

QIO$C IO.GTS, ••• ,<stadd,size>

GET terminal support

QIO$C IO.RAL, ••• ,<stadd,size>

READ logical
bits

QIO$C IO.RNE, ••. ,<stadd,size>

READ logical block, do not echo

QIO$C IO.RPR, ••• ,<stadd,size,
[tmo] ,pradd,prsize,vfc>

READ logical block after prompt

QIO$C IO.RST, ••• ,<stadd,size>

READ logical block
special terminators

QIO$C SF.SMC, ••• ,<stadd,size>

SET multiple characteristics

QIO$C IO.WAL, ••• ,<stadd,size>

WRITE logical block,
bits

QIO$C IO.WBT, ••• ,<stadd,size,vfc>

WRITE logical
block,
break
through most I/O conditions at
terminal

block,

pass

all

ended

pass

all

ast
The entry point for an unsolicited-input-character AST.
pr add
The starting address of the byte buffer where the prompt
stored. The buffer must be within the task's address space.

prsize
The size of the pradd prompt buffer in bytes.
If the system
supports variable length reads, the buffer size must be greater
than 0 and less than or equal to 255. If the system does not
support variable length reads, the specified size must be greater
than 0 and less than or equal to 80~

3-n

HALF-DUPLEX TERMINAL DRIVER

size
The size of the stadd data buffer in bytes (must be greater than
0).
If the function
is a
read
and
the system supports
variable-length reads, the size must be less than or equal
to
255.
Otherwise, the size must be less than or equal to 80.
The
buffer must be within the task's address space.
For SF.GMC,
IO.GTS, and SF.SMC,
the size must be an even number less than
40n5 (decimal).
If the function is a write, size can be up to
32K bytes.

stadd
The starting address of the data buffer.
The address must be
word aligned
for SF.GMC, IO.GTS, and SF.SMC; otherwise, stadd
may be on a byte boundary.

tmo
An optional time-out count, included for IAS
supplied, it is ignored.

compatibility.

vf c
A character for vertical format
Section 3. 7).

3.3.l

control

from

Table

3-11

(see

Subfunction Bits

Most of the device-specific functions supported by the terminal driver
are implemented by way of "subfunction bits." That is, these functions
can be invoked by ORing a named bit with some other function.
Table
3-4 shows the relationship of the 10 subfunction bits to the standard
and device-specific functions.
The 10 subfunction bits, and their octal values, are:
TF.AST
TF .BIN
TF.CCO
TF.ESQ
TF.RAL
TF.RNE
TF.RST
TF.WAL
TF.WBT
TF.XOF

Unsolicited-input-character AST
Binary prompt
Cancel CTRL/O
Recognize escape sequences
Read all bits
Read with no echo
Read with special terminators
Write all bits
Break-through write
Send XOFF

10
2
40
20
10
20
l
10
100
100

The subfunction bits are defined in the system module TTSYM (discussed
further
in Section 3.3.2.5).
The octal values of these entities are
subject to change;
therefore, it is recommended that you always use
the symbolic names.
As Table 3-4 shows, 7 of the 10 subfunction bits
can be ORed with standard QIO functions
to
invoke device-specific
functions.
The remaining three subfunction bits {TF.BIN, TF.ESQ, and
TF.XOF) can be ORed with Attach and Read After Prompt QIOs to provide
added features, as described in Section 3.3.2.

3-7

HALF-DUPLEX TERMINAL DRIVER
Of the 10 subfunction bits, 3 can be used with Read QIO functions,
3
with Write functions, 2 with Attach functions, and 5 with Read After
Prompt.
The breakdown is:
Read
Write
Attach
Read After Prompt

TF.RAL,
TF.CCO,
TF.AST,
TF.BIN,

TF.RNE, TF.RST
TF.WAL, TF.WBT
TF.ESQ
TF.XOF, TF.RAL, TF.RNE, TF.RST

If a task invokes a subfunction bit that
is not supported on the
system, the subfunction bit is ignored, not rejected.
For example, if
Read with Special Terminators is not selected,
either
IO.RST or
IO.RLB!TF.RST is interpreted as IO.RLB.
The following
example shows a
QIO request
subfunction bit:
a nonechoed
read, which
special terminator, after a prompt.

using more than one
may be concluded by a

QIO$C IO.RPR!TF.RNE!TF.RST, ••• ,<stadd,size,,pradd,prsize,vfc>

3.3.2

Details on Device-Specific QIO Functions

All the device-specific functions described in this section are SYSGEN
options.
All except SF.GMC, IO.RPR, SF.SMC, and IO.GTS can be issued
by ORing a particular subfunction bit with another QIO function.
These subfunction bits are specified in the text;
subfunction bits
are described in general in Section 3.3.1.
In addition to the 11 device-specific QIO functions, this section also
gives details on the
features provided by the 3 subfunction bits
TF.ESQ, TF.BIN, and TF.XOF.

3.3.2.1 IO.ATA - IO.ATA is a variation of the Attach directive.
It
specifies an asynchronous system trap (AST) to process an unsolicited
input character. When called as follows:
QIO$C

IO.ATA, ••• ,<ast>

this function attaches the terminal and identifies "ast" as the entry
point for an unsolicited-input-character AST.
Control passes to this
address whenever any unsolicited character (other than CTRL/Q, CTRL/S,
or CTRL/O)
is
input.
Note that little checking
is done on the
specific AST address.
A bad address is frequently detected only when
the Executive tries to transfer control to it and the task crashes.
In particular, CTRL/C is trapped by the task and does not reach MCR.
Thus,
any task that uses IO.ATA should recognize some.input sequence
as a request to terminate, because MCR can not be invoked to abort the
task in case of difficulty.
Note that this mechanism is intended to get a
single character into
the system
not a series of characters.
Since the driver must
become a fork process in order to declare an AST, a second character
can.arrive before the driver can queue an AST for the first character.
The buffer for unsolicited input characters, however,
is one byte
long.
Therefore,
the terminal driver ignores the second character.
This circumstance can occur because of fast input on a busy system or
because output is in progress when the characters are received.
The
implications of this are that neither type-ahead nor
full-duplex
operations can be simulated perfectly using unsolicited character
ASTs.

Table 3-4
Subfunction Bits
Allowed Subfunction Bits
Function

Equivalent with
subfunction bits

TF.RAL

TF.RNE

TF.RST

IO.RLB

IO.RVS

TF.AST

TF.BIN

TF.CCO

TF.ESQ

TF.WAL

TF.WBT

TF.XOF

STANDARD FUNCTIONS

IO.ATT

IO.DET
IO.KIL

IO.WLB

IO.WVB

DEVICE-SPECIFIC FUNCTIONS
w
I

IO.ATA

IO.ATT!TF.AST

Io.cco

IO.WLB!TF.CCO

\.0

SF.GMC
IO.GTS
IO.RAL

IO.RLB!TF.RAL

IO.RNE

IO.RLB!TF.RNE

IO.RLB!TF.RST

1
1

IO.RPR
IO.RST

x
1

SF.SMC
IO.WAL

IO.WLB!TF.WAL

IO.WBT

IO.WLB!TF.WBT

x
x

1. Exercise great care when using Read All and Read with Special Terminators together.
result.
2. These subfunction bits are allowed but are not effective.
virtual is converted to a read or write logical.

Obscure problems can

They are stripped off when the read

write

HALF-DUPLEX TERMINAL DRIVER
At entry, the unsolicited character is the low-order byte of the top
word on the stack.
Before exiting the AST, be sure to pop that word
off the stack; otherwise, the task will crash.
In all other respects
the AST environment is standard:
SP+lO

Event flag mask word

SP+06

PS of task prior to AST

SP+04

PC of task prior to AST

SP+02

Task's directive status word

SP+OO

Unsolicited character in low byte

See the RSX-llM/M-PLUS Executive Reference Manual for further details
on ASTs.
See Section 3.10.10 for hints on ASTs in a multiterminal
environment.
IO.ATA is equivalent to IO.ATT ORed with the subfunction bit TF.AST.

3.3.2.2 IO.ATT!TF.ESQ - The task issuing this directive attaches a
terminal and notifies the driver that it recognizes escape sequences
input from that terminal.
Escape sequences are recognized only for
solicited
input.
See Section 3.6 for a discussion of escape
sequences.
If the terminal has not been declared capable of generating escape
sequences,
IO.ATT!TF.ESQ has no effect beyond attaching the terminal.
No escape sequences are returned to the task, because any ESC sent by
the terminal acts as a line terminator.
The SF.SMC QIO or the MCR SET
/ESCSEQ command is used to declare the terminal capable of generating
escape sequences (see Table 3-5 and Section 3.3.2.12).

3.3.2.3 IO.CCO - This write function directs the driver to write to
the terminal
regardless of a CTRL/O condition that may be in effect.
If CTRL/O is in effect, it is canceled before the write is done.
IO.CCO is equivalent to IO.WLB!TF.CCO.

3.3.2.4 SF.GMC - The Get Multiple Characteristics function returns
information on terminal characteristics. Get Multiple Characteristics
is used in the following way:
QIO$C SF.GMC, ••• ,<stadd,size>
stadd
The starting address of a data buffer
Each word in the buffer has the form
.BYTE
.BYTE

length

characteristic-name
0

characteristic-name
One of the eight bit names given in Table 3-5.

3-10

"size"

bytes.

HALF-DUPLEX TERMINAL DRIVER
The QIO function returns a value in the high-order byte of each
byte-pair:
1 if the characteristic is true for the terminal, 0 if not
true.
For the TC.TTP characteristic (terminal type), one of three values
returned in the high-order byte, as shown in Table 3-6.

NOTE
The half-duplex terminal driver treats
the
terminal
type
as
a
required
characteristic for the type of terminal
specified.
The terminal type (TC.TTP)
does not set any implicit
terminal
characteristics other than those noted
in Table 3-6.
Table 3-5
Terminal Characteristics for SF.GMC and SF.SMC Requests
Bit
Name

Octal
Value

TC.ASP3
TC.ESQ
TC.HLDl
TC.NEC
TC.PRI2
TC.SCP
TC.SLV
TC.SMR

44
47
51
12
50
25

TC.TTP

TC.HFF
TC.RSP3
TC.XSP3

Meaning
(If Asserted):

Corresponding
MCR Command

Terminal •••

Remote line answer speed
••• can generate escape sequences
••• is in hold-screen mode
••• is in no-echo mode
••• is privileged
••• is a scope (CRT)
••• is slaved
Uppercase conversion disabled
on input
Terminal type

76
35

••• handle hardware form feeds
Receiver speed
Transmitter speed

SET /REMOTE=TI:speed
SET /ESCSEQ=TI:
SET /HOLD=TI:
SET /NOECHO=TI:
SET /PRIV=TTnn:
SET /CRT=TI:
SET /SLAVE=TTnn:
SET /LOWER=TI:
SET /LA30S=TI:
SET /VT05B=TI:
SET /FORMFEED=TI:
SET /SPEED=TI:rcv:xmit
(As above)

1. Effective for VT5x and VT61 only.
2. Cannot be changed by a task;

must use MCR command.

3. Recognized only by the SF.SMC function.
Table 3-6
Bit TC.TTP (Terminal Type): Values Set by SF.SMC
and Returned by SF.GMC
Octal Value

Symbolic

Meaning

T.UNKO

T.AS33

T.L30S

T.VT05

Terminal type is unknown
(resets all other types)
Terminal is an ASR
(sets uppercase conversion on
output)
Terminal is an LA30
(sets horizontal fill after
carriaae return)
Termin~l is a VT05B
(sets a vertical fill count of 4)

3-11

HALF-DUPLEX TERMINAL DRIVER
3.3.2.5 IO.GTS - The Get Terminal Support QIO returns a 4-word buffer
of information specifying which SYSGEN-option features are part of the
terminal driver.
Of these four words,
two are currently defined.
Table 3-7 gives details on these two words.
The IO.GTS QIO is itself
a SYSGEN option.
If IO.GTS is issued on a minimum system (one with no
terminal-driver SYSGEN options), IE.IFC is returned in the I/O status
block.
Table 3-7
Information Returned by Get Terminal Support (IO.GTS) QIO
Bit

Value

Mnemonic

Meaning When Set to 1

Word 0 of Buffer:
-- -

7
8
9
10
11
12
13
14

1
2
4
10
20
40
100
200
400
1000
2000
4000
10000
20000
40000

Fl.ACR
Fl.BTW
Fl.BUF
Fl. UIA
Fl. CCO
Fl. ESQ
Fl. HLD
Fl. LWC
Fl. RNE
Fl. RPR
Fl.RST
Fl. RUB
Fl. SYN
Fl.TRW
Fl. UTB

100000

Fl. VBF

0
1
2
3
4
5
6

Automatic CR/LF on long lines
Break-through write
Checkpointing during terminal input
Unsolicited-input-character AST
Cancel CTRL/O before writing
Recognize escape sequences in solicited input
Hold-screen mode
Lower- to uppercase conversion
Read with no echo
Read after prompting
Read with speciaf terminators
CRT rubout
CTRL/R terminal synchronization
Read all and write all
Input characters buffered in task's address
space
Variable-length terminal buffers

Word 1 of Buffer:
-- 0

F2eSCH
F2.GCH

Set characteristics QIO (SF.SMC)
Get characteristics QIO (SF.GMC)

The various symbols used by the IO.GTS, SF.GMC, and SF.SMC QIOs are
defined in a system module, TTSYM. These symbols include: Fl.xxx and
F2.xxx (Table 3-7); T.xxxx (Table 3-6); TC.xxx (Table 3-5); and the
SE.xxx error returns described
in Table 3-8, Section 3.4.
These
symbols may be defined locally within a code module by using:
.MCALL

TTSYM$

TTSYM$
If the symbols are not defined locally, they are automatically defined
by the Task Builder.
The octal values of these symbols are subject to change.
it is recommended that you always use the symbolic names.

3-12

Therefore,

HALF-DUPLEX TERMINAL DRIVER
3.3.2.6 IO.RAL - The Read All function causes the driver to pass all
bits to the requesting task.
The driver does not intercept control
characters or mask out the "parity" (high-order) bit.
This means, for
example, that CTRL/C, CTRL/Q, CTRL/S, CTRL/O, and CTRL/Z are passed to
the program and are not interpreted by the driver.
NOTE
IO.RAL echoes the characters that are
read. To read all bits without echoing,
use IO.RAL!TF.RNE.
IO.RAL is equivalent to IO.RLB ORed with the subfunction bit TF.RAL.
The only way to terminate an IO.RAL function is by a character count
(that is, filling the input buffer).

3.3.2.7 IO.RNE - IO.RNE causes the driver to read a line from the
terminal without echoing the characters that are input. This feature
is useful when typing sensitive information:
for example, a password
or combination.
IO.RNE is also used to read a badge with the RT02-C.
(Another way to suppress echoing of input is to set the terminal to
no-echo mode with the SF.SMC QIO or the MCR SET /NOECHO command.
See
Table 3-5, bit TC.NEC.)
Note that the TC.NEC subfunction only suppresses echoing of
input.
Unsolicited input is still echoed.

solicited

CTRL/R, if selected as a SYSGEN option, is ignored while an IO.RNE
in progress.

IO.RNE is equivalent to IO.RLB ORed with the subfunction bit TF.RNE.

3.3.2.8 IO.RPR - The QIO function IO.RPR (Read After Prompt) has the
same effect as IO.WLB (to write a prompt to the terminal) followed by
IO.RLB.
However, IO.RPR differs in four ways from this combination of
QIOs. With IO.RPR:
•

System overhead is lower because only one QIO is processed.

•

There is no "window" during which a response to the prompt may
be ignored.
Such a window occurs if IO.WAL/IO.RLB is used,
because no read may be posted at the time the response is
received.

•

If the issuing task is checkpointable,
during both the prompt and the read.

•

A CTRL/O that may be in effect is canceled before
is written.

The third user-specified argument to IO.RPR,
tmo,
is
compatibility with IAS.
If supplied, it is ignored.

checkpointed
the

prompt

required

for

Subfunction bits may be ORed with IO.RPR to write the prompt as a
Write All (TF.BIN) and to send XOFF after the read (TF.XOF). See the
next two sections.
In addition,
the three Read subfunction bits
(TF.RAL, TF.RNE, TF.RST) can be used with IO.RPR.

3-13

HALF-DUPLEX TERMINAL DRIVER
3.3.2.9 IO.RPR!TF.BIN - This QIO function results in a read after a
"binary" prompt, that is, a prompt that is written by the driver with
no character interpretation (as if it were issued as an IO.WAL).

3.3.2.10 IO.RPR!TF.XOF =This QIO function causes the driver to send
an XOFF to the terminal after its prompt-and-read. The XOFF, or
CTRL/S, may have the effect of inhibiting input from the terminal, if
the terminal recognizes XOFF for this purpose.

3.3.2.11 IO.RST - This QIO function acts like IO.RLB, except that
certain special characters terminate the read. These characters are
in the ranges 0-37(8) and 175-177(8). The driver does not interpret
the terminating character, with certain exceptions.l For example, a
horizontal TAB (11 octal) is not expanded, a RUBOUT (or DEL, 177
octal) does not erase, and a CTRL/C does not get MCR's attention.
Upon successful completion
terminated by filling the
like the following:

of an IO.RST request that was
not
input buffer, the I/O status block looks

Terminating
character

IOSB

IS.SUC&377

i of bytes in buffer

The terminating character is not in the buffer.
IO.RST is equivalent to IO.RLB!TF.RST.

3.3.2.12 SF.SMC - This QIO function allows a task to set and reset
the characteristics of a terminal. Set Multiple Characteristics is
the inverse of SF.GMC. Like SF.GM.C, it is called in the following
way:
QIO$C SF.SMC, ••• ,<stadd,size>
stadd
The starting address of a buffer of length "size" bytes.
Each word in the buffer has the form
.BYTE characteristic-name
.BYTE value

1. If upper- and lowercase conversion is disabled (see remarks in
Section 3.10.9), the character 175(8) echoes as right-brace and 176{8)
as tilde, and these characters do not act as terminators.
The three
characters
CTRL/O,
CTRL/Q,
and
CTRL/S
(17, 21, and 23(8),
respectively) are not special terminators. The driver interprets them
as output effectors.
3-14

HALF-DUPLEX TERMINAL DRIVER
characteristic-name
One of the symbolic bit names given in Table 3-5.
value
Either O (to clear a given characteristic)
or 1
(to set a
characteristic).
Table 3-5 notes the restrictions that apply to
these characteristics.
If characteristic-name is TC.TTP (terminal type), then value can
any of the values listed in Table 3-6.

have

A nonprivileged task can only issue an SF.SMC request to affect its
own terminal, TIO:.
A privileged task can issue SF.SMC to any
terminal.

3.3.2.13 IO.WAL - The Write All function causes the driver to pass
all output from the buffer without interpretation.
It does not
intercept control characters.
Lines are neither wrapped around
(if
input/output
wrap-around
has been selected)
nor truncated
(if
wrap-around is not selected).
IO.WAL is equivalent to IO.WLB!TF.WAL.

3.3.2.14 IO.WBT - The Write Break Through function instructs the
driver to write the buffer regardless of the I/O status of the
receiving terminal.
If an IO.WET is issued on a system that does not
support IO.WET, it is treated as an IO.WLB.
•

If another write is in progress, it finishes and the IO.WET is
the next write issued. The effect of this is that IO.WBTs can
be stopped by a CTRL/S. Therefore, tasks may still want to
time out on IO.WET.

•

If a read is posted, the IO.WET proceeds anyway, and an
automatic CTRL/R is performed to redisplay any input that was
received before the break-through write.

•

CTRL/S and/or CTRL/O, if in effect, are canceled.

•

Characters input during a break-through write are ignored.

An IO.WET cannot break through another IO.WET that is in progress or
if a prompt is bein~ written by IO.RPR.
In either case, the low-order
byte of the first word of the I/O status block contains IE.RSU&377.
The task receiving this error need only reissue the write.
Break-through write may only be issued by a privileged task.
However,
the task does not have to be mapped to the Executive (Task Builder
options /PR:4 or /PR:5). A task can use IO.WET if it is built with
the
/PR:O
switch
specified.
The privileged MCR command BRO
(broadcast) uses IO.WET.
Break-through write cannot break through a multiecho.
Instead,
it
returns error code IE.RSU. When this occurs, the task should reissue
the write request.

3-15

HALF-DUPLEX TERMINAL DRIVER
3.4

STATUS RETURNS

Table 3-8 lists error and status conditions that are returned
terminal driver.

Upon successful completion of a read, the I/O
data of this sort:

contains

Word

ret

I+l

Number of bytes read

status

block

the

Byte

ret

means

ret

means

IS.CR:

ret

means

IS. ESC: read terminated by an Altmode.

ret

233

means

IS.ESQ: read terminated by an escape sequence.

IS. sue: the return code for successful
completion.

read terminated by buff er full
(byte count satisfied);
read terminated by carriage return.

Most RSX-llM return codes are byte values:
for example, rs.sue = 1 is
a
byte value.
By contrast, the three return codes IS.CR, IS.ESC, and
IS.ESQ are word values.
The low-order byte indicates successful
completion, and the high-order byte is required to show what type of
completion occurred.
To test for one of these word-value ·return codes, first test the
low-order byte of the first word of the IOSB for the value rs.sue.
Then test the full word for IS.CR, IS.ESC, or IS.ESQ.
(If the full
word tests equal to rs.sue, then its high-order byte is o, indicating
byte-count termination of the read.)
The "error" return IE.EOF may be considered to indicate a successful
read, because characters can be returned to the task's buffer.
The three errors in Table 3-8 with SE.xxx codes are returned by the
SF.GMC and SF.SMC QIOs.
They are characterized by IE.AB0&377 in the
low-order byte of the first IOSB word.
The high-order byte contains
the error code.
The second IOSB word contains an offset (starting
from 0) to the byte in error in the QIOs stadd buffer.

3.5

CONTROL CHARACTERS AND SPECIAL KEYS

This section describes the meanings of special terminal control
characters and keys for RSX-llM.
Note that the driver does not
recognize control characters and special keys during a Read All
request
(IO.RAL), and recognizes only some of them during a Read with
Special Terminators (IO.RST).

3-16

HALF-DUPLEX TERMINAL DRIVER
Table 3-8
Terminal Status Returns
Code

Reason

IE.EOF

Successful completion on a read with end-of-file
The line of input read from the terminal was
terminated with the end-of-file character CTRL/Z.
The second word of the I/O status block contains
the number of bytes read before CTRL/Z was seen.
The input buffer contains those bytes.
Successful completion
The operation specified in the QIO directive was
completed successfully.
If the operation involved
reading or writing, you can examine the second word
of the I/O status block to determine the number of
bytes processed. The input buffer contains those
bytes.

IS.CR

Successful completion on a read
The line of input read from the terminal was
terminated by a carriage return.
The input buffer
contains the bytes read.

IS.ESC

Successful completion on a read
The line of input read
from the terminal was
terminated by an Altmode character.
The input
buffer contains the bytes read.

IS.ESQ

Successful completion on a read
The line of input read from the terminal was
terminated by an escape sequence.
The input buffer
contains the bytes read and the escape sequence.

IS.PND

I/O request pending
The operation specified in the QIO directive has
not yet been executed.
The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled by IO.KIL
while in progress or while in the I/O queue.
The
second word of the IOSB shows how many bytes were
processed before the kill took effect. Note that
the SE.xxx error codes are characterized by IE.ABO&
377 in the low-order byte of the first word of the
IOSB.

IE.BAD

Bad parameter
The size of the prompt in a
read-after-prompt QIO
is too big
(that is, greater than 255 bytes on
systems supporting variable-length
buffers
or
greater than 80 on systems that do not).
(continued on next page)

3-17

HALF-DUPLEX TERMINAL DRIVER
Table 3-8
(Cont.)
Terminal Status Returns
Code
IE.DAA

Reason
Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code indicates that the issuing task has
already attached the desired physical device unit,
not that the unit was attached by another task.
If
the
attach specified TF.AST or TF.ESQ,
these
subfunction bits have no effect.

IE.DNA

Device not attached
The physical device unit specified in an IO.DET
function was not attached by the issuing task.
This code has no bearing on the attachment status
of other tasks.

IE.DNR

Device not ready
The physical device unit specified in the QIO
directive was not ready to perform the desired I/O
operation. This code is returned to indicate one
of the following conditions:

IE.IES

•

A time-out occurred on the physical device
(that is, an interrupt was lost).

unit

•

An attempt was made to perform a function on a
remote
DHll
or DZll line without carrier
present.
(The line is hung up.)

Invalid escape sequence
An escape sequence was started but escape-sequence
syntax
was
violated before the sequence was
completed. See Section 3.6.4.

IE.IFC

IE.NOD

Illegal function
A function code specified in an I/O request was
illegal for terminals;
or, the function code
specified was a SYSGEN option not selected for this
system.

Buffer allocation failure

System dynamic storage has been depleted, and there
was insufficient space available to allocate anj
intermediate buffer for an input request.
(continued on next page}

3-18

HALF-DUPLEX TERMINAL DRIVER
Table 3-8
(Cont.)
Terminal Status Returns
Reason

Code
IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE.PES

Partial escape sequence
An escape sequence was started, but read-buffer
space
was
exhausted before the sequence was
completed.
See Section 3.6.4.3.

IE.PR!

Privilege violation
In a multiuser system, a nonprivileged task either
issued an IO.WBT or directed an SF.SMC to a
terminal other than its own TIO:.

IE.RSU

Resource in use
The prompt of an IO.RPR, or a break-through write,
Reissue
was in progress when an IO.WBT was issued.
the IO.WBT later.

IE.SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task.
Alternately, a byte count of
0 was specified.

SE.BIN

The
new
value
specified
for
a
terminal
characteristic in an SF.SMC request was not 0 or 1.
(Characteristics other than TC.TTP -- see Table
3-5.)

SE.NIH

A terminal characteristic other than those in Table
3-5 was named in an SF.GMC or SF.SMC request; or,
a task attempted to assert TC.PR!.

SE.VAL

The new value specified in an SF.SMC request for
the TC.TTP terminal characteristic was not one of
those listed in Table 3-6, or the baud rate (speed)
specified is not valid.

3-19

HALF-DUPLEX TERMINAL DRIVER
3.5.1

Control Characters

A control character is input from a terminal by holding the control
key
(CTRL)
down while typing one other key.
Two of the control
characters described in Table 3-9, CTRL/U and CTRL/Z, are echoed on
the terminal as AU and AZ, respectively.
Other control characters are
recognized by the terminal driver, but are not printing characters and
therefore are not echoed.
Table 3-9
Terminal Control Characters
Character

Meaning

CTRL/C

Typing CTRL/C repeatedly is the way to get a
terminal's
attention.
Normally, typing CTRL/C
causes unsolicited input on that terminal
to be
directed to the Monitor Control Routine (MCR).
"MCR>" echoes when the terminal is ready to accept
unsolicited
input.
When the unsolicited
input
completes, it is passed to MCR.
If the last item typed on the terminal was CTRL/S
(suspend output),
then CTRL/C restarts suspended
output and directs subsequent input to MCR.
If the hold-screen mode option has been selected at
SYSGEN, and
if the terminal is a VT5x or VT61 in
hold-screen mode, then typing a string of CTRL/Cs
eventually removes the terminal from hold-screen
mode.
Not all CTRL/Cs act to get MCR's
attention.
CTRL/Cs are directed to a task if the task has
attached a
terminal
and
has
specified
an
unsolicited-input-character AST. See the discussion
on
unsolicited-input-character
ASTs,
Section
3.3.2.1.
CTRL/Cs also go to a task if an IO.RAL
(Read
All)
or
IO.RST
(Read
with
Special
Terminators) is posted.

CTRL/I

Typing CTRL/I or TAB initiates a horizontal tab,
and the terminal spaces to the next tab stop.
Tabs
at every eighth character position are simulated by
the terminal driver.

CTRL/J

Typing CTRL/J is equivalent to typing the LINE FEED
key on the terminal.

CTRL/K

Typing CTRL/K initiates a vertical
terminal performs four line feeds.

CTRL/L

Typing CTRL/L initiates a
form feed,
and the
terminal performs eight line feeds.
Paging is not
performed.

CTRL/M

Typing CTRL/M is equivalent to typing the carriage
RETURN key on the terminal (see Section 3.5.2).

tab,

and

the

(continued on next page)

3-20

HALF-DUPLEX TERMINAL DRIVER
Table 3-9
(Cont.)
Terminal Control Characters
Character

Meaning

CTRL/O

Typing CTRL/O suppresses output being sent to a
terminal by the current I/O request.
For attached
terminals, CTRL/O remains in effect, and output
continues
to be suppressed until any of the
following occurs:
1.

The terminal is detached.

Input is entered.

Another CTRL/O character is typed.

An IO.CCO, IO.WBT, or IO.RPR is processed.

For unattached terminals, CTRL/O suppresses output
for only the current output buffer (generally one
1 ine) •
CTRL/Q

(SYSGEN option.)
Typing CTRL/Q resumes terminal
output previously suspended by means of CTRL/S.

CTRL/R

(SYSGEN option.)
Typing CTRL/R on a
terminal
results in the echo of CR/LF followed by the
incomplete (unprocessed) input line. Any tabs that
were input are expanded and
the effect of any
rubouts is shown.
On hard-copy terminals,
CTRL/R
allows you to verify the effect of tabs and/or
rubouts in an input line.
CTRL/R is also useful
for CRT terminals when the automatic-cariage-return
and CRT rubout SYSGEN options have been selected
(see Section 3.8).
For example, after rubbing out
the leftmost character on the second displayed line
of a wrapped
input line, you will find that the
cursor does not move to the right of the first
displayed line.
In this case, CTRL/R brings the
input line and the cursor back together again.

CTRL/S

{SYSGEN option.)
Typing CTRL/S causes terminal
output to be suspended.
Output is resumed by
typing CTRL/Q or CTRL/C.

CTRL/U

Typing CTRL/U before typing a
line terminator
causes previously typed characters to be deleted
back to the beginning of the line.
The system
echoes this character as AU followed by a carriage
return and a line feed.
This allows you to retype
the line.

CTRL/Z

Typing CTRL/Z indicates an end-of-file for
the
current terminal input.
It signals MAC, PIP, TKB,
and other system tasks that terminal
input is
complete and the task should exit.
The system
echoes this character as AZ followed by a carriage
return and a line feed.

3-21

HALF-DUPLEX TERMINAL DRIVER
3.5.2

Special Keys

The ESCape, carriage RETURN, and RUBOUT, keys have special significance
for
terminal input, as described
in Table 3-10.
A line can be
terminated by an ESCape (or Altmode) character, by a carriage RETURN,
by CTRL/Z, or by completely filling the input buffer (that is, by
exhausting the byte count before a line terminator is typed) e
The
standard buffer size for a terminal can be determined by issuing a GET
LUN INFORMATION system directive and examining Word 5 of
the
information buffer.
Another way is to type the MCR command "SET
/BUF=TI:".

3.6

ESCAPE SEQUENCES

Escape sequences are strings of two or more characters beginning with
33 octal.
Some terminals generate an escape sequence when a special
key is pressed (for example, the PFl key on the VTlOO).
On any
terminal, an escape sequence may be generated manually by typing
ESCape and the appropriate following characters.
Escape sequences provide a way to pass input to a task without
interpretation by the operating system. This could be done with a
number of 1-character Read Alls, but escape sequences allow a neater
way to accomplish it (they can be read with ordinary IO.RLBs).
Most DIGITAL software currently does not employ escape sequences. The
specifics provided here are for the benefit of users who wish to take
advantage of escape sequences in their own tasks.

3.6.1

Definition

An escape sequence is defined as follows:
ESC [int]

••• [int]

fin

ESC
The result of pressing the ESCape
33(8).

key,

byte

(character)

int
An "intermediate character" in the range 40(8)
to 57(8).
This
range includes the character "space" and 15 punctuation marks.
An escape sequence may contain any number of intermediate
characters, or none.
fin
A "final character" in the range 60{8)
to 176{8).
This range
includes
upperand
lowercase
letters, numbers, and 113
punctuation marks.
There are four exceptions to
Section 3.6.5.

this

general

3-22

definition

discussed

HALF-DUPLEX TERMINAL DRIVER
Table 3-10
Special Terminal Keys
Key

Meaning

ESCape

If escape sequences are not recognized, typing
ESCape or Altmode signals the terminal driver that
there is no further input on the current line.
This line terminator allows further input on the
same line, because the carriage or cursor is not
returned to the first column position.
If escape sequences are recognized, ESCape signals
the beginning of an escape sequence. See Section

3.o.

RETURN

Typing RETURN terminates the current line and
causes the carriage or cursor to return to the
first column on the line.

RUBOUT

Typing RUBOUT deletes the last character typed on
an input line.
Only characters typed since the
last line terminator may be deleted.
Several
characters can be deleted in sequence by typing
successive RUBOUTs.
The first RUBOUT echoes as a backslash
(\),
followed by the character that has been deleted.
Subsequent RUBOUTs cause only the deleted character
to be echoed. The next character typed that is not
a RUBOUT causes another backslash, followed by the
new character, to be echoed. The following example
illustrates rubbing out ABC and then typing CBA:
ABC\CBA\CBA
The second backslash is not displayed if a line
terminator
is
typed
after
rubbing out the
characters on a line, as in the following:
ABC\CBA
(SYSGEN option.) At SYSGEN time you may elect to
support a "CRT rubout" feature.
This feature
applies to a terminal only after a SET
MCR
directive has been issued:
SET /CRT=TI:
(Note: See Section 3.3.2.12 for another way this
SET can be accomplished, with the SF.SMC QIO
function.) When a RUBOUT is struck, the last typed
character (if any) is removed from the incomplete
input line and backspace-space-backspace is echoed.
If the last typed character was a tab, enough
backspaces are issued to move the cursor to the
character position before the tab was typed. If a
long input line was split, or "wrapped," by the
automatic-carriage-return
option, and a RUBOUT
erases the last character of a previous line, the
cursor is not moved to the previous line. CTRL/R
must be used to resynchronize the display with the
contents of the incomplete input line.

3-23

HALF-DUPLEX TERMINAL DRIVER
3.6.2

Prerequisites

Two prerequisites must be satisfied before
received by a task.

escape

sequences

can

First, the task must "ask" for them by issuing an IO.ATT and
the subfunction bit TF~ESQ~

invoking

Second, the terminal must be declared capable of generating
sequences. This may be done with an MCR SET command:

escape

SET /ESCSEQ=TI:
An alternative way to tell the driver that the terminal can generate
escape sequences is by issuing the Set Multiple Characteristics QIO.
See Section 3.3.2.13.
If either of these prerequisites is not satisfied, the ESC character
is treated as a line terminator.
If both prerequisites are satisfied,
then an additional feature results.
CTRL/SHIFT/O (37(8)) may be used
as an Altmode.l
This character does not act as an Altmode from a terminal that
generate escape sequences.

3.6.3

cannot

Characteristics

3.6.4

Escape Sequence Syntax Violations

A violation of the syntax defined in Section 3.6.1 causes the driver
to abandon the escape sequence and to return an error (IE.IES).

3.6.4.1 DEL or RUBOUT {177{8)) - The character DEL or RUBOUT is not
legal within an escape sequence.
Typing it at any point within an
escape sequence causes the entire sequence to be abandoned and deleted

1. An Altmode is a line terminator that does not cause the cursor to
advance to a new line.
On terminals that cannot generate escape
sequences, the ESCape key acts as an Altmode.
So do the characters
175(8)
and 176(8),
if the terminal has not been declared lowercase
(MCR command SET /LOWER).
If the terminal is lowercase, then these
characters represent right-brace and tilde, respectively.
3-24

HALF-DUPLEX TERMINAL DRIVER
from the input buffer.
Thus, use DEL or RUBOUT to abandon an escape
sequence,
if desired, once you have begun it.
For example, if you
enter:
AB ESC

DEL CR

the buffer contains "AB" and the
following:

I/O

status

block

looks

the

IOSB

3.6.4.2 Control Characters (0-37(8)) - The reception of any character
in the range 0 to 37(8) (with four exceptions -- see footnotel) is a
syntax violation that terminates the read with an error (IE.IES).
For
example, entering:
ESC

CTRL/SHIFT/O

results in a buffer that contains these three characters
status block that is similar to the following:
IOSB

and

I/O

3.6.4.3 Full Buffer - A syntax error results when an escape sequence
is terminated by running out of read-buffer space, rather than by
reception of a final character. The error IE.PES is returned.
For
example, after a task issues an IO.RLB QIO with a buffer length of 2,
and you type:
ESC !

the buffer contains "ESC ! " , and the I/O status block contains:
IOSB

The "A" is treated as unsolicited input.

1. Four control characters are allowed:
CTRL/Q, CTRL/S,
CTRL/C, and
CTRL/O.
These characters are handled normally by the operating system
even when an escape sequence is in progress.
For example, entering:
ESC CTRL/S A
gives:
IS.ESQ

IOSB

with the side effect of turning off the output stream.

3-25

HALF-DUPLEX TERMINAL DRIVER
3.6.5

Exceptions to Escape-Sequence Syntax

Four "final characters"
that normally would terminate an escape
sequence are treated as special cases by the terminal driver.
These
special cases exist for historical compatibility reasons.
Three of
these ch a r a c t e r s a re :
;
(7 3 (8 ) ) , ?
( 7 7 ( 8 ) ) , and O ( 117 ( 8 ) ) •
The
syntax for escape sequences that contain these four characters as
intermediates is:
ESC

(int]

[int]

fin

ESC ? [int]

[int]

fin

ESC 0 [int]

[int]

f inl

=>
=>
=>

int
fin
f inl

40-57
60-176
100-176

( 8) •

( 8) •
( 8) •

The fourth exception to the general syntax given in Section 3.6.1
involves the "final character" Y (131(8)).
Historically (for example,
in the VT52), ESC Y has been used to signal the cursor position.
It
is followed by two numbers signifying column and row positions:
ESC Y colpos rowpgs
where colpos and rowpos are both characters in the range 40-176(8).
They represent bias-40 numbers: colpos = 40 corresponds to column O,
and so forth.

3.7

VERTICAL FORMAT CONTROL

Table 3-11 summarizes the meanings of all characters used for vertical
format control on the terminal.
Any one of these characters can be
specified as the value of the vfc parameter in the functions
IO.WLB,
IO.WVB, IO.WBT, IO.CCO, or IO.RPR.
Table 3-11
Vertical Format Control Characters
Octal
Value

Character

blank

SINGLE SPACE - Output a line feed,
print the
contents of the buffer, and output a carriage
return.
Normally,
printing
immediately
follows the previously printed line.

DOUBLE SPACE - Output two line feeds,
print
the contents of the buffer, and output a
carriage
return.
Normally,
the
buffer
contents are printed two lines below the
previously printed line.

PAGE EJECT - Output eight line feeds
(or,
if
the terminal
is an LA180S, output a form
feed), print the contents of the buffer, and
output a carriage return.

Meaning

(continued on next page)

3-26

HALF-DUPLEX TERMINAL DRIVER

Table 3-11 (Cont.)
Vertical Format Control Characters
Octal
Value

Character

OVERPRINT - Print the contents of the buffer
and
output
a
carriage return, normally
overprinting the previous line.

PROMPTING OUTPUT - Output a line feed and
print the contents of the buffer. This mode
of output is intended for use with a terminal
on which a prompting message is output, and
input is then read on the same line.

null

Meaning

INTERNAL VERTICAL FORMAT - Print the
buffer
without addition of vertical format
control characters. In this mode, more than
one line of guaranteed contiguous output can
be printed for each I/O request.

I contents

All other vertical format control characters are interpreted as blanks
(40(8)).

3.8

FEATURES AVAILABLE BY SYSGEN OPTION

A number of terminal-driver features are available as options at the
time
the RSX-llM system is generated
(see the RSX-llM System
Generation and Management Guide or RSX-llS System Generation and
Installatio~Guide,
as appropriate). Some that have been mentioned
previously in the text are:
•

All the device-specific QIO functions

•

Special keys
CTRL/S

Suspend output

CTRL/Q

Resume suspended output

CTRL/R

Write incomplete input buffer

CRT rubout
•

Escape sequences

Other features that you may select at SYSGEN time are described in the
following sections.

Automatic Carriage Return

3.8.1

By SYSGEN option, all terminals in a system may be set to "wrap
around," on input and output, after a specified number of columns. If
this option is selected, the number of characters per line is
determined on a terminal-by-terminal basis. An MCR SET command is
used to specify the wrap-around column, n:
>SET /BUF=TI:n

3-27

HALF-DUPLEX TERMINAL DRIVER
(Note that n is an octal number by default.
Type an explicit decimal
point to enter a decimal number.) After SYSGEN and before this SET has
been done for a given terminal,
the default column width is 72
(decimal).
The SET /BUF command used without an argument is
returns the current buffer width for a terminal:

enquiry

that

>SET /BUF=TI:
BUF=TI0:00072.

>
A task can determine the buffer width by issuing a Get LUN Information
directive and examining word 5.
After the SET has been done, typing the n+lst character results in a
CR/LF being output before the n+lst character is echoed (at the
leftmost character position of the next line).
There is still only
one input line, but it is displayed on two lines on the terminal.
Output also wraps around after column n.
This is undesirable for some
applications.
To disable wrap-around, set the buffer to some number
greater than the terminal's column width.
Output -- and
input
too -- beyond the column width will
then overprint at the right
margin. Wrap-around
is also disabled when executing the
IO.WAL
function (see Section 3.10.11), because the driver does not keep track
of the cursor's position.
It is possible to lose track of where you are in the input buffer if
both the automatic carriage return and the CRT rubout features have
been selected at SYSGEN.
If, while rubbing out text on a wrapped
line, you rub out the first character on that line, the cursor will
not back up to the previous line.
In order to resynchronize the
cursor with the contents of the incomplete input buffer, type CTRL/R
(if this option has been selected).
It is also possible to cause wrap-around
to malfunction.
This can
occur when mora than 255(10)
characters are output without an
intervening carriage return.
This condition is possible because the
driver maintains a byte location with the current cursor position;
thus, counts greater than 255(10) are truncated, and the cursor count
will be invalid until the next carriage return is received.

3.8.2

Variable-Length Buffering

If this user-transparent SYSGEN option is selected,
up to
255(10)
characters may be read from a terminal.
The terminal driver allocates
an Executive buffer the same size as the read request.
If the variable-length option is not chosen, any number of characters
may be read from a terminal, but a maximum of 80(10) are transferred
to the task issuing the read request.
An Executive buffer of 80(10)
characters is always allocated.
Note that, whether variable-length buffering is selected or not, a
maximum of 80(10)
characters may be directed to MCR as unsolicited
input.

3-28

HALF-DUPLEX TERMINAL DRIVER
3.8.3

Task Buffering of Received Characters

This user-transparent SYSGEN option causes characters read from the
terminal
to be sent directly to the reading task's buffer. With this
option, no Executive buffer need be allocated, and the completed input
line need not be transferred to the task's buffer.
This option,
however, does not necessarily reduce system overhead.
In a mapped
system, each character must be mapped to the task's buffer.
If
Executive buffering was used, the mapping is done once and then all
the characters are transferred.
For the half-duplex terminal driver,
the Executive buffers only input except for the prompt output on an
IO.RPR request.
Task buffering may be overridden by checkpointing.
If a
task is
checkpointable, an Executive buffer is allocated in the normal way and
the task is made eligible for checkpointing by any task, regardless of
priority, while the read proceeds.
(Checkpointing only occurs when
there is
another
task
that
can
be
made
active.)
Since
checkpointability is a dynamic quality controlled by the task, the
user retains control over the resource trade-off.

3.8.4

LA30-P Support

This option provides a 1-byte software buffer for terminal input from
an
LA30-P.
Because
LA30-Ps
communicate
with RSX-llM by a
single-buffered hardware interface, the echoing of an input character
may block the reception of the next input character.
This is because
a character is normally discarded by the terminal driver if it is
received before the echo of the previous character completes.
The
SYSGEN option for LA30-P support (transparent to the user) will buffer
the second character in the software.
This option should not be chosen at SYSGEN if there are no LA30-Ps
the system.

3.9

TERMINAL INTERFACES

This section summarizes the characteristics of the four types of
standard communication-line interfaces supported by RSX-llM. All four
interfaces support parity, but RSX-llM does not.

3.9.1

DHll Asynchronous Serial Line Multiplexer

The DHll multiplexer interfaces up to 16
asynchronous
serial
communications lines for terminal use.
The DHll supports programmable
baud rates.
Input and output baud rates may differ;
the input rate
may be set to 0 baud, thus effectively turning off the terminal. The
DMll-BB option may be included to provide modem control for dial-in
lines.
These lines must be interfaced by means of a full duplex modem
(for example, in the United States, a Bell 103A or equivalent modem).
The direct memory access {DMA) capability of the DHll is not supported
by the RSX-llM terminal driver.

3-29

HALF-DUPLEX TERMINAL DRIVER
3.9.2

DJll Asynchronous Serial Line Multiplexer

The DJll multiplexer interfaces as many as 16 asynchronous serial
lines to the PDP-11 for local terminal communications.
The DJll does
not provide a dial-in capability, but supports jumper-selectable baud
rates.

3.9.3

DLll Asynchronous Serial Line Interface

The DLll supports a single asynchronous serial line and handles
communication between the PDP-11 and a terminal. A number of standard
baud rates are available to DLll users.
Four versions of the DLll
interface are supported by RSX-llM for terminal use: DLll-A, DLll-B,
DLll-C, and DLll-D.
The DLll-E is supported by the full-duplex
terminal driver described
in Chapter 2, and by the message-oriented
communication drivers described in Chapter 11.

3.9.4

DZll Asynchronous Serial Line Multiplexer

The DZll multiplexer interfaces up to eight asynchronous serial
communication lines for use with terminals.
It supports programmable
baud rates; however, input and output speeds must be the same.
The
DZll can control a full duplex modern in auto-answer mode.

3.10

PROGRAMMING HINTS

This section contains information relevant to users
driver.

3.10.1

the

terminal

Terminal Line Truncation

If automatic carriage return has not been selected at SYSGEN, and if
the number of characters to be printed exceeds the line length of the
physical device unit, then the terminal driver discards the excess
characters until
it receives one that instructs it to return to
horizontal position 1. You can determine when this will happen by
examining word 5 of the information buffer returned by the Get LUN
Information system directive, or by typing "SET /BUF=TI:".

3.10.2

ESCape Code Conversion

If escape sequences are not recognized, an ESCape or Altmode character
code of 33,
175, or 176 is converted internally to 33 before it is
returned to the user on input.

3.10.3

RT02-C Control Function

Because the screen of an RT02C Badge Reader and Data Entry Terminal
holds only one line of information, special care must be taken when
sending a control character (for example, vertical tab) to the RT02-C.
Use IO.WAL (Write All).

3-30

HALF-DUPLEX TERMINAL DRIVER
It is advisable to read without echoing when reading a badge with the
RT02-C.
Use
IO.RAL
or IO.RNE,
and then write the received
information.

3.10.4

Checkpointing During Terminal Input

If checkpointing during terminal
input was selected as a
SYSGEN
option, a checkpointable task is stopped (and therefore eligible to be
checkpointed) when trying to read.
Therefore, a stratagem such as
issuing a read followed by a mark-time does not work.
The intent
might be to time out the read if input is not received in a reasonable
length of time.
But the mark-time is not issued until the read
completes.
You can circumvent this behavior by disabling checkpointing for the
read.
This is not a desirable solution because it forces a task to
remain in memory during the entire read.
This defeats the purpose of
selecting the checkpoint-during-terminal-input option.

3.10.5

Time Required for IO.KIL

An IO.KIL request may take up to 1 second to succeed, because an
internal mark-time mechanism is used to generate a software interrupt
to get into a clean state. The I/O may reach a state in which the
kill can complete within this time
(for instance, if a hardware
interrupt is received).
If not, the request is killed after 1 second.

3.10.6

Use of IO.WVB

We recommend that you routinely use IO.WVB, instead of IO.WLB, when
writing to a terminal.
If the write actually goes to a terminal, the
Executive converts your IO.WVB into IO.WLB.
However, if the LUN has
been
redirected
to
some
inappropriate device -- a disk,
for
example -- using an IO.WVB will be rejected because a file is not open
on the LUN.
This prevents privileged tasks from overwriting block
zero of the disk (the boot block).
Note that any subfunction bits specified in the IO.WVB request
(for
example, TF.CCO,
TF.WAL, or TF.WBT) are stripped off when the QIO is
converted to an IO.WLB.

3.10.7

Remote DHll and DZll Lines

All remote DHll lines in a system are answered at the same baud
rate.
All
remote DZll lines are also answered at the same rate, which may
differ from the DHll rate.
These rates are specified at system
generation.
Before a remote DHll or DZll line is answered,
the driver clears
certain of the terminal characteristics (see Table 3-5) that may have
been set by an MCR SET command or by an SF.SMC
QIO.
The
characteristics cleared are:
TC.SCP,
TC.ESQ,
TC.HLD, TC.SMR, and
TC.TTP.
(Clearing TC.TTP means that a terminal type of "unknown"
is
returned to an SF.GMC request.) Also, buffer size is set to 73.

3-31

HALF-DUPLEX TERMINAL DRIVER
A DZll remote line must be declared to be remote before the terminal
driver will correctly handle the modem.
This is done with the MCR
command SET /REMOTE=TI:.
NOTE
Because of the few modem signals that
the
DZll
handles and
the lack of
interrupt support provided
for
those
signals,
the DZll may not adequately
handle telephone exchange requirements
in all countries.

3.10.8

High-Order Bit on Output

Setting the high-order bit of an output byte
transmitted but not interpreted by the driver.

3.10.9

causes

may

set

Side Effects of Setting Characteristics

Some of the characteristics that a task may set, or that you
from a terminal, have side effects that should be noted.
•

TC.HLD -- Unexpected behavior can result from a terminal
in
hold-screen mode if its reception rate is much greater than
its transmission rate.
(The DHll supports split baud
rates.)
In hold-screen mode the terminal
sends a CTRL/S during
reception of an output stream, when the screen is nearly full.
Output is resumed -- another screen-full -- when you type
SHIFT/SCROLL (the terminal generates CTRL/Q).
Thus, no output
is lost as a result of scrolling off the screen before you can
read it.
However, if the terminal's transmission rate is far
below its reception rate, some unread output may scroll out of
sight before the CTRL/S can be transmitted.
A related point to note is that some terminals and
interfaces
are hardware buffered.
This fact can cause obscure timing
problems for tasks that try to implement hold-screen mode.

•

3.10.10

TC.SMR -- If this characteristic
is asserted
(that is,
if
lower-/uppercase conversion
is disabled by, for example, SET
/LOWER=TI:),
the two characters 175(8)
and
176(8)
are
interpreted as
[
(right-brace) and
(tilde), respectively.
If TC.SMR is not asserted,
these two characters act as
Altmodes.
That is, they act as line terminators that do not
advance the cursor to a new line.
Altmodes are npt echoed.

Unsolicited-Input-Character ASTs for Tasks Attaching
Terminals

Several

For a task that attaches several terminals (for example, a
reentrant
language processor),
the handling of unsolicited
input requires
special care. When the terminal driver passes an unsolicited
input
character to a task, it does not pass any information about which of
several terminals generated the character.
The task must ascertain
this for itself.

3-32

HALF-DUPLEX TERMINAL DRIVER
One solution is for the task to name uniquely the AST entry points for
each attached terminal.
Each separate AST then identifies its
terminal before branching to a common routine that processes the
unsolicited character. For example:
ATTl:
ATT2:

UICl:
UIC2:

UIC:

3.10.11

QIO$C IO.ATA, ••• ,<UICl>
BR CONT
QIO$C IO.ATA, ••. ,<UIC2>
BR CONT

MOV #1,-(SP)
BR UIC
MOV #2 1 -(SP)
BR UIC

MOV (SP)+,INDEX

Direct Cursor Control

The terminal driver generally examines the output stream in order to
keep track of the cursor's horizontal position (so that output can be
wrapped around or discarded).
Therefore, tasks that want to use
direct cursor control should use IO.WALs. This prevents the terminal
driver from inserting CR/LFs (that the task considers spurious)
into
the output stream. FORTRAN WRITE statements become IO.WVBs, which are
interpreted by the driver. To prevent this, a FORTRAN task can use
the CALL QIO routine or can issue carriage returns at frequent
intervals (to make the driver think the cursor is always well to the
left of the rightmost column, and therefore no CR/LFs need be emitted
to keep the cursor on the screen) •

3.10.12

DLll Receiver Interrupt Enable

For hardware reasons, a DLll is susceptible to losing receiver
interrupt enable in its Receiver Status Register. The disabling of
the receiver interrupt bit causes the terminal to print output
requests but not to respond to input (for example, the terminal does
not echo input characters). The terminal driver has no mechanism for
recogn1z1ng the disabling.
Therefore, it cannot recover. The bit
must be reset with an MCR OPEN command, the console switch register,
or a periodically rescheduled task.

3.10.13

Loadable Driver Restrictions

Checkpointing during terminal input, variable-length terminal buffer
support,
and
escape sequence support require the presence of
conditionally assembled Executive support.
If a loadable terminal
driver supports one of these features and the Executive does not (or
vice versa) , the best that can happen is an undefined global when the
terminal driver is built. At worst, the system is corrupted.

3-33

CHAPTER 4
VIRTUAL TERMINAL DRIVER

4.1

INTRODUCTION

The virtual terminal driver supports offspring task use of virtual
terminals in RSX-llM-PLUS systems. Virtual terminals are not physical
hardware devices; they are actually implemented in software through
the use of data structures created by the RSX-llM-PLUS Executive.
Virtual terminals are created by the Executive when requested by
parent tasks with the Create Virtual Terminal directive. Virtual
terminals are useful in batch processing and other
processing
environments in providing noninteractive terminal I/O support for
offspring tasks, eliminating the need for operator intervention.
Offspring task(s) "spawned" by or "connected" to the parent task that
created the virtual terminal can perform terminal I/O operations with
the virtual terminal in the same manner as with physical terminals.
Virtual terminals differ from physical terminals in that they receive
input from or output to a program (the parent task), rather than from
a keyboard or to a display (or printer), respectively.

4.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word) contains the following
information for virtual terminals. A setting of 1 indicates that the
described characteristic is true for virtual terminals.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported

Meaning

4-1

VIRTUAL TERMINAL DRIVER
Bit

Setting

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Words 3 and 4 are undefined. Word 5 specifies the maximum byte count
(that is, maximum buffer size) to which offspring requests will be
truncated; this value is specified by the parent task in the Create
Virtual Terminal system directive, as described in the RSX-llM/M-PLUS
Executive Reference Manual.

4.3

QIO MACRO

Table 4-1 lists the standard and device-specific functions of the
macro that are valid for virtual terminals.

QIO

Table 4-1
Standard and Device-Specific QIO Functions for Virtual Terminals
Format

Function

STANDARD FUNCTIONS:
QI 0 $C IO • ATT , •••

Attach device

QI0$C IO. DET, •••

Detach device

QIO$C IO. KIL, •••

Cancel I/O request

QIO$C IO.RLB, ••• ,<stadd,size>

Read logical block

QIO$C IO.RVB, ••• ,<stadd,size>

Read virtual block
( e ff e c ts I 0 • R LB )

QIO$C IO.WLB, ••• ,<stadd,size,stat>

Write logical block

QIO$C IO.WVB, ••• ,<stadd,size,stat>

Write virtual block
(effects IO.WLB)
(continued on next page)

4-2

VIRTUAL TERMINAL DRIVER
Table 4-1
(Cont.)
Standard and Device-Specific QIO Functions for Virtual Terminals
Function

Format
DEVICE-SPECIFIC FUNCTIONS:
QIO$C IO.STC, •.• ,<cb,sw2,swl>

Set terminal characteristics
(enable/disable intermediate
I/O buffering, or return I/O
status
to
completion
offspring task)

QIO$C SF.GMC, ••• ,<stadd,size>

Get multiple characteristics

I Get terminal support

I QIO$C IO.GTS, ••• ,<stadd,size>

I QIO$C IO.RPR, ••• ,<stadd,size,[tmo], I Read logical block
after prompt

pradd,prsize,vfc>

Set multiple characteristics

QIO$C SF.SMC, ••• ,<stadd,size>
size

The size of the data buffer in bytes (must be greater than 0).
The buffer must be located within the addressing space of the
parent or offspring task issuing the I/O request.
stadd
The starting address of the data buffer.
The
word aligned for SF.GMC, IO.GTS, and SF.SMC;
be aligned on a byte boundary~

address must be
otherwise, it may

stat
The I/O completion status code, specified by the parent task,
that is issued by the virtual terminal driver in response to an
offspring task's read request upon successful completion.
cb

Characteristic bits to become
virtual terminal functions:

set,

selecting

th~

following

cb Value

Bits Set

Function

none

Enable
intermediate
buffering in the Executive
pool

Return
the
specified
virtual
terminal
I/O
completion status to the
requesting offspring task

Disable
buffering

0 and 1

for
Return
status
offspring write request

4-3

intermediate

VIRTUAL TERMINAL DRIVER
swl
The I/O completion code for I/O completion status.
NOTE
The sw2 and swl parameters are valid in
the IO.STC function only when cb=l or
cb=3.
tmo
An optional time-out count (see below).
vfc
A character for vertical format control.

See Table 3-11.

pr add
The starting address of the prompt buffer.
prsize
The size of the prompt buffer in bytes.
The buffer must be
located within the address space of the offspring task issuing
the I/O request.

4.3.1

Standard QIO Functions

4.3.1.1 IO.ATT - This I/O function can be issued by offspring task
tasks to attach the virtual terminal.
(It is illegal for parent tasks
to issue IO.ATT).
Attaching a virtual terminal prevents other
offspring tasks from executing I/O operations with the virtual
terminal. However, parent task I/O requests are always serviced when
issued.

4.3.1.2 IO.DET - This I/O function can be issued by offspring tasks
to detach the virtual terminal, making it available for use by other
offspring tasks connected to the same parent task.
(It is illegal for
parent tasks to issue IO.DET.)

4.3.1.3 IO.KIL - Parent and offspring tasks can issue IO.KIL to
cancel I/O requests. An offspring task issuing IO.KIL can result in
IE.ABO being returned to the parent task.

4.3.1.4 IO.RLB, IO.RVB, IO.WLB, IO.WVB - These
read
and
write
functions execute requested I/O operations with virtual terminals in
the same manner as with terminals described in Chapter 2, except as
follows:
1.

The virtual terminal driver returns the tmo parameter of an
offspring task's IO.RLB or IO.RVB request, or the vfc
parameter of an offspring task's IO.WLB or IO.WVB request as
a stack parameter on entry to the appropriate AST for the
parent task.
4-4

VIRTUAL TERMINAL DRIVER
2.

4.3.2

The virtual terminal driver returns I/O completion status to
the offspring task in response to successful completion of
the offspring task's IO.RLB -0r IO.RVB request; however,
the
actual
I/O completion status values returned are specified
for data transfers in the third parameter word of the parent
task's
IO.WLB or IO.WVB response, or in the second and third
parameters of the parent task's IO.STC function response when
no data transfer is desired.

Device-Specific QIO Function (IO.STC)

The IO.STC function can be issued by parent tasks to enable/disable
offspring task I/O buffering
in secondary pool, or to force an
appropriate I/O completion status for an offspring task read
I/O
request when no data transfer is desired.
Both of these applications
for the IO.STC function are described as follows.
Parent tasks can use
IO.STC to enable
(or disable)
intermediate
buffering in secondary pool.
Intermediate buffering, when enabled, is
performed on offspring task virtual terminal read and write requests
when the offspring task is checkpointable.
Thus, offspring tasks can be stopped for virtual terminal
I/O and
checkpointed
in a manner similar to that when physical terminals are
used.
Whenever the virtual
terminal
driver
determines
that
intermediate buffering should not be used, offspring tasks that issue
terminal requests become locked
in memory until
I/O completion;
transfers occur directly between parent task and offspring task
buffers without intermediate buffering in secondary pool.
In addition to the conditions that permit intermediate buffering (when
specified), one condition can automatically disable intermediate
buffering of the parent task.
If the buffer size specified
in the
Create Virtual Terminal directive exceeds the maximum size specified
at system generation time (512(10) maximum), intermediate buffering is
disabled.
The second application for IO.STC is to allow the virtual terminal
driver to return an appropriate I/O completion status in response to
an offspring task read request.
I/O status returned
in this manner
allows successful completion of the offspring task's request when the
parent task determines that no data transfer
is desired;
this
condition can occur, for example, when no data is available for input
to the offspring task by the virtual terminal driver.
When used
in
this manner,
the
IO.STC function must include three parameters,
<cb,sw2,swl>, as follows:
cb
A value of 1 is specified to indicate that the
status return to the offspring task is desired.

I/O

completion

NOTE
If the virtual terminal is operating in full duplex mode,
a cb value of l
returns status for an offspring read
request, and a cb value of 3 returns status for an
offspring write request.

4-5

VIRTUAL TERMINAL DRIVER
sw2
This parameter is the second word returned in the I/O completion
status indicating the number of bytes read upon successful
completion of an offspring task's read request.
However, since
no data transfer actually occurs, the value specified is O; the
byte count of 0 specified in this function is legal
(and
desired), whereas a byte count of 0 in write operations is
illegal (and will result in an error being returned to the parent
task) •
sw2
This parameter specifies the status code to be returned to the
offspring task by the virtual terminal driver in the first word
of the I/O completion status. This value is returned in the high
byte and a value of +l is returned in the low byte of the status
word. Typical values and the status that each represent are
listed as follows:

4.3.3

Code

Value

Completion Status Indicated

IS. sue

Successful completion

IS.CR

Read terminated by carriage
return

IS. ESC

Read terminated by an Altmode

IS. ESQ

233

Read terminated by an escape
sequence

SF.GMC

The Get Multiple Characteristics function returns information on
terminal characteristics.
This function can be issued by both the
parent and the offspring tasks. The virtual terminal driver returns
the characteristics that were set by the previous corresponding SF.SMC
request. However, only the full duplex mode (TC.FOX) characteristic
affects the operation of the virtual terminal driver. The SF.GMC
function is provided only to maintain transparency to the offspring
task.
Valid virtual terminal characteristics are listed in Table 4-2.

4• 3• 4

IO. GTS

The Get Terminal Support function returns a 4-word buffer
of
information specifying which features are a part of the virtual
terminal driver. The virtual terminal driver provides the IO.GTS
function only to maintain transparency to the offspring task. Table
2-7 lists the options returned by the full duplex terminal driver. Of
those listed, the virtual terminal driver returns the following:
Word 1

Fl.BUF, Fl.RPR, Fl.UTB, and Fl.VBF

Word 2

F2.SCH and F2.GCH

4-6

VIRTUAL TERMINAL DRIVER
4.3.5

IO.RPR

The Read After Prompt (IO.RPR) function can be issued only by the
offspring task.
When the offspring task issues this function, the
function appears to the parent task as a separate write request
followed by a read request. This function is described in Chapter 3.

4.3.6

SF.SMC

The SF.SMC function allows a task to set and reset the characteristics
of a terminal. Both the parent and the offspring tasks may issue this
function. The parent task may set virtual terminals to full duplex
operation by using the SF.SMC function with the characteristics bit
TC.FOX. When in full duplex mode, the virtual terminal driver
attempts to process the offspring task's read and write requests
simultaneously.
In order to insure that these operations
are
overlapped, the parent task should minimize the amount of time it
spends in AST state.
The virtual terminal driver defaults to half duplex mode.
Table 4-2 lists the characteristics that
offspring task may set.

either

the

parent

the

Table 4-2
Virtual Terminal Characteristics
Bit Name

Octal
Value

Meaning (If Asserted)

TC.FOX

Full duplex mode

TC.SCP

Terminal is a scope

TC.SMR

Uppercase conversion
disabled

TC.TTP

Terminal type

4.4

Default Value

STATUS RETURNS

The error and status conditions listed in Tables 4-3 and 4-4 are
returned by the virtual terminal driver described in this chapter.
The SE.NIH error is returned by the SF.GMC and SF.SMC functions.
For
this error, the low byte of the first word in the I/O status block
contains IE.ABO. The second word in the I/O status block contains an
offset (starting at 0) pointing to the erroneous byte in the stadd
buffer.

4-7

VIRTUAL TERMINAL DRIVER

Virtual Terminal Status

Table 4-3
for Offspring Task Requests

~eturns

Code

Reason
Successful completion of an offspring task read
request results in an I/O completion status specified
in a parent task QIO parameter being returned.
Typically, the status information returned simulates
a subset of I/O returns normally produced by the
terminal drivers described in Chapter 2.

rs.sue

Successful completion
The operation specified in the QIO directive was
completed successfully.
The second word of the I/O
status block
indicates
the
number
of
bytes
transferred on a write operation.

IE.IFC

Invalid function code
The offspring task attempted a read or a write
function and the parent task did not specify an AST
address in its response to the
requested
I/O
function, or the offspring task issued an IO.STC or
other invalid function.

IE.ABO

Request terminated
The offspring task issued IO.KIL or the
eliminated the virtual terminal unit.

IE.SPC

parent

task

Illegal address space
Part or all of the buffer specified for a read or
write request was outside of the task's address
space, or a byte count of 0 was specified.

IE.UPN

Insufficient dynamic storage
The driver could not allocate an AST block to notify
the parent task of an offspring task request, or the
driver could not allocate an intermediate buffer in
the Executive pool.

SE.NIH

A terminal characteristic other than those in Table
4-2 was specified, or an offspring task attempted to
assert TC.FDX.

4-8

VIRTUAL TERMINAL DRIVER

Table 4-4
Virtual Terminal Status Returns for Parent Task Requests
Code

rs.sue

Reason
Successful completion
The operation specified in the QIO directive was
completed successfully.
The second word of the I/O
status block
indicates
the
number
of
bytes
transferred on a read or write operation.

IE.EOF

End of file encountered
The IO.STC function was completed successfully.

IE.BAD

Bad parameters
The parent task specified a buffer size that exceeded
the system maximum specified at system generation
time.

IE.DUN

Device not attachable
An IO.ATT or IO.DET function was issued by the parent
task.

IE.IFC

Invalid function code
A read, write, or IO.STC function was issued without
a pending offspring task request. This status can
occur if the offspring task cancels a pending read or
write request.
This function code is also returned
when IO.STC is issued
to
enable
intermediate
buffering on a virtual terminal unit whose buffer
size, specified in the Create Virtual
Terminal
directive, exceeds the system maximum specified at
system generation time.

SE.NIH

A terminal characteristic other than those in Table
4-2 was specified in an SF.GMC or SF.SMC request.

4-9

CHAPTER 5

DISK DRIVERS

5.1

INTRODUCTION

The RSX-llM disk drivers support the disks summarized in Table
Subsequent sections describe these devices in greater detail.

5-1.

All of the disks described in this chapter are accessed in essentially
the same manner.
Up to eight disks of each type (except RXOl, RX02,
RX50, RD51, RC25, RLOl, RL02, RA60, RASO, or RA81) may be connected to
their respective controllers. Disks and other file-structured media
are divided logically into series of 256-word blocks.

5.1.1

RFll/RSll Fixed-Head Disk

The RFll controller/RSll fixed-head disk provides random access bulk
storage.
It features fast track-switching time and a redundant set of
timing tracks.

5.1.2

RS03 Fixed-Head Disk

The RS03 (RH11-RH70 controller/RS03 fixed-head disk) is a fixed-head
disk that offers speed and efficiency. With 64 tracks per platter and
recording on one surface, the RS03 has a capacity of 262,144 words.

5.1.3

RS04 Fixed-Head Disk

The RS04 (RH11-RH70 controller/RS04 fixed-head disk) is similar to the
RS03 disk and interfaces to the same controller, but provides twice
the number of words per track by recording on both surfaces of the
platter, and thus has twice the capacity.

5.1.4

RP11/RP02 or RP03 Pack Disks

The RPll controller/RP02 or RP03 pack disk consists of 20 data
surfaces and a moving read/write head.
The RP03 has twice as many
cylinders, and thus double the capacity of the RP02.
Only an even
number of words can be transferred in a read/write operation.

5-1

April 1983

DISK DRIVERS
Table 5-1
Standard Disk Devices
Controller/
Drive

RPM

Secs

Tr ks

Cy ls

Bytes/
Drive

Decimal
Blocks

RFll/RSll

1800

128

524,288

1024

RHXX/RS03

3600

641

524,288

1024

RHXX/RS04

3600

641

1,048,576

2048

RP11E/RPR02

2400

200

20,480,000

40,000

RP11C/RP03

2400

400

40,960,000

80,000

RHXX/RM02

2400

823

67,420,160

131,680

RHXX/RM03

3600

823

67,420,160

131,680

RH70/RM05

3600

823

256,196,608

500,384

RH11/RP04,RP05 3600

411

87,960,576

171,798

RH70/RP06

3600

815

174,423,040

340,670

RH70/RP07

3600

6302

516,096,000 1,008,000

RH70/RM80

3600

5592

124,214,272

242,606

RK11/RK05

1500

200

2,457,600

4800

RLll/RLOl

2400

403

256

5,242,880

10,240

RL11/RL02

2'400

403

512

10,485,760

20,480

RK611/RK06

2400

411

13,888,512

27,126

815

27,810,800

53,790

I
I

RK611/RK07

2400

RXll/RXOl

360

264

256,256

494

RX211/RX02

360

264

512,512

988

UDA50/RA80

3600

546

121,325,568

236,964

\ 3600

1248

456,228,864

891,072

3600

2382

204, 890, 112

400,176

I RC25

2850

..).L.

796

26,061,824

50,902

RD51

3600

306

10,027,008

19,584

I RXSO

300

J 80

409,600

800

words

I UDAS 0 /RA8 l
l UDA50/RA60
I

1. The RS03 has
words/sector.

per

sector;

the

RS04

has

128

2. The RPO? and the RM80 each have two additional CE cylinders.
3. The RLOl and RL02 each have 128 words per sector.
4. The RXOl has 64 words per sector; the RX02 has 128 words per
sector.
5-2

April 1983

DISK DRIVERS
5.1.5

RM02/RM03/RM05/RM80 Pack Disk

The RM02/RM03, RM05, and RM80 are MASSBUS disk drives and adapters
that use the existing MASSBUS controller. With a single head per
surface, they provide a 1.2 megabyte-per-second data transfer rate.
The RM03, RM05, and RM80 are used with the RH70 controller on
PDP-11/70 systems. All other systems use the RM02 with the RHll
controller.

5.1.6

RP04, RPOS, RP06 Pack Disks

The RP04 or RP05 {RH11-RH70 controller/RP04 or RP05 pack disk)
pack
disks consist of 19 data surfaces and a moving read/write head. Both
offer large storage capacity with rapid access time.
The RP06 pack
disk has approximately twice the capacity of the RP04 or RP05. The
RP07 fixed-media disk has approximately 3 times the capacity of the
RP06.

5.1.7

RKll/RKOS or RKOSF Cartridge Disks

The RKll controller/RK05 DECpack cartridge disk is an economical
storage
system
for medium-volume, random access storage.
The
removable disk cartridge offers the flexibility of large off-line
capacity with rapid transfers of files between on- and off-line units
without necessitating copying operations. The RK05F has twice the
storage capacity of the RK05 and has a fixed {nonremovable) disk
cartridge.

5.1.8

RLll/RLOl or RL02 Cartridge Disk

The RLOl is a low-cost, single-head per surface disk with a burst data
transfer rate of 512 kilobytes per second. The storage capacity of
the RL02 is twice that of the RLOl.

5.1.9

RK611/RK06 or RK07 Cartridge Disk

The RK611 controller/RK06 cartridge disk is a removable, random
access, bulk-storage system with three data surfaces. The storage
capacity is 6,944,256 words per pack. The system, expandable to eight
drives, is suitable for medium to large systems.
The RK611 controller/RK07 cartridge disk is generally similar to the
RK611/RK06, except storage capacity is increased to approximately
13,905,400 words per pack. Both RK06 and RK07 disks can use the same
RK611 controller;
mixing RK06 and RK07 disks on the same controller
is permitted.

5-3

April 1983

DISK DRIVERS
5.1.10

RXll/RXOl Flexible Disk

The RXll controller/RXOl flexible disk is an economical storage system
for low-volume,
random access storage. Data is stored in twenty-six
64-word sectors per track;
there are 77 tracks per disk. Data may be
accessed by physical sector or logical block.
If logical or virtual
block I/O is selected, the driver reads four physical sectors.
These
sectors are interleaved to optimize data transfer. The next logical
sector that falls on a new track is skewed by six sectors to allow for
track-to-track
switch
time.
Physical
block I/O provides no
interleaving or skewing and provides access to all 2002 sectors on the
disk.
Logical or virtual I/O starts on track 1 and provides access to
494 logical blocks.

5.1.11

RX211/RX02 Flexible Disk

The RX211 controller/RX02 flexible disk is an economical storage
system for low-volume,
random access storage.
It is capable of
operating in either an industry-standard, single-density mode
(as
stated for the RXll/RXOl flexible disk), or a double-density mode (not
industry standard).
In the single-density mode, each drive can store
data exactly as stated in Section 5.1.10.
In the double-density mode,
data is stored in twenty-six 128-word sectors per track;
there are 77
tracks per disk.
The RX211/RX02 operating in the single-density mode
can read disks written by an RXll/RXOl flexible disk system.
In
addition,
disks
written
by
the RX211/RX02 operating in the
single-density mode can be read by the RXll/RXOl flexible disk system.

5.1.12

ML-11 Disk Emulator

The ML-11 is a fast, random access, block-mode MOS memory system. The
RSX-llM and RSX-llM-PLUS operating systems treat the ML-11 as a disk.
However, since it is not a disk, the statistics in Table 5-1 do not
apply.
Unlike a disk,
the number of bytes per drive varies.
One
ML-11 provides from 512 blocks to 8192 blocks of storage.

5.1.13

UDASO/RA60/RA80/RA81 Disks

The ODA controller is an intelligent disk controller, which contains a
high-speed microprogrammed processor capable of performing all disk
functions, including data handling, error detection and correction,
and optimization of disk drive activity and data transfers.
The types
of drives that can be connected to the UDA50 controllers are the RA60
disk drive, which has a removable pack, and the RASO and RA81, both of
which are fixed media drives.
(For data capacities and rates, see
Table 5-1.)
Up to four of these drives can be connected to a ODA, in
any desired combination.
The ODA controller also has two addressable registers in the I/O page
that are used for the initialization sequence and to initiate polling
of command packet buffers in memory.
In addition, this controller is
also capable of carrying out an extensive self-test on power-up or
initialization.

5-4

April 1983

DISK DRIVERS
5.1.14

RC25 Disk Subsystem

The RC25 Subsystem combines, in one package, a controller and a single
disk drive that has a removable disk and a fixed disk.
These disks
reside in the drive as two separate logical units on a single spindle.
Their size is the same.
Both are single eight-inch disks with two
surfaces, and both disks have the same
data
capacity.
But
mechanically they are different:
One is a removable front-loading
cartridge disk, while the other cannot be removed from the drive.
The
drive is designed with loadable Winchester type heads.
An additional disk drive can be added to the RC25 Disk Subsystem,
providing a dual spindle configuration with two fixed and two
removable disks.
The added-on disk drive is a slave to the disk
subsystem that has the controller.

5elel5

RD51 Fixed 5.25 Disk/RX50 Flexible 5.25 Disk

This subsystem is designed to serve a hard(RD)/flexible(RX)
disk
combination that can be used as a mass storage medium for small
systems.
The basic configuration for this mass storage scheme is an
RD51 fixed disk drive and an RX50 flexible dual disk drive.
In this
configuration, the RD51 is the system device and the RX50 is used as a
data device and/or as a backup.
The RX50 dual disk is addressed as
two separate units resulting in a basic configuration of three disk
units.
Also, another RD51 can be added to increase storage capacity.
Some of the characteristics of the RD/RX drives are given in Table 5-1
and in the following paragraphs.
The RD51 disk drive is a 5.25 inch fixed disk with Winchester type
heads.
It has two disks with four data surfaces.
The RD51 is soft
sectored and field formattable.
The headers for each sector contain
the sector's cylinder number,
head number, and sector number.
The
sector number is the logical sector number (0-15)
that reflects the
sector interleave of the disk.
The RX50 dual diskette drive is a compact mass storage drive with two
access slots.
Each slot can hold a single-sided 5.25 flexible disk.
These diskettes are firm sectored and are not field formattable.
Every track has sectors numbered from 1 to 10.
The two diskettes
share the same head transport mechanism.

5.2

GET LON INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for disks.
A bit setting of 1 indicates that the
described characteristic is true for disks.

5-4.1

April 1983

DISK DRIVERS
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported (device
dependent)

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo-device

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Words 3 and 4 of the buffer contain the maximum logical block number.
Note that the high byte of U.CW2 is undefined. The user should clear
the high byte in the buffer before using the block number.
For the
RASO disk, these two words are undefined until the device has been
accessed at least once. Word 5 indicates the default buffer size,
which is 512 bytes for all disks.

5. 3

QIO MACRO

This section summarizes the
functions for disk drivers.

5.3.1

standard,

and

device-specific

QIO

Standard QIO Functions

Table 5-2 lists the standard functions of the QIO macro that are valid
for disks.

5-5

DISK DRIVERS
Table 5-2
Standard QIO Functions for Disks
Format

Function

QIO$C IO. ATT, •••

Attach devicel

QIO$C IO. DET, •••

Detach device

QIO$C IO.KIL, •••

Kill I/02

QIO$C IO.RLB, ••• ,<stadd,size,,blkh,blkl>

READ logical block

QIO$C IO.RVB, ••• ,<stadd,size,,blkh,blkl>

READ virtual block

QIO$C IO.WLB, ••• ,<stadd,size,,blkh,blkl>

WRITE logical block

QIO$C IO.WLC, ••• ,<stadd,size,,blkh,blkl>

WRITE logical block
followed by write
check3

QIO$C IO.WVB, ••• ,<stadd,size,,blkh,blkl>

WRITE virtual block

1. In RSX-llM systems, only unmounted volumes may be attached;
in RSX-llM-PLUS systems, only volumes mounted foreign may be
attached. Any other attempt to attach a mounted volume will
result in an IE.PRI status being returned in the I/O status
doubleword.
2. In-progress disk operations are allowed to complete when
IO.KIL is received, because they take such a short time. I/O
requests that are queued when IO.KIL is received are killed
immediately.
An IE.ABO status is returned in the I/O status
doubleword.
3. Not supported on RXOl or RX02 flexible disks.
stadd
The starting address of the
boundary) •

data

buffer

(must

word

size
The data buffer size in bytes (must be even, greater than O, and,
for the RP02 and RP03, also a multiple of four byte·s~.
blkh/blkl
Block high and block low, combining to form a double-precision
number that indicates the actual logical/virtual block address on
the disk where the transfer starts; blkh represents the high 8
bits of the address, and blki the low 16 bits.

5-6

DISK DRIVERS
IO.RVB and
IO.WVB are associated with file operations
(see the
IAS/RSX-11 I/O Operations Reference Manual).
For these functions to
be executed,~a-file must be open on the specified LUN if the volume
associated with the LUN is mounted.
Otherwise, the virtual I/O
request is converted to a logical
I/O request using the specified
block numbers.
NOTE
When writing a new file using QIOs,
the
task must explicitly issue .EXTND File
Control System library routine calls as
necessary to reserve enough blocks for
the file, or the file must be initially
created with enough blocks allocated for
the file.
In addition,
the task must
put an appropriate value in the FDB for
the end-of-file block number
(F.EFBK)
before closing the file.
(Refer to the
.EXTND routine
description
in
the
IAS/RSX-11
I/O
Operations Reference
Manual.)
~Each disk driver supports the subfunction bit IQ.X:
inhibit retry
attempts for error recovery.
The subfunction bit is used by ORing it
into the desired QIO;
for example:
QIO$C IO.WLB!IQ.X, ••• ,<stadd,size,,blkh,blkl>
The IQ.X subfunction permits user-specified
retry
applications in which data reliability must be high.

algorithms

for

The overlapped seek drivers for RSX-llM-PLUS support subfunction bit
IQ.Q:
queue the request immediately without doing a seek (that is,
use implied seeks).

5.3.2

Device-Specific QIO Functions

The device-specific functions of the QIO macro are valid for the
only;
they are shown in Table 5-3.

RXOl

Table 5-3
Device-Specific Functions for the
RX01,RX02, RLOl, and RL02 Disk Drivers
Function

Format

QIO$C IO.RPB, ••• ,<stadd,size,,,pbn> Read physical block
QIO$C IO.SEC, •••

Sense diskette characteristics
(RX02 only)

QIO$C IO.SMD, ••• ,<density,,>

SET media density (RX02 only)

QIO$C IO.WDD, ••• ,<stadd,size,,,pbn> Write physical block (with deleted
data mark) (RXOl and RX02 only)
QIO$C IO.WPB, ••• ,<stadd,size,,,pbn> Write physical block

5-7

DISK DRIVERS
stadd
The starting address of the
boundary).

data

buffer

(must

word

size
The data buffer size in bytes must be even and greater than 0).
pbn
The physical block number
validation will occur).

where

the

transfer

starts

(no

density
The media density as follows:
0
2

5.3.3

single (RXOl-compatible) density
double density

Device-Specific QIO Function for the RASO

The RA80 driver supports the device-specific
Table 5-4.

QIO

function

shown

Table 5-4
Device-Specific QIO Function for the RA80 Disk Driver
Format

Function

QIO$C IO.RLC, ••• ,<stadd,size,,blkh,blkl>

Read Logical with Read Check
modifier

5.4

STATUS RETURNS

The error and status conditions listed in Table 5-5
the disk drivers described in this chapter.

are

returned

Table 5-5
Disk Status Returns
Code

rs. sue

Reason
Successful completion
The operation specified in the QIO directive was
The second word of the I/O
status block can be examined to determine the
number
of
bytes processed,
i f the operation
involved reading or writing.

I completed successfully.

(continued on next page)

5-8

DISK DRIVERS
Table 5-5
(Cont.)
Disk Status Returns
Code
IS.PND

Reason
I/O request pending
The operation specified in the QIO d_irective has
not yet been executed.
The I/O status block is
filled with Os.

IS.ROD

Deleted data mark read
A deleted record was encountered while executing an
IO.RPB function.
The second word of the I/O status
block can be examined to determine the number of
bytes processed (RXOl and RX02 only) •

IE.ABO

Request aborted
An I/O request was queued (not yet acted
the driver) when an IO.KIL was issued.

IE.ALN

upon

File already open
The task attempted to open a file on the physical
device unit associated with specified LUN, but a
file has already been opened by the issuing task on
that LUN.

IE.BLK

Illegal block number
An illegal logical block number was specified.
This code would be returned, for example, if block
4800 were specified for an RK05 disk, on which
legal block numbers extend
from 0 through 4799.
IE.BLK would also be returned
if an attempt was
made to write on the last track of an RK06 disk.
(See Section 5.5.)

IE.BBE

Bad block error
The disk sector (block) being read was marked as
bad block in the header word.

IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a buffer, but only
word alignment is legal for disk.
Alternatively,
the length of a buffer is not an appropriate number
of bytes.
For example, all
RP03 and RP02 disk
transfers must be multiples of four bytes.

IE.DNR

Device not ready
The physical device unit specified
in the QIO
directive was not ready to perform the desired I/O
operation.
(continued on next page)

5-9

DISK DRIVERS
Table 5-5 (Cont.)
Disk Status Returns
Reason

Code
IE.FHE

Fatal hardware error
The controller is physically unable to reach the
location where input/output operation is to be
performed. The operation cannot be completed.

IE. IFC

Illegal function
A function code was specified
that is illegal for disks.

IE.NLN

I/O

request

File not open
The task attempted to close a file on the physical
device unit associated with the specified LUN, but
no file was currently open on that LUN.

IE. NOD

Insufficient buffer space
Dynamic storage space has been depleted, and there
was insufficient buffer space available to allocate
a secondary control block. For example, if a task
attempts to open a file, buffer space for the
window and file control block must be supplied by
the Executive. This code is returned when there is
not enough space for this operation.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE. OVR

Illegal read overlay request
A read overlay was requested, and the physical
device unit specified in the QIO directive was not
the physical device unit from which the task was
installed.
The read overlay function can only be
executed on the physical device unit from which the
task image containing the overlays was installed.

IE. PR!

Privilege violation
The task that issued the request was not privileged
execute that request. For disk, this code is
returned if a nonprivileged task attempts to read
or write a mounted volume directly (that is, using
IO.RLB or IO.WLB). Also, this code is returned if
any task attempts to attach a mounted volume.

I to

(continued on next page)

5-10

1·

DISK DRIVERS
Table 5-5
(Cont.)
Disk Status Returns
Reason

Code
IE.SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task.
Alternately, a byte count of
0 was specified.

IE.VER

Unrecoverable error
After the system's standard number of retries has
been attempted upon encountering an error, the
I operation
still could not be completed.
For disk,
I unrecoverable errors are usually parity errors.

IE.WCK

Write check error
An error was detected
I portion of an operation.

IE.WLK

during

the

write

check

Write-locked device
The task attempted to write
write-locked.

disk

that

was

When a disk I/O error condition is detected, an error is usually not
returned immediately.
Instead, RSX-llM attempts to recover from most
errors by retrying the function as many as eight times.
Unrecoverable
errors are generally parity, timing, or other errors caused by a
hardware malfunction.

5.5

PROGRAMMING HINTS

For the RK611 controller/RK06 or RK07 disk, the RLll controller/RLOl
or RL02 disk, RM02 disk, RM03 disk, RM05 disk, RM80 disk, and RP07
disk, the driver write-protects the last track of the cartridge.
This
track contains the factory-recorded bad-sector file.

5-11

CHAPTER 6
DECTAPE DRIVER

6.1

INTRODUCTION

The RSX-llM DECtape driver supports the TCll-G dual DECtape controller
with up to three additional dual DECtape transports.
The TCll-G is a
dual-unit, bidirectional, magnetic-tape transport system for auxiliary
data storage.
DECtape is formatted to store data at fixed positions
on the tape, rather than at unknown or variable positions as on
coventional magnetic tape.
The system uses redundant recording of the
mark, timing, and data tracks to
increase reliability.
Each reel
contains 578 logical blocks.
As with disk, each of these blocks can
be accessed separately, and each contains 256 words.

6.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled
by the Get LUN Information system
directive
(the first characterics word)
contains the following
information for DECtapes.
A bit setting of 1 indicates that the
described characteristic is true for DECtapes.
Meaning

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit addressing

Unit software write-locked

6-1

DECTAPE DRIVER
Bit

Setting

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Words 3 and 4 of the buffer contain the maximum LBN.
the default buffer size, 512 bytes, for DECtape.

6. 3

Word 5 indicates

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the DECtape driver.

6.3.1

Standard QIO Functions

Table 6-1 lists the standard functions of the QIO macro that are valid
for DECtape.
Table 6-1
Standard QIO Functions for DECtape
Format

Function

QIO$C IO.ATT, •••

Attach devicel

QIO$C IO.DET, •••

Detach device

QIO$C IO. KIL, •••

Kill I/02

I QIO$C IO.RLB, ••• ,<stadd,size,,,lbn>

READ logical block (forward)

QIO$C IO.RVB, ••• ,<stadd,size,,,lbn>

READ virtual block (forward)

QIO$C IO.WLB, ••• ,<stadd,size,,,lbn>

WRITE logical block (forward)

QIO$C IO.WVB, ••• ,<stadd,size,,,lbn>

WRITE virtual block {forward)

1. Only unmounted volumes may be attached. An attempt to attach a
mounted volume will result in an IE.PRI status being returned in the
I/O status doubleword.
2. In-progress DECtape operations are allowed to complete when
IO.KIL is received, unless the unit is not ready, because they take
such a short time.
I/O requests that are queued when IO.KIL is
received are killed. An IE.ABO status is returned in the I/O status
doubleword.

6-2

I
I
I
I
I

DECTAPE DRIVER
stadd
The starting address of the
boundary) •

data

buffer

{must

word

size
The data buffer size in bytes {must be even and greater than 0).
lbn
The logical block number on the DECtape where the transfer starts
(must be in the range 0-577).
IO.RVB and IO.WVB are associated with file operations
(see the
IAS/RSX-11 I/O Operations Reference Manual).
For these functions to
be executed,~a-file must be open on the specified LUN if the volume
associated with the LUN is mounted.
Otherwise, the virtual I/O
request is converted to a logical
I/O request using the specified
block numbers.

6.3.2

Device-Specific QIO Functions

The device-specific functions of the QIO
DECtape are shown in Table 6-2.

macro

that

are

valid

for

Table 6-2
Device-Specific Functions for DECtape
Format

Function

QIO$C IO.RLV, ••• ,<stadd,size,,,lbn>

READ logical block (reverse)

QIO$C IO.WLV, ••• ,<stadd,size,,,lbn>

WRITE logical block (reverse)

stadd
The starting address of the
boundary).

data

buffer

{must

word

size
The data buffer size in bytes {must be even and greater than 0).
lbn
The transfer starts (must be in the range 0-577).

6-3

DECTAPE DRIVER
6.4

STATUS RETURNS

The error and status conditions listed in Table 6-3
the DECtape driver described in this chapter.

are

returned

Table 6-3
DECtape Status Returns
Reason

Code

rs.sue

IS. PND

I/O request pending
The operation specified in the QIO directive has
not yet been executed.
The I/O status block is
filled with Os.

IE.ABO

Request aborted
An I/O request was queued (not yet acted
the driver) when an IO.KIL was issued.

IE.ALN

upon

File already open
The task attempted to open a file on the physical
device unit associated with the specified LUN, but
a file has already been opened by the issuing task
on that LUN.

IE.BLK

Illegal block number
An illegal logical block number was specified
DECtape.
The number exceeds 577 (1101 (8)).

IE. BYT

for

Byte-aligned buffer specified
Byte alignment was specified for a buffer, but only
word alignment is legal for DECtape. Alternately,
the length of the buffer is not an even number of
bytes.

I IE.DNR

Device not ready
The physical device unit specified in the QIO
directive was not ready to perform the desired I/O
operation.

IE. IFC

Illegal function
A function code was specified
that is illegal for DECtape.

I/O

request

(continued on next page)

6-4

DECTAPE DRIVER

Table 6-3
(Cont.)
DECtape Status Returns
Reason

Code
IE.NLN

File not open
The task attempted to close a file on the physical
device unit associated with the specified LUN, but
no file was currently open on that LUN.

IE.NOD

Insufficient buffer space
Dynamic storage space has been depleted, and

there

I was insufficient buffer space available to allocate
a secondary control block. For example, if a task
II attempts to open a file, buffer space for the
window and file control block must be supplied by
the Executive. This code is returned when there is
I not enough space for this operation.
IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE.OVR

Illegal read overlay request
A read overlay was requested and the physical
device unit specified in the QIO directive was not
the physical device unit from which the task was
installed.
The read overlay function can only be
executed on the physical device unit from which the
task image containin9 the overlays was installed.

IE. PRI

Privilege violation
The task that issued the request was not privileged
to execute that request. For DECtape, this code is
returned when a nonprivileged task attempts to read
or write a mounted volume directly (that is,
IO.RLB, IO.RLV, IO.WLB, or IO.WLV).
Also, this
code is returned if any task attempts to attach a
mounted volume.

IE. SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task. Alternately, a byte count of
O was specified.
(continued on next page)

6-5

DECTAPE DRIVER
Table 6-3 (Cont.)
DECtape Status Returns
Code

Reason

IE.VER

Unrecoverable error
After the system's standard number of retries has
been attempted upon encountering an error, the
operation still could not be completed.
For
DECtape, this code is returned to indicate any of
the following conditions.

IE.WLK

•

A parity error was encountered.

•

The task attempted a forward multiblock transfer
past block 577 (1101 (8)).

•

The task attempted
a
transfer past block O.

backward

multi block

Write-locked device
The task attempted to write on a DECtape unit
was physically write-locked.

6.4.1

that

DECtape Recovery Procedures

When a DECtape I/O error condition is detected, RSX-llM attempts to
recover from the condition by retrying the function as many as five
times. Unrecoverable errors are generally parity, mark track, or
other errors caused by a faulty recording medium or a hardware
malfunction. An unrecoverable error condition also occurs when a read
or write operation is performed past the last block of the DECtape on
a forward operation, or the first block of the DECtape on a reverse
operation.
In addition to the standard error conditions, an unrecoverable error
is reported when the "rock count" exceeds 8. The rock count is the
number of times the DECtape driver reverses the direction of the tape
while looking for a block number. Assume that the block numbers on a
portion of DECtape are 99, 96, and 101, where one bit was dropped from
block number 100, making it 96. If an I/O request is received for
block 100' and the tape is positioned at block 99, the driver starts
searching forward for block 100. The first block to be encountered is
96 and, because the driver is searching for block 100 in a forward
direction and 96 is less than 100, the search continues forward.
Block 101 is the next block and, because number 101 is greater than
100, the driver reverses the direction of the tape and starts to
search backwarde The next block number in this direction is 96, and
the direction is reversed again because 100 is greater than 96. To
prevent the DECtape from being hung in this position, continually
rocking between block numbers 96 and 100, a maximum rock count of 8
has been established.

DECTAPE DRIVER
6.4.2

Select Recovery

If the DECtape unit is in an off-line condition when the I/O function
is performed, the message shown below is output on the operator's
console.

*** DTn:

-- SELECT ERROR

where n is the unit number of the drive that is currently off line.
The user should respond by placing the unit to REMOTE.
The driver
retries the function, from the beginning, once every second.
It
displays the message once every 15 seconds until the appropriate
DECtape unit is selected. A select error may also occur when there
are two drives with the same unit number or when no drive has the

appropriate unit number.

6.5

PROGRAMMING HINTS

This
section
considerations
this chapter.

6.5.1

contains
information
on
important
programming
relevant to users of the DECtape driver described in

DECtape Transfers

If the transfer length on a write is less than 256 words, a partial
block is transferred with zero fill
for the rest of the physical
block.
If the transfer length on a read is less than 256 words, only
the number of words specified is transferred.
If the transfer length
is greater than 256 words, more than one physical
block
is
transferred.

6.5.2

Reverse Reading and Writing

The DECtape driver supports reverse reading and writing, because these
functions speed up data transfers in some cases. A block should
normally be read in the same direction in which it was written.
If a
block is ·read from a DECtape into memory in the opposite direction
from that in which it was written,
it is reversed
in memory
(for
example, word 255 becomes word 0, and 254 becomes word 1).
If this
occurs, the user must then reverse the data within memory.

6.5.3

Speed Considerations When Reversing Direction

It is possible to reverse direction at any time while reading or
writing DECtape.
However, the user should understand that reversing
direction substantially slows down the movement of the tape.
Because
DECtape must be moving at a certain minimum speed before reading or
writing can be performed, a tape block cannot be accessed
immediately
after reversing direction.
Two blocks must be bypassed before a read
or write function can be executed, to give the tape unit time to build
up to normal access speed.
Furthermore, when a request is issued to
read or write in a certain direction, the tape first begins to move in
that direction,
then starts detecting block numbers.
The following
examples illustrate these principles.

6-7

DECTAPE DRIVER

If a DECtape is positioned at block number 12 and the driver receives
a request to read block 10 forward, the tape starts to move forward,
in the direction requested. When block number 14 is encountered, the
driver reverses the direction of the tape, since 14 is greater than
10. The search continues backward, and block numbers 11 and 10 are
encountered.
Because the direction must be reversed and the driver
requires two blocks to build up sufficient speed for reading, block
number 9 and 8 are also bypassed in the backward direction. Then the
direction is reversed and the driver encounters blocks 8 and 9 forward
before reaching block number 10 and executing the read request.

6.5.4

Aborting a Task

If a task is aborted while waiting for a unit to be
DECtape driver recognizes this fact within 1 second.

6-8

selected,

the

CHAPTER 7
DECTAPE II DRIVER

7.1

INTRODUCTION

The DECTAPE II {TU58) driver supports TU58 system hardware,
low-cost, block-replaceable mass storage.

7.1.l

providing

TUS8 Hardware

Each TU58 DECTAPE II system consists of one or two TU58 cartridge
drives, one tape drive controller, and one DLll-type serial line
interface.
Each TU58 drive
functions
as
a
random
access,
block-formatted mass storage device. Each tape cartridge is capable
of storing 512(10) blocks of 512(10) bytes each. Access time averages
10 seconds.
All I/O transfers (commands and data) occur by means of
the serial line interface at serial transmission rates of 9600 bps.
All read and write check operations are performed by the controller
hardware using a 16-bit checksum. The controller performs up to eight
attempts to read a block, as necessary, before aborting the read
operation and returning a hard error; however, whenever more than one
read attempt is required for a successful read, the driver is notified
in order to report a soft error message to the error logger.

7.1.2

TU58 Driver

The TU58 driver communicates with the TU58 hardware by means of a
serial line interface (DLll); no other interface is required. All
data and command transfers between the PDP-11 system and the TU58 are
done with programmed I/O and interrupt-driven routines; NPRs are not
supported.

7.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive (the first characteristics word) contains the following
information for the TU58. A bit setting of 1 indicates that the
described characteristic is true for this device.

7-1

DECTAPE II DRIVER
Meaning

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 of the buffer are a double-precision number specifying
the total number of blocks on the device;
this value is 512(10)
blocks. Word 5 indicates the default buffer size, which is 512(10)
bytes.

7.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the TU58.

7.3.1

Standard QIO Functions

Table 7-1 lists the standard QIO system directive functions of the QIO
macro that are valid for the TU58.

7-2

DECTAPE II DRIVER
Table 7-1
Standard QIO Functions for the TU58
Function

Format

I
I

QIO$C

IO.ATT, •••

Attach device

QIO$C

IO.DET, •••

Detach device

QIO$C

IO. KIL, •••

Cancel I/O requestsl

QIO$C

IO.RLB, ••• ,<stadd,size,,,lbn>

READ logical block

QIO$C

IO.WLB, ••• ,<stadd,size,,,lbn>

WRITE logical block

1. In-progress operations are allowed to complete when IO.KIL
is received.
I/O requests that are queued when IO.KIL is
received are killed.
stadd
The starting address of the
boundary).

data

buffer

(must

word

size
Th~

data buffer size in bytes (must be even and greater than 0).

lbn
The logical block number on the cartridge tape where
transfer starts (must be in the range of 0-777).

the

data

The device-specific QIO system directive functions that are valid
the TU58 are shown in Table 7-2.

for

7.3.2

Device-Specific QIO Functions

Table 7-2
Device-Specific QIO Functions for the TU58
Format

Function

QIO$C IO.WLC, ••• ,<stadd,size,,,,lbn>

WRITE logical block with check

QIO$C IO.RLC, ••• ,<stadd,size,,,,lbn>

READ logical block with check

QIO$C IO.BLS!IQ.UMD, ••• ,<lbn>

POSITION tape

QIO$C IO.DGN!IQ.UMD,...

Run internal diagnostics

7-3

DECTAPE II DRIVER
stadd
The starting address of the
boundary) •

data

buffer

(must

word

size
The data buffer size in bytes (must be even and

grea~er

than 0).

lbn
The logical block number on the cartridge tape where
transfer starts (must be in the range of 0-777).
Additional details for device-specific QIO functions are
the following paragraphs.

the

provided

data

7.3.2.1 IO.WLC - The IO.WLC function writes the specified data onto
the tape cartridge.
A checksum verification is then performed by
reading the data just written; data is not returned to the task
issuing the function.
An appropriate status, based on the checksum
verification, is returned to the issuing task.

7.3.2.2 IO.RLC - The IO.RLC function reads the tape with an increased
threshold in the TUSB's data recovery circuit.
This is done as a
check to insure data read reliability.

7.3.2.3 IO.BLS - The IO.BLS function is used for diagnostic purposes
to position the tape to the specified logical block number.
If you
specify IO.BLS, you must use the IQ.UMD subfunction (see Chapter 1).

7.3.2.4 IO.DGN - The IO.DGN function is used for diagnostic purposes
to execute the TU58's internal (firmware) diagnostics. Appropriate
status information is returned to the issuing task by the I/O status
block.
If you specify IO.DGN, you must use the IQ.UMD subfunction
(see Chapter 1).

7.4

STATUS RETURNS

Table 7-3 lists the error and status conditions that are
the TU58 driver.

7-4

returned

DECTAPE II DRIVER
Table 7-3
TU58 Driver Status Returns

I Code
rs.sue

Reason
Successful completion
The operation specified in the QIO directive
was
completed successfully.
The second word of the I/O
status block can be examined to determine the number of
bytes processed,
if the operation involved reading or
writing.

IE.DNR

Device not ready
The physical device unit specified in the QIO directive
was not ready to perform the desired I/O operation.

IE.IFC

Illegal function

A function code was specified in an I/O request that

illegal for the TU58.
IE.FHE

Fatal hardware error

IE.TMO

Time-out error
The TU58 failed to respond to a
function
normal time specified by the driver.

IE.VER

within

the

Unrecoverable error
After the system's standard number of retries
(8)
has
been attempted upon encountering an error, the operation
still could not be successfully completed.

IE.WLK

Cartridge write-locked
The task attempted to write on a tape cartridge that
physically write-locked.

7-5

CHAPTER 8
MAGNETIC TAPE DRIVERS

8.1

INTRODUCTION

RSX-llM and RSX-llM-PLUS support a variety of magnetic tape devices.
Table 8-1 summarizes these devices and subsequent sections describe
them in greater detail.
Programming for magtape is quite similar to programming for the
magnetic tape cassette (see Chapter 9). Unlike cassette, however,
magtape can handle variable-length records and allows the user to
select a parity mode.

8.1.1

TE10/TU10/TS03 Magnetic Tape

The TE10/TU10/TS03 consists of a TMll controller with a TElO, TUlO, or
TS03 transport.
It is a low-cost, high-performance system for serial
storage
of
large
volumes
of
data
and
programs
in
an
industry-compatible
format.
All recording is nonreturn-to-zero,
inverted (NRZI).

8.1.2

TE16/TU16/TU45/TU77/TU78 Magnetic Tape

The TE16/TU16/TU45/TU77/TU78 consists of an RH11/RH70 controller, a
TM02,
TM03,
or TM78 formatter, and a TE16/TU16/TU45/TU77/TU78
transport. They are quite similar to the TE10/TU10 but are Massbus
devices, with a common controller, a specialized formatter, and
drives. Recording is either 800 bpi NRZI or 1600 bpi phase-encoded
(PE)
for the TE16/TU16/TU45/TU77.
The TU78 records in 1600 bpi
phase-encoded or 6250 bpi GCR modes.

8.1.3

TS11/TU80 Magnetic Tape

The TSll and TOSO are integrated subsystems.
Each has a drive, a
controller,
and
a
formatter.
The hardware is microprocessor
controlled for all operations, including I/O transfers, tape motion,
and so forth, and has comprehensive
(internal) diagnostic test
execution. Recording is 1600 bpi phase-encoded (PE).
The TSll operates in conventional start and stop mode while the TU80
operates at either low speed
(start and stop mode) or high speed
(streaming mode). Tape speed is microprocessor controlled.

8-1

April 1983

MAGNETIC TAPE DRIVERS
8.1.4

TSVOS Magnetic Tape

The TSV05 tape subsystem is a Q BUS device.
It is an integrated
subsystem with a drive, a controller, and a formatter.
The hardware
is microprocessor controlled for all operations,
including
I/O
transfers,
tape motion, and so forth and has comprehensive (internal)
diagnostic test execution. Recording is 1600 bpi phase-encoded
(PE).
The TSV05 operates at 25 inches per second.
Table 8-1
Standard Magtape Devices

Devices

Channels

TE10,T010

9 (TElO)
7 or 9 (T010)

Recording Density
(Frames/Inch)

Tape Speed
(Inches/Second)

Maximum Data
Transfer Rate
(Bytes/Second)

Recording
Method

For 7-channel:
200, 556, or
800
For 9-channel:
800

36,000

NRZI

TE16,!l'Ul6

800 or 1600

For 800 bpi:
36,000
For 1600 bpi:
72,000

NRZI or
Phase
Encoding

T045

800 or 1600

For 800 bpi:
60,000
For 1600 bpi:
120,000

NRZI or
Phase
Encoding

T077

800 or 1600

125

For 800 bpi:
100,000
For 1600 bpi:
200,000

NRZI or
Phase
Encoding

TS0-3

800

12,000

NRZI

TSll

1600

72,000

Phase Encoding

T078

1600 or 6250

125

For 1600 bpi:
200,000
For 6250 bpi:
781,000

Phase Encoding
or GCR (Group
Cyclical
Recording)

TOSO

1600

251
100 2

40,0001
160,000 2

Phase Encoding

TSV05

1600

40,000

Phase Encoding

1. Low Speed
2. High Speed

8-2

April 1983

MAGNETIC TAPE DRIVERS
8.2

GET LON INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for magtapes. A bit setting of 1 indicates that the
described characteristic is true for magtapes.
Bit

Setting

0 or 1

Record-oriented device (0 if the tape is
mounted, 1 if it is not)

Carriage-control device

Terminal device

File-structured device

0 or 1

Single-directory device (0 if the tape is not
mounted, 1 if it is}

Sequential device

Mass storage device

0 or 1

User-mode diagnostics supportedl

0 or 1

Massbus device (set only for TE16, TU16,
TU45, TU77, or TU78 drives interfaced by
means of an RH70 controller)l

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications
channel

0 or 1

Device mountable as a FILES-11 volumel

0 or 1

Device mountablel

Meaning

Words 3 and 4 of the buffer are undefined;
default buffer size, for magtapes 512 bytes.

8.3

word

indicates

the

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the magtape drivers.

1. SYSGEN and device-dependent characteristic.
8-3

MAGNETIC TAPE DRIVERS
8.3.1

Standard QIO Functions

Table 8-2 lists the standard functions of the QIO macro that are valid
for magtape.
Table 8-2
Standard QIO Functions for Magtape
Format

Function

QIO$C IO.ATT, •••

Attach device

QIO$C I 0. DET, •••

Detach device

QIO$C IO.KIL, •••

Cancel I/O requests

QIO$C IO.RLB, ••. ,<stadd,size>

READ logical block
(read tape into buffer)

QIO$C IO.RVB, ••• ,<stadd,size>

READ virtual block
(read tape into buffer)

QIO$C IO.WLB, ••• ,<stadd,size>

WRITE logical block
(write buffer contents to tape)

QIO$C IO.WVB, ••• ,<stadd,size>

WRITE virtual block
(write buffer contents to tape)

stadd
The starting address of the
boundary) •

data

buffer

(must

word

greater

than

select

error

size
The data buffer size in bytes. Size must be even,
O, and, for a write, must be at least 14 bytes.
IO.KIL does not cancel an in progress request unless
has occurred.

8.3.2

Device-Specific QIO Functions

Table 8-3 lists the device-specific functions of the QIO macro that
are valid for magtape. Additional details on certain functions appear
below.

8.3.2.1 10.RLV - The data appears in the specified buffer in a
fashion identical with IO.RLB or IO.RVB, as long as the data block has
the same length as the buffer.

8-4

April 1983

MAGNETIC TAPE DRIVERS
8.3.2.2 IO.RWD - Completion of IO.RWD means that the rewind has been
initiated.
Additional operations on that controller may then be
queued. However, a request for the same unit will be queued by the
driver until load point {BOT) is reached.

8.3.2.3 IO.RWU - IO.RWU is normally used when operator intervention
is required (for example, to load a new tape).
The operator must turn
the unit back on line manually before subsequent operations can
proceed.
Table 8-3
Device-Specific QIO Functions for Magtape
Function

Format
QIO$C IO. DSE, •••

Data Security Erase (TU78 only)

QIO$C IO. EOF, •••

Write end-of-file mark (tape mark)

QIO$C IO. ERS, .••

Erase (TElO and TUlO not
supported)

QIO$C IO.RLV, ••• ,<stadd,size>

READ logical block reverse (TElO
and TUlO not supported.)

QIO$C IO. RWD, •••

Rewind unit

QIO$C IO.RWU, •••

Rewind and turn unit off line

QIO$C IO.SEC, •••

Sense tape characteristics

QIO$C IO.SMO, ••• ,<cb>

MOUNT tape and set tape
characteristics (Unit must be
READY, tape at LOAD POINT.)

QIO$C IO.SPB, ••• ,<nbs>

SPACE blocks

QIO$C IO.SPF, ••. ,<nes>

SPACE files

QIO$C IO.STC, ••• ,<cb>

SET tape characteristics

cb
The characteristic bits to set.
nbs

The number of blocks
negative if reverse).

space

8-5

past

(positive

forward;

April 1983

MAGNETIC TAPE DRIVERS
nes
The number of EOF marks to space
negative if reverse).

past

(positive

forward,

even

byte

size
The size of the stadd data buffer in bytes
number of bytes greater than 0) •

(must

stadd
The starting address of the data
boundary) •

buffer

(may

8.3.2.4 IO.ERS - Erases 3 inches of (write blank)
tape, effectively
providing an extended interrecord gap.
(Not supported on TUlO and
TElO.)

8.3.2.5 IO.DSE - The TU78 will erase from the current position
end-of-tape and then rewind the tape to beginning-of-tape.

8.3.2.6 IO.SEC - This function returns the tape characteristics in
the second I/O status word. The tape characteristic bits are defined
as follows:
Can Be Set by
IO.SMO and IO.STC

Bit

Meaning When Set

For TUlO, 556 bpi
density (7-channel).
For TE16, TU16, TU45, TU77,
TU78, and TSll, reserved.

For TUlO, 200 bpi
density (7-channel).
For TE16, TU16, TU45, TU77, and
TU78, reserved.

For TSll, TOSO, and TSV05,
swap byte mode (read/write).
2

For TUlO, core-dump
mode (7-channel, see below).
For TE16, TU16, TSll, TU45,
TU77, and TU78 reserved.

Even parity (default is odd).
(Not selectable for the TSll.)

Tape is past EOT.

Last tape command encountered
EOF (unless last command was
backspace) .

8-6

April 1983

MAGNETIC TAPE DRIVERS

Bit

Meaning When Set

Can Be Set by
IO.SMO and IO.STC

Writing is prohibited.

Writing with extended interrecord gap is prohibited
(that is, no recovery is attempted
after write error).

Select error on unit.

Unit is rewinding.

Tape is physically write-locked.

For TElO, TUlO, and TS03, reserved.
For all other tapes, 1600 bpi density.

For TUlO, drive is 7-channel.
For all other tapes, reserved.

Tape is at load point (BOT).

Tape is at end-of-volume (EOV).

Tape is past EOV (reserved for driver; always 0 when read by user).

In core-dump mode (TUlO only, 800 bpi density,
and 7-channel), each
8-bit byte is written on 2 tape frames, 4 bits per frame.
In other
modes on 7-channel tape, only 6 low-order bits per byte are written.
For the TSll, 1600 bpi density is always selected (bit 11=1). Bit 11
cannot be modified by either the IO.SMC or IO.STC functions. For
drives that use the TM03 controller, this bit can be either set or
cleared;
however, once the tape is moved from the load (beginning of
tape) position (BOT), the device driver modifies this bit to reflect
the actual density of the tape currently mounted. You cannot change
bit 11 once the tape is moved beyond BOT. For the TU78, bit 11 set
indicates 1600 bpi and bit 11 clear indicates 6250 bpi. Bit 11 cannot
be set or cleared once the tape is moved beyond BOT.
The effect of these settings is illustrated in Figure 8-1 for the TElO
and TUlO, and in Figure 8-2 for the TE16, TU16, TU45, and TU77.

8-7

April 1983

MAGNETIC TAPE DRIVERS

SET EVEN
PARITY

YES

SET 800 BPI,
NINE-CHANNEL

YES

SET 800 BPI,
>--Y_ES_ __.. SEVEN-CHANNEL,
CORE-DUMP
MODE

SET 556 BPI,

__Y_E_s_ _ _-<

SEVEN-CHANNEL

YES

SET 200 BPI.
SEVEN-CHANNEL

SET 800 BPI.
SEVEN-CHANNEL

ZK-002-8~

Figure 8-1

Determination of Tape Characteristics for the TE10/TU10

8-8

MAGNETIC TAPE DRIVERS

SET 1600 BPI

YES

SET 800 BPI

YES

SET
EVEN PARITY

ZK-003-81

Figure 8-2

Determination of Tape Characteristics
for the TE16/TU16/TU45/TU77

8.3.2.7 IO.SMO - This function can be used as a combination of the
sense
(IO.SEC)
and set
(IO.STC)
tape characteristics functions.
Unlike IO.STC, however, the IO.SMO function requires that the unit be
READY and the tape be at load point
(BOT).
If either of these
conditions is not met, the function returns an error status code of
IE.FHE (refer to Table 8-4).
The IO.SMO function should be used to set the characteristics of a
newly loaded tape.
If the IE.FHE error code is returned, the tape
drive is not on line and is not at BOT.

8-9

MAGNETIC TAPE DRIVERS
8.4

STATUS RETURNS

The error and status conditions listed in Table 8-4
the magtape drivers described in this chapter.

are

returned

Table 8-4
Magtape Status Returns
Reason

Code

rs.sue

Successful completion
The operation specified in the QIO directive was
completed successfully.
The second word of the I/O
status block can be examined to determine the
number
of
bytes processed,
if the operation
involved reading or writing.
This code is also
returned
if nbs equals 0 in an IO.SPB function or
if nes equals 0 in an IO.SPF function.

IS.PND

I/O request pending
The operation specified in the QIO directive has
not yet been completed.
The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled by IO.KIL
while in progress or while still in the I/O queue.

IE.BBE

Bad block
A bad block was encountered while reading or
writing and the error persists after nine retries.
The number of bytes transferred is returned in the
second word of the
I/O status block.
For TMll,
IE.BBE may also indicate that a bad tape error
(BTE)
has
been encountered while reading or
spacing.

IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a buffer, while
only
word
alignment
is legal
for
the QIO.
Alternatively, the length of a buffer is not an
even number of bytes.

IE.DAA

Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code
indicates that the
issuing task has
already attached the desired physical device unit,
not that the unit was attached by another task.
(continued on next page)

8-10

MAGNETIC TAPE DRIVERS
Table 8-4
(Cont.)
Magtape Status Returns
Code
IE.DAO

Reason
Data overrun
On a read, a
record exceeded the stated buffer
size.
The final portion of the buffer is checked
for parity, but is not read into memory.

IE.DNA

Device not attached
The physical device unit specified
in an
IO.DET
function was not attached by the issuing task.
This code has no bearing on the attachment status
of other tasks.

IE.DNR

Device not ready
The physical device unit specified
in the QIO
directive was not ready to perform the desired I/O
operation.
This code is returned to
indicate one
of the following conditions:

IE.EOF

•

A time-out occurred on the physical device
(that is, an interrupt was lost).

•

A vacuum failure occurred on the magtape drive.

•

While trying to read
detected blank tape.

•

The LOAD switch on the physical
switched to the off position.

•

The unit failed internal diagnostic tests
only)

space,

the

unit

driver

drive

was
(TS04

End-of-file encountered
An end-of-file (tapemark) was encountered.

IE.EQT

End-of-tape encountered
The end-of-tape
{physical
end-of-volume)
was
encountered while the tape was moving
in the
forward direction.
A 10-foot length of tape is
provided past EOT to be used for writing data and
markers, such as volume trailer labels.
The IE.EQT
code will continue to be returned in the I/O status
block until the EOT marker is passed in the reverse
direction.
IE.EQT is not returned on a
read
operation.
(continued on next page)

8-11

MAGNETIC TAPE DRIVERS
Table 8-4
(Cont.)
Magtape Status Returns
Code
IE.EOV

Reason
End-of-volume encountered (unlabeled tape)
On a
forward
space
function,
the
logical
end-of-volume was encountered. An end-of-volume is
two consecutive end-of-file marks
(EOF), or a
beginning-of-tape mark
(BOT)
followed by an EOF.
The tape is normally left positioned between the
two marks.

IE.FHE

Fatal hardware error
Nonrecoverable hardware malfunction: e.g., magtape
unit not READY and/or tape not at LOAD POINT when
IO.SMO is issued.

IE.IFC

Illegal function
An illegal function
(or subfunction bit)
was
specified
in a magtape I/O request.
Refer also to
Section 8.4.3.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified
in the QIO directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE.SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task.
For magtape,
this code is
also returned if a byte count of 0 was specified or
if the user attempted to write a block that was
less than 14 bytes long.

IE.VER

Unrecoverable error
After the system's standard number of retries
been attempted upon encountering an error,
operation still could not be completed.
magtape,
this code is returned in the case of
or checksum errors or when a tape block could
be read.

IE.WLK

has
the
For
CRC
not

Write-locked device
The task attempted to write on a magtape unit that
was physically write-locked.
Alternatively, tape
characteristic bit 6 was set by the software to
write-lock the unit logically.

8-12

MAGNETIC TAPE DRIVERS
After processing a QIO request, the magnetic tape driver returns two
status words.
The first word contains one of the I/O status codes
listed in Table 8-4.
For successful
second
I/O
operations for
shown in Table

QIO execution (IS.SUC) or read requests
(IE.DAO),
status word may contain further
information.
which this is true, and the information returned,
8-5. For all other cases this word is undefined.

the
The
are

Table 8-5
Information Contained in the Second I/O Status Word
I/O Function Code
IO.RLB
IO. RLV
IO.RVB
IO.SEC
IO.SPB
IO.SPF
IO.WLB
IO.WVB

8.4.1

Information Returned
Number of bytes transferred

I Number of bytes transferred

Number of bytes transferred
Tape characteristics word
Number of records spaced over
Number of files spaced over
Number of bytes transferred
Number of bytes transferred

Select Recovery

If a request fails because the desired unit is off line, no drive has
the desired unit number, or has its power off, the following message
is output on the operator's console:

*** MTn: -- SELECT ERROR
n

The unit number of the specified drive.
The driver checks the unit for readiness and repeats the message every
15 seconds until the requesting task is aborted or the unit is made
available.
In the latter case, the driver then proceeds with the
request.

8.4.2

Retry Procedures for Reads and Writes

If an error occurs during a read (for example, vertical parity error),
the recovery procedure depends on the type of magtape in use. Read
errors for TElO, TUlO, TS03, TE16, TU16, TU45, TU77, are retried by
backspacing one record and then rereading the record in question.
If
the error persists after nine retries,
IE.VER is returned.
Read
errors for the TU78 are retried using a combination of backspacing one
record and then rereading the record in question,
rereading
in the
opposite direction,
rereading at both normal/low thresholds, and
cleaning the tape.

8-13

April 1983

MAGNETIC TAPE DRIVERS
Read errors for the TSll, TOSO,
block in error a predetermined
the block is passed by the tape
after a predetermined number of

and TSVOS are retired by rereading the
number of times.
Every eighth reread,
cleaner blade. If the error persists
retries, IE.VER is returned.

Write recovery is the same for all devices. When a write operation
fails, the driver attempts the following error recovery procedure:
1.

Repositions the tape

Erases three inches
interrecord gap)

Retries the write operation

tape

(resulting

extended

If the error persists after a predetermined number of retries,
IE.VER
is returned.
The requesting task can use IO.STC to prohibit writing
with an extended interrecord gap.
In this case, the tape is
backspaced and the write is retried.

8.4.3

Power-Fail Recovery for Magnetic Tapes

If a power failure and/or loss of vacuum occurs on a magnetic tape
drive,
tape position is lost.
(Note that an initial system boot
simulates a recovery from a power failure.) Additionally, on auto-load
drives, the tape will be positioned at BOT when the unit is turned on
line.
To prevent accidental destruction of data currently on tape, the
driver maintains a power-fail status indicator. When this indicator
is set, the driver disallows any data transfer or tape motion commands
until a rewind
(IO.RWD),
rewind unload (IO.RWU), or mount and set
characteristics (IO.SMC) function is issued.
These functions clear
the power-fail indicator and allow all tape functions to be issued.
It is also possible to issue the set and sense characteristics
functions
(IO.STC and IO.SEC) while the power-fail indicator is set.
These functions, however, will not clear the bit.
All functions other than those just described are considered illegal
and cause the return of the IE.IFC (illegal function) error code to
the requesting task.
In situations where a tape is currently a
mounted volume, the tape should be dismounted and then remounted
before use.
In doing this, the rewind command will be issued, thereby
clearing the power-fail indicator.

8.5

PROGRAMMING HINTS

This
section
considerations
chapter.

8.5.1

contains
information
on
important
programming
relevant to users of magtape drivers described in this

Block Size

Each block must contain an even number of bytes, at least 14 for a
write and at most 65,534.
However, tape usage is more efficient with
a larger buffer.

8-14

April 1983

MAGNETIC TAPE DRIVERS
8.5.2

Importance of Resetting Tape Characteristics

A task that uses magtape should always set the tape characteristics to
the proper value before beginning I/O operations.
The task cannot be
certain in what state a previous task left these characteristics.
It
is also possible that an operator might have changed the magtape unit
selection.
If the selection switch is changed, the new physical
device unit may not correspond to the characteristics of the unit
described by the respective unit control block.

8.5.3

Aborting a Task

If a task is aborted while waiting for a rnagtape unit to be
the magtape driver recognizes this fact within 1 second.

selected;

If a task is aborted while waiting for a magtape unit to complete a
space operation, the magtape driver may allow spacing to the next tape
mark.

8.5.4

Writing an Even-Parity Zero-NRZI

If an even-parity 0 were written normally,
it would appear to the
drive as blank tape.
It is therefore converted to 20 (8).
If this
conversion is undesirable, the user must ensure that no even-parity Os
are output on the tape.

8.5.5

Density Selection

The TM03 and TM78 controllers impose the following density selection
restriction:
The user cannot mix recording densities on any volume
associated with the controller.
Density for write operations is selected when the tape is at the load
(BOT)
position.
Density for read operations is hardware - selected
during the first read (away from BOT);
after the first read,
the
IO.SEC function can be used to determine (sense) tape density.

8.5.6

End-of-Volume Status {Unlabeled Tape)

The magnetic tape driver detects end-of-volume when it spaces over the
second of two consecutive tape marks. The tape is left positioned
between the two tape marks.
The magnetic tape driver returns the IE.EOV status code only on
operations.
IE.EOV is never returned by read operations.

space

For the purpose of checking for end-of-volume, the driver treats
beginning of tape (BOT) as a tape mark.
Therefore, any forward space
operation from BOT that immediately encounters a tape mark will return
IE.EOV.
If a space operation stops between two tape marks but does not space
over the second one, the driver will return end of file rather than
end-of-volume. Any subsequent space operation from this point that
immediately
spaces
over
the
second
tape
mark will return
end-of-volume.

8-15

MAGNETIC TAPE DRIVERS
During IO.SPF operations, the driver considers all tape marks to be
files except for BOT and for the second tape mark spaced over at the
end of volume.
Note that both IO.SPF and IO.SPB operations leave the tape
·a£ter the tape mark in the direction of travel.

positioned

If you want to treat two consecutive tape marks as end-of-volume on
read operations, your application must keep track of the tape marks.
The magnetic tape driver does not support two consecutive tape marks
as end-of-volume on read operations.

8.5.7

Resetting VCK Indicator

When the tape transport status for a TSll, TU80, or TSV05 changes
(goes on-line or off-line), further I/O operations are inhibited. A
deliberate I/O sequencing must occur to reset the VCK indicator and
allow physical I/O to proceed. This sequencing is done by issuing a
IO.RWD or IO.SMO QIO or including /RW or /REW switches to command
requests (such as DMP).

8-16

April 1983

CHAPTER 9
CASSETTE DRIVER

9.1

INTRODUCTION

RSX-llM supports the TAll magnetic tape cassette
(a TAll controller
with a TU60 dual transport).
Programming for cassette is quite
similar to programming for magtape (see Chapter 8).
The TAll system
is a dual-drive,
reel-to-reel unit designed to replace paper tape.
Its two drives run nonsimultaneously, using DIGITAL Proprietary
Philips-type cassettes.
The maximum capacity of a cassette, in bytes, is 92,000 (minus 300 per
file gap and 46 per interrecord gap).
It can transfer data at speeds
of up to 562 bytes per second.
Recording density ranges from 350 to
700 bits ber inch, depending on tape postion.

9.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for cassettes. A bit setting of 1 indicates that the
described characteristic is true for cassettes.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Meaning

9-1

CASSETTE DRIVER
Meaning

Bit

Setting

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 of the buffer are undefined;
default buffer size, for cassettes 128 bytes.

9.3

word

indicates

the

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the cassette driver.

9.3.1

Standard QIO Functions

Table 9-1 lists the standard functions of the QIO macro that are valid
for cassette.
Table 9-1
Standard QIO Functions for Cassette
Format

Function

QIO$C IO. ATT, •••

Attach device

QIO$C IO.DET, •••

Detach device

QIO$C IO.KIL, •••

Cancel I/O requests

QIO$C IO.RLB, ••• ,<stadd,size>

READ logical block
(read tape into buffer)

QIO$C IO.RVB, ••• ,<stadd,size>

READ virtual block
(read tape into buffer)

QIO$C IO.WLB, ••• ,<stadd,size>

WRITE logical block
(write buffer contents to
tape)

QIO$C IO.WVB, ••• ,<stadd,size>

WRITE virtual block
(write buffer contents to
tape)

9-2

l
1

CASSETTE DRIVER
stadd
The starting address of
boundary).

the

data

buffer

(may

byte

size
The data buffer size in bytes (must be greater than 0).
IO.KIL does not affect in-progress requests.

9.3.2

Device-Specific QIO Functions

Table 9-2 lists the device-specific functions of the QIO macro that
are valid for cassette~
The section on programming hints below
provides more detailed information about certain functions.

9.4

STATUS RETURNS

The error and status conditions listed in Table 9-3
the cassette driver described in this chapter.

are

returned

Table 9-2
Device-Specific QIO Functions for Cassette
Format

Function

QIO$C IO.EOF, •••

Write end-of-file gap

QIO$C IO.RWD, •.•

Rewind unit

QIO$C IO.SPB, ••• ,<nbs>

SPACE blocks

QIO$C IO.SPF, ••• ,<nes>

SPACE files

nbs
The number of blocks to space past {positive if forward, negative
if reverse).
nes
The number of EOF gaps
negative if reverse).

space

9-3

past

{positive

forward,

CASSETTE DRIVER
Table 9-3
Cassette Status Returns
Code

rs.sue

Reason
Successful completion
The operation specified in the QIO directive was
completed successfully. The second word of the I/O
status block can be examined to determine the
number of bytes processed if the operation involved
reading or writing, or. the number of blocks or
files spaced
if the operation involved spacing
blocks or files.

IS.PND

I/O request pending
The operation specified in the QIO directive has
not yet been executed.
The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled by
while still in the I/O queue.

IE.DAA

IO.KIL

Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code indicates that the issuing task has
already attached the desired physical device unit,
not that the unit was attached by another task.

IE.DAO

Data overrun
The driver was not able to sustain
required by the TAll controller.

IE.DNA

the

data

rate

Device not attached
The physical device unit specified by an IO.DET
function was not attached by the issuing task.
This code has no bearing on the attachment status
of other tasks.

IE.DNR

Device not ready
The physical device unit specified in the QIO
directive was not ready to perform the desired I/O
operation. This code is returned to indicate one
of the following conditions:
•

The cassette has not been physically inserted.

•

The unit is off line.

•

A time-out occurred on the physical device
(that is, an interrupt was lost).

unit

(continued on next page)

9-4

CASSETTE DRIVER
Table 9-3
(Cont.)
Cassette Status Returns
Code
IE.EQF

Reason
End-of-file encountered
An end-of-file gap was recognized on the cassette
tape.
This code is returned if an EQF gap is
encountered during a read, or if the cassette is
physically removed during an I/Q operation.

IE.EQT

End-of-tape encountered
While reading or writing,
clear
trailer
at
end-of-tape (EQT) was encountered.
Unlike magtape,
writing beyond EOT is not permitted on cassettes*
This condition is always sensed on a write before
it would be sensed on a read of the same section of
tape.
If IE.EQT is returned during a write, the
cassette head has encountered EQT before finishing
the writing of the last block.
It is recommended
that the user entirely rewrite the block on another
cassette.

IE.IFC

Illegal function
A function code was specified
that is illegal fo~ cassette.

IE.QFL

I/Q

request

Device off line
The physical device unit associated with the LUN
specified
in the QIQ directive was not on line.
When the system was booted, a
device
check
indicated that this physical device unit was not in
the configuration.

IE.SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task.
Alternatively, a byte count
of 0 was specified on a transfer.

IE.VER

Nonrecoverable error
This code is returned when a block check error
occurs
(see Section 9.6.5).
The cyclic redundancy
check (CRC), a 2-byte value located at the end of
each block, is a checksum that is tested during all
read operations to ensure that data is
read
correctly.
This is returned if a read request did
not specify exactly the number of bytes of data
in
the record on tape.
If a nonrecoverable error is
returned, the user may attempt recovery by spacing
backward one block and retrying the read operation.

IE.WLR

Write-locked device
The task attempted to write on a cassette unit that
was physically write-locked.
This code may be
returned after an IQ.WLB,
IQ.WVB,
or
IQ.EOF
function.
9-5

CASSETTE DRIVER
Cassette Recovery Procedures

9.4.1

If an error occurs during a read or write operation, the operation
should be retried several times. The recommended maximum number of
retries is nine for a read and three for a write because each retry
involves backspacing, which does not always position the tape in the
same place. More than three retries of a write operation may destroy
previously written data. For example, to retry a write, it is best to
space two blocks in reverse, then space one block forward.
This
insures the tape is in the proper position to rewrite the block that
encountered the error.
After read and write functions, the second I/O status word contains
the number of bytes actually processed by the function. After spacing
functions, it contains the number of blocks or files actually spaced.

9.5

STRUCTURE OF CASSETTE TAPE

Figure 9-1 illustrates a general structure for cassette
different structure can be employed if the user wishes.

tape.

Here the tape consists of blocks of data interspersed with sections of
clear tape that serve as leader, trailer, interrecord gaps (IRGs), and
end-of-file gaps.
The logical end-of-tape in this case consists of a sentinel label
record, rather than the conventional group of end-of-file gaps. Each
file must contain at least one block. The size of each block depends
upon the number of bytes the user specifies when writing the block.
IRGS
_........-.............___
~..._. . . . . . . . . . . .-.._~

BOT

LPG

REC REC

EOT

... REC EOF LR REC ... REC EOF SLR
FILE 2

FILE 1

LEOT

---........____________________~--------------------------150 FEET

ZK-006-81

Figure 9-1

Structure of Cassette Tape

Abbreviation

Meaning

Clear leader

BOT

Physical beginning-of-tape

LPG

Load point gap (blank tape written
before the first retrievable record)

File label record

REC

Fixed-length record (data)

9-6

driver

CASSETTE DRIVER
Abbreviation

Meaning

EOF

End-of-file gap

IRG

Interrecord gap

SLR

Sentinel label record

LEOT

Logical end-of-tape

EOT

Physical end-of-tape

Clear trailer

9.6

PROGRAMMING HINTS

This
section
considerations
this chapter.

9.6.1

contains
information
on
important
programming
relevant to users of the cassette driver described in

Importance of Rewinding

The first cassette operation performed on a tape must always be a
rewind to ensure that the tape is positioned to a known place. When
it is positioned in clear tape, there is no way to determine whether
it is in leader at the beginning-of-tape (BOT) or in trailer at the
end-of-tape (EQT).

9.6.2

End-of-File and IO.SPF

The hardware senses end-of-file (EOF) as a time-out. When IO.SPF is
issued in the forward direction
(nes is positive), the tape is
positioned two-thirds of the way from the beginning of the final
file
gap.
In effect, this is all the way through the file gap. When
IO.SPF is issued in the reverse direction (nes is negative), the tape
is positioned one-third of the way from the beginning of the final
file gap (that is, two-thirds of the way from the beginning of the
last file spaced).
Therefore, to correctly position the tape for a
read or write after issuing IO.SPF in reverse, the user should issue
IO.SPB forward
for one block, followed by IO.SPB in reverse for one
block.

9.6.3

The Space Functions, IO.SPB and IO.SPF

IO.SPB always stops in an IRG gap, IO.SPF in an EOF gap.
Neither
space function actually takes effect until data is encountered.
For
example, suppose the tape is positioned in clear leader at BOT and the
user requests that one block be spaced forward.
The drive passes over
the remaining leader until it reaches data, passes one block, and
stops in the IRG.
Similarly, if the same command is issued when the
tape is at BOT on a blank tape or a tape containing only EOF gaps, the
function does not terminate until EOT.

9-7

CASSETTE DRIVER
9.6.4

Verifying of Write Operations

Certain errors, such as cyclic redundancy check, are detected on read
but not write operations.
Therefore, to ensure reliability of
recording, it is recommended that the user perform a read in order to
verify every write operation.

9.6.5

Block Length

The user must specify the exact number of bytes per block when
requesting read or write operations. An attempt to read a block with
an incorrect byte count causes an unrecoverable error
(see Section
9.4) to occur.

9.6.6

Logical End-of-Tape

The conventional method of signaling logical end-of-tape by multiple
EOF gaps is inadequate for cassettes, because multiple EOF gaps are
not distinguishable from each other. For example, two sequential EOF
gaps would be read as three instead of two. Also spacing functions,
since they are triggered by encountering data, can not recognize
multiple EOF gaps. Consequently, the use of a sentinel or key record
to signal logical end-of-tape is recommended.

9-8

CHAPTER 10
LINE PRINTER DRIVER

10.1

INTRODUCTION

The RSX-llM line printer driver supports the line printers summarized
in Table 10-1.
Subsequent sections of this chapter describe these
printers in greater detail.
Table 10-1
Standard Line Printer Devices
Controller

Printer

Column Width

LPll-C

LP14-C

132

890

LPll-D

LP14-D

132

650

Character Set

Lines per Minute

LPll-F

LPOl-F

LPll-H

LPOl-H

170-1110

LP02-J

132

170-1110

LPll-K

LP02-K

132

170-1110

LPll-R

LP04-R

132

1110

LPll-S

LP04-S

132

1110

LPll-V

LP05-V

132

300

LPll-W

LP05-W

132

300

LPll-Y

LP06-Y

132

600

LPll-Z

LP06-Z

132

460

LPll-GA

LP07

132

1200

LPll-EA

LP26

132

600

LPll-EB

LP26

132

64/96

600/420

LPll-UA

LP27

132

64/96

1200/800

LSll

132

60-200

LVll

LVOl

132

500

LA180

132

150

LNOl

variable I

600

LPll-J
i

LNOl

170-1110

Software selectable fonts not supported by RSX.
10-1

April 1983

LINE PRINTER DRIVER
10.1.l

LPll Line Printer

The LPll is a high-speed line printer available in a variety of
models.
The LPll model line consists of band line printers and drum
line printers. The drum printers are impact printers,
that use one
hammer per column and a revolving drum with uppercase and optional
lowercase characters. The LPll-R and LPll-S are fully buffered models
that operate at a standard speed of 1110 lines per minute.
The other
LPll drum models have 20-character print buffers. These printers are
therefore able to print at full speed if the printed line is no longer
than 20 characters. Lines that exceed this maximum are printed at a
slower rate.
Forms with up to six parts may be used for multiple
copies. The band line printers are impact printers that have a flat
steel belt with raised metal characters on the face.
The LP07, LP26,
and LP27 offer speeds from 420 to 1200 lines per minute.

10.1.2

LSll Line Printer

The LSll is a medium-speed line printer.
It has a 20-character print
buffer, and lines of 20 characters or less are printed at a rate of
200 lines per minute. Longer lines are printed at a slower rate.
RSX-llM does not support the LSll expanded character set feature.

10.1.3

LVll Line Printer

The LVll is a fully-buffered,
electrostatic printer-plotter that
operates at a standard rate of 500 lines per minute.
RSX-llM supports
only the LVll print capability, not the plotter mode.

10.1.4

LA180 DECprinter

The LA180 is a 180-character/sec, dot-matrix
impact printer.
accepts multipart forms and pages of various lengths and widths.

10.1.5

LNOl Laser Printer

The LNOl is a non-impact page printer that uses laser imaging combined
with xerographic printing.
This technology provides letter quality
printing at line printer speeds with no noise. Printing is done on
standard 8 1/2 inch by 11 inch paper at 12 pages per minute, which
equates to 600 lines per minute.
Contributing to the high print
quality is a printer resolution of 300 by 300 dots per inch. The LNOl
offers the speed of a line printer with the advantages of a
phototypeset device.

10.2

GET LON INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for line printers. A bit setting of 1 indicates that the
described characteristic is true for line printers.

10-2

April 1983

LINE PRINTER DRIVER
Meaning

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 of the buffer are undefined;
word 5 indicates the
default size for the device, for line printers the width of the
printer carriage (that is, 80 or 132).

10-2.1

LINE PRINTER DRIVER
10. 3

QIO MACRO

Table 10-2 lists the standard functions of
valid for line printers.

the

QIO

macro

that

are

Table 10-2
Standard QIO Functions for Line Printers
Format

Function

QIO$C IO.ATT I • • •

Attach device

QI0$C IO. DET I • • •

Detach device

QI0$C IO.KIL, •••

Cancel I/O requests

QI0$C IO.WLB, ••• ,<stadd,size,vfc>

WRITE logical block
(print buffer contents)

QIO$C IO.WVB, ••• ,<stadd,size,vfc>

WRITE virtual block
(print buffer contents)

stadd
The starting address of
boundary) .

the

data

buffer

(may

size
The data buffer size in bytes

(must be greater than 0).

vf c
A vertical format control character from Table 10-4.

10-3

byte

LINE PRINTER DRIVER
IO.KIL does not cancel an in-progress request unless the line printer
is in an off-line condition because of a power failure or a paper jam,
or because it is out of paper.
The line printer driver supports no device-specific functions.

10.4

STATUS RETURNS

Table 10-3 lists the error and status conditions that are returned
the line printer driver described in this chapter.

Table 10-3
Line Printer Status Returns
Code

rs.sue

IS.PND

I/O request pending
The operation specified in the QIO directive has
not yet been executed. The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled while
progress or while in the I/O queue.

IE.DAA

Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code indicates that the issuing task has
already attached the desired physical device unit,
not that the unit was attached by another task.

IE.DNA

Device not attached
The physical device unit specified an IO.DET
function was not attached by the issuing task.
This code has no bearing on the attachment status
of other tasks.

IE.IFC

Illegal function
A function code was specified in an
that is illegal for line printers.

I/O

request

(continued on next page)

10-4

LINE PRINTER DRIVER
Table 10-3 (Cont.)
Line Printer Status Returns
Reason

Code
IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line.
When the system was booted, a device
check
indicated that this physical device unit was not
in the configuration.

IE.SPC

Illegal address space

The buffer specified for a write request was
partially or totally outside the address space of J
the issuing task. Alternatively, a byte count of
0 was specified.

l
10.4.1

Ready Recovery

If any of the following conditions occur:

• Paper jam
•
•

Printer out of paper
Printer turned off line

• Power failure
the driver determines that the line printer is off line,
following message is output on the operator's console:

and

the

***LPn: -- NOT READY
n

The unit number of the line printer that is not ready.
The driver retries the function that encountered the error condition
from the beginning, once every second. It displays the message every
m seconds (m is defined at SYSGEN to be a value less than 256.
The
default is 15) until the line printer is readied. If a power failure
occurs while printing a line, the entire line is reprinted from the
beginning when power is restored.

10.5

VERTICAL FORMAT CONTROL

Table 10-4 summarizes the meaning of all characters used for vertical
format control on the line printer. Any one of these characters can
be specified as the vfc parameter in an IO.WLB or IO.WVB function.

10-5

LINE PRINTER DRIVER
Table 10-4
Vertical Format Control Characters
Octal
Value

Character

Meaning

040

Blank

SINGLE SPACE: Output a line feed, print the
contents of the buffer, and output a carriage
return.
Normally,
printing
immediately
follows the previously printed line.

060

Zero

DOUBLE SPACE: Output two line feeds, print
the contents of the buffer, and output a
carriage return.
Normally,
the
buffer
contents are printed two lines below the
previously printed line.

061

One

PAGE EJECT: Output a form feed, print the
contents of the buffer, and output a carriage
return. Normally, the contents of the buffer
are printed on the first line of the next
page.

053

Plus

OVERPRINT: Print the contents of the buffer
and
perform a carriage return, normally
overprinting the previous line.

044

Dollar
sign

PROMPTING OUTPUT: Output a line feed
then print the contents of the buffer.

000

Null

INTERNAL
VERTICAL
FORMAT:
The
buffer
contents are printed without addition of
vertical format control characters. In this
mode,
more than one line of guaranteed
contiguous output can be printed per I/O
request.

and

All other vertical format control characters are interpreted as blanks
{040(8)).

10.6

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the line printer driver described
in this chapter.

10.6.1

RUBOUT Character

The line printer driver discards the ASCII character code 177 during
output, because a RUBOUT on the LSll printer causes a RUBOUT of the
hardware print buffer.

10-6

LINE PRINTER DRIVER
10.6.2

Print Line Truncation

If the number of characters to be p~inted exceeds the width of the
print carriage, the driver discards excess characters until it
receives one that instructs it to empty the buffer and return to
horizontal position 1.
The user can determine that truncation will
occur by issuing a Get LUN Information system directive and exam1n1ng
word 5 of the information buffer. This word contains the width of the
print carriage in bytes.

10.6.3

Aborting a Task

If a task is aborted while waiting for the line printer to be readied,
the line printer driver recognizes this fact within 1 second.

10-7

CHAPTER 11
CARD READER DRIVER

11.l

INTRODUCTION

The RSX-llM card reader driver supports the CRll card reader.
This
reader
is a virtually jam-proof device that reads EIA standard
80-column punched cards at the rate of 300 per minute.
The hopper can
hold 600 cards.
This device uses a vacuum picker that provides
extreme tolerance to damaged cards and makes card wear insignificant.
Cards are riffled in the hopper to prevent sticking.
The reader uses
a strong vacuum to deliver the bottom card. Because it has a very
short card track, only one card is in motion at a time.

11.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for card readers.
A bit setting of 1 indicates that the
described characteristic is true for card readers.
Bit

Setting

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

11-1

CARD READER DRIVER
Meaning

Bit

Setting

Input spooled device

Output spooled device

')
..L £.

Pseudo device

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

Words 3 and 4 of the buffer are undefined;
word 5 indicates
default buffer size, which is 80 bytes for the card reader.

11.3

QIO

the

MACRO

This section summarizes standard and device-specific QIO functions for
the card reader driver.

11.3.1

Standard QIO Functions

Table 11-1 lists the standard functions of
valid for the card reader.

the

QIO

macro

that

are

Table 11-1
Standard QIO Functions for the Card Reader
Function

Format
QIO$C IO.ATT, •••

Attach device

QIO$C IO.DET, •••

Detach device

QIO$C IO.KIL, •••

Cancel I/O requests

QIO$C IO.RLB, ••• ,<stadd,size>

READ logical block
(alphanumeric)

QIO$C IO.RVB, ••• ,<stadd,size>

READ virtual block
(alphanumeric)

stadd
The starting address of
boundary) •

the

data

buffer

(may

byte

size
The data buffer size in bytes (must be greater than 0).
IO.KIL does not cancel an in-progress request unless the card reader
is in an off-line condition because of a pick, read, stack, or hopper
check, because of power failure, or because the RESET button has not
been depressed.
11-2

CARD READER DRIVER
11.3.2

Device-Specific QIO Functions

The device-specific functions of the QIO macro that are valid for
card reader are shown in Table 11-2.

the

Table 11-2
Device-Specific QIO Function for the Card Reader
Format

Function

QIOSC IO.ATA, ••• ,<AST addr>

Attach for unsolicited card AST

QIO$C IO.RDB, ••• ,<stadd,size>

Read logical block (binary)

stadd
The starting address of
boundary) •

the

data

buffer

(may

byte

size
The data buffer size in bytes (must be greater than 0).

11.4

STATUS RETURNS

A wide variety of error conditions and recovery procedures relate to
the use of the card reader.
This section describes the three major
ways in which the system reports error conditions.
1.

Lights and indicators on the card reader panel are turned on
or off to
indicate particular operational problems such as
read, pick, stack, or hopper checks.
Switches are available
to turn the reader power on and off and to allow the user to
reset after correcting an error condition.

A message is output on the operator's console if
checks or power problems occur.

An I/O completion code is returned in the low-order byte of
the first word of the I/O status block specified in the QIO
macro to indicate success or failure on completion of an I/O
function.

operational

The following subsections describe each of these returns in detail.

11.4.1

Card Input Errors and Recovery

The table included below describes all external lights and
switches
used to indicate to the operator that a hardware problem has occurred
and must be corrected.
There are two classes of hardware errors:
•

Those requiring the operator to ready the reader and
operation again

•

Those requiring the operator to remove the last card from the
output stacker, to replace it in the input hopper, and to try
the operation again

11-3

try

the

CARD READER DRIVER
In the first case, the card reader was unable to read the current
card.
In the second, the card was read incorrectly and must be
physically removed from the output stacker. The card reader driver
automatically restarts a read operation within 1 second after the
cards have been replaced in the input hopper.
Table 11-3 summarizes the functions of lights and indicators on the
front panel of the card reader. It discusses common operational
errors that might be encountered while reading cards and recovery
procedures associated with these error conditions.

11.4.2

Ready and Card Reader Check Recovery

If any of the following conditions occur:
•

Power failure

•

Reset switch not pressed (reader off line)

•

Timing error (Two columns were read before the card
driver input the first column from the card reader.)

the driver determines that the card reader is not ready,
following message is output on the operator's console:

reader
and

the

with normal

card

*** CRn: -- NOT READY
When a timing error occurs, the operator can
reader operation by:

proc~ed

Placing the card reader off line by pressing the STOP switch

Removing the last card read and inserting it where it will be
the next card read

Placing the card reader on line by pressing the RESET switch

If any of the following conditions occurs:

• Pick error (PICK CHECK)
• Read error (READ CHECK)
• Output stacker error (STACK CHECK)
• Input hopper out of cards (HOPPER CHECK)
• Output stacker full (HOPPER CHECK)
the driver determines that a card reader check has occurred,
following message is output on the operator's console:

and

the

*** CRn: -- READ FAILURE. CHECK HARDWARE STATUS
where n is the unit number of the card reader that is not ready.
The
operator should correct the error and press RESET:
The driver
attempts the function from the beginning, once every second.
It
displays the message once every m seconds (m is defined at SYSGEN as a
value less than 256. The default is 15) until the card reader is
readied. In all cases except pick error, the last card read should be
reinserted in the input hopper, as described in Section 11.4.1.

11-4

CARD READER DRIVER
Table 11-3
Card Reader Switches and Indicators
Indicator
POWER
Switch

Description

Recovery

Action

Controls application
Pushbutton
indicator
of all power to the
switch
card reader.
(alternate
I action:
lwhen indicator is
pressed for off, depressing switch
both ON and applies power to
reader and causes
OFF)
associated indicator to 1 ight.
When indicator is
lit, depressing
switch removes all
power from reader and
causes indicator to
go out.

READ
CHECK
Indicator

White light

When lit, this light
indicates that the
card just read may be
torn on the leading or
trailing edges, or
that the card may
have punches in
column positions O
or 81.

Card may have been
read incorrectly;
restore power if
possible by depressing the POWER
switch; insert the
card again as the
first card in the
input hopper, and
press the RESET
switch; in some
cases, it may be
necessary to
restart the program.

Card was read incorrectly; duplicate if
necessary, insert
the card again as
the first card in the
input hopper, and
press the RESET
switch.

Because READ CHECK
indicates an error
condition, whenever
this indicator is
lit, it causes the
card reader to stop
operation and extinguishes the RESET
indicator.
PICK
CHECK
Indicator

White light

When lit, this light
indicates that the
card reader failed to
move a card into the
read station after
it received a READ
COMMAND from the
controller.

Card could not be
read; press the
RESET switch to try
again or remove the
cards from the input
hopper, smooth the
leading edges, replace, and then
press the RESET
switch.

Stops card reader
operation and extinguishes RESET
indicator.
(continued on next page)

11-5

CARD READER DRIVER
Table 11-3 (Cont.)
Card Reader Switches and Indicators
Indicator

Description

Action

Recovery

STACK
CHECK
Indicator

White light

When lit, this light
indicates that the
previous card was not
properly seated in
the output stacker
and therefore may be
badly mutilated.

Card may have been
read incorrectly and
is not positioned
properly in the output stacker; duplicate the card i f it
is damaged; insert
I
the card again as
the first card in
the input hopper and·
press the RESET
switch.

Stops card reader
operation and extinguishes RESET
indicator.
HOPPER
CHECK
Indicator

White light

When lit, this light
Card may have been
indicates that either read incorrectly;
the input hopper is
empty the stacker or
empty or that the out- fill the hopper; input stacker is full.
sert the card again
as the fist card in
the input hopper and
press the RESET
switch.

STOP
Switch

Momentary
pushbutton/
indicator
switch
(red light)

When depressed,
immediately lights
and drops the READY
line, thereby extinguishing the RESET
indicator. Card
reader operation then
stops as soon as the
card currently in the
read station has been
read.
This switch has no
effect on the system
power; it only stops
the current operation.

RESET
Switch

Momentary
pushbutton/
indicator
switch
(green
1 igh t)

When depressed and
released, clears all
error flip-flops and
initializes card
reader logic. Associated RESET indicator
lights to indicate
that the READY.signal
is applied to the controller.
The RESET indicator
goes out whenever the
I STOP switch is depressed or whenever
an error indicator
lights (READ CHECK,
PICK CHECK, STACK
CHECK, or HOPPER
CHECK) •

11-6

I
I

CARD READER DRIVER
11.4.3

I/O Status Conditions

The error and status conditions listed in Table 11-4 are
the card reader driver described in this chapter.

returned

Table 11-4
Card Reader Status Returns
Code

rs.sue

IS.PND

I/O request pending
The operation specified in the QIO directive has
not yet been executed.
The I/O status block is
filled with Os.

IE.ABO

Operation aborted
The specified I/O operation was cancelled while in
progress or while still in the I/O queue.

IE.DAA

Device already attached
The physical device unit specified
in an IO.ATT
function was already attached by the issuing task.

IE.DNA

Device not attached
The physical device unit specified
in an IO.DET
function was not attached by the issuing task.
This code has no bearing on the attachment status
of other tasks.

IE.EOF

End-of-file encountered
An end-of-file control card was recognized.

IE.IFC

Illegal function
A function code was specified in an
that is illegal for card readers.

IE.NOD

I/O

request

Buffer allocation failure
Dynamic storage space has been depleted, and there
was
insufficient
buffer
space available to
allocate a card buffer (that is,
cards are read
into a driver buffer, translated, and then moved
to the user buffer) ~
(continued on next page)

11-7

CARD READER DRIVER
Table 11-4
(Cont.)
Card Reader Status Returns
Reason

Code
IE.OFL

Device off line
The physical device unit associated with the LUN
specified
in the QIO directive was not on line.
When the system was booted, a device
check
indicated that this physical device unit was not
in the configuration.
Illegal address space

IE.SPC

The buffer specified for a
read request was
partially or totally outside the address space of
the issuing task. Alternatively, a byte count of
O was specified.

11.5

FUNCTIONAL CAPABILITIES

The card reader driver can perform the following functions:
1.

Read cards in DEC026 format and translate to ASCII

Read cards in DEC029 format and translate to ASCII

Read cards in binary format

If the QIO macro specifies the IO.RLB or IO.RVB function,
the driver
interpets all data as alphanumeric (026 or 029 format).
As explained
below, control characters indicate whether 026 or 029 is desired.
If
the QIO macro specifies IO.ROB,
the driver
interprets all data,
including 026 and 029 control characters, as binary.

11.5.1

Control

Characters

Table 11-5 lists the multipunched cards that the card reader driver
recognizes as control characters.
They are never transferred to the
user's ·buffer or included in the count of transferred bytes in
alphanumeric mode.
In binary mode, the only control card recognized
is binary EOF.
DEC026 is the default translation mode
when
the
system
is
bootstrapped.
This mode remains in effect until explicitly changed by
a control card indicating that DEC029 cards will follow.
After
encountering a DEC029 control card, the driver translates all cards in
DEC029 format unless another DEC026 control card is encountered. This
card - overrides
the 029 mode specification and indicates that
subsequent cards are to be translated in 026 format.
Control
characters are addressed to the card reader itself, and remain in
effect even when the reader is attached and subsequently detached.

11-8

CARD READER DRIVER
The default condition can easily be changed from DEC026 to DEC029 by
reading a 029 control card, and then saving the system with the MCR
SAV command.
Table 11-5
Card Reader Control Characters
Punches
12-11-0-1-6-7-8-9

1
(All 8 punches in
the first 8 columns)

12-11-0-1-6-7-8-9

I 12-2-4-8
I 12-0-2-4-6-8
11.6

Meaning

Columns

I
I

End-of-file (alphanumeric)
End-of-file (binary)

026-coded cards follow

029-coded cards follow

CARD READER DATA FORMATS

The card reader reads data in either alphanumeric or binary format.

11.6.1

Alphanumeric Format (026 and 0211)

Table 11-6 summarizes the translation from DEC026 or DEC029 card codes
to ASCII.

11.6.2

Binary Format

In RSX-llM binary format, the data are not packed, but are transferred
exactly as read, one card column per word.
Because each word has 16
bits and each card column represents only 12, the data from the column
are stored in the rightmost 12 bits of the word.
The word's remaining
four bits contain Os.

11.7

PROGRAMMING

HINTS

This
section
contains
information
considerations relevant to users of the
in this chapter.
Section 11.4 contains
error-recovery procedures that might be
point of view.

11.7.1

on
important
programming
card reader driver described
information on operational
important from a programming

Input Card Limitation

Only one card can be read with a single QIO macro call.
A request to
read more than 80 bytes or colµmns, the length of a single card, does
not result in a multiple card transfer.
Only 80 columns are
processed.
It is possible to read fewer than 80 columns of card input
with a QIO read function.
For example, the user can specify that only
the first 10 columns of each card are to be read.

11-9

CARD READER DRIVER
11.7.2

Aborting a Task

If a task waiting for the card reader to be readied is aborted,
card reader driver recognizes this fact within 1 second.

the

Table 11-6
Translation from DEC026 or DEC029 to ASCII

Character

SPACE
!
II

#
$
%

AND

(
)

+
:
;

=
>
?
@

A
B

c
D
E
F
G
H

I
J
K
L

NonParity
ASCII
173
175
040
041
042
043
044
045
046
047
050
051
052
053
072
073
074
075
076
077
100
101
102
103
104
105
106
107
110
111
112
113
114

DEC029

DEC02n

12 0
12 0
11 0
11 0
none
none
12 8 7 12 8 7
8 7
0 8 5
8 3
0 8 6
11 8 3 11 8 3
0 8 4
0 8 7
12
11 8 7
8 5
8 6
12 8 5 0 8 4
11 8 5 12 8 4
11 8 4 11 8 4
12 8 6 12
8 2
11 8 2
11 8 6 0 8 2
12 8 4 12 8 6
8 6
8 3
11 8 6
0 8 6
12 8 2
I 0 8 7
8 4
8 4
12 1
12 1
12 2
12 2
12 3
3
I 12
12 4
12 4
12 5
12 5
12 6
12 6
12 7
12 7
12 8
12 8
12 9
12 9
11
1
11, 1
,
.L 1

2
11 3

NonParity
ASCII

Character

0
1
2
3
4
5
6
7
8
9
M

N
0
p
Q
R

s
I

l.i 2
11 3

11-10

w
x

z
[

\
]
"

or
or

054
055
056
057
060
061
062
063
064
065
066
067
070
071
115
116
117
120
121
122
123
124
125
126
127
130
131
132
133
134
135
136
137

DEC029

DEC026

0 8 3
0 8 3
11
11
12 8 3 12 8 3
0 1
0 1
0
0
1
1
2
2
3
3
4
4
5
5
6
6
7
7
8
8
9
9
11 4
11 4
11 5
11 5
11 6
11 6
11 7
11 7
11 8
11 8
11 9
11 9
0 2
0 2
0 3
0 3
0 4
0 4
0 5
0 5
0 6
I0 6
0 7
7
0 8
I0 8
0 9
0 9
12 8 2 11 8 5
0 8 2
8 7
11 8 2 12 8 5

....,

CHAPTER 12
MESSAGE-ORIENTED COMMUNICATION DRIVERS

12.l

INTRODUCTION

RSX-llM supports a variety of
communication
line
interfaces:
synchronous
and
asynchronous,
single-line
and
multiplexers,
character-oriented and message-oriented.
These are used for
terminal
communications,
remote job entry, multicomputer
interfaces, and
laboratory and industrial control communications.
Communications line
interfaces can be roughly divided into two categories:
•

Terminal

(character-oriented) communications devices

•

Multicomputer (message-oriented) communications devices

Chapters 1, 2, and 3 describe the character-oriented asynchronous
communications
line
interfaces
used
primarily
for
terminal
communications. The Terminals and Communications Handbook contains
more detail on these devices.
This chapter describes in some detail
the
RSX-llM
message-oriented
synchronous
and
asynchronous
communication line interfaces.
These are used most frequently in
multicomputer communications.
Character-oriented communications devices include the DHll,
DJll,
DLll-A,
DLll-B/C/D,
and DZll interfaces.
These are asynchronous
multiplexers and single-line interfaces used almost exclusively for
terminal communications.
Transfers on all of these interfaces are
performed one character at a time.
None of the interfaces in this
category has a driver of its own (that is, they are supported by the
terminal driver), and none can be accessed directly as RSX-llM
devices.
Message-oriented communications line interfaces are used primarily to
link two separate but complementary computer systems.
One system must
serve as the transmitting device and
the other as the receiving
device.
Devices in this category include the synchronous and
asynchronous single-line interfaces summarized in Table 12-1.
The message-oriented communication line interfaces are used
to transfer large blocks of data.

primarily

Whereas the character-oriented
interfaces can only be
accessed
indirectly through the terminal driver, the DAll-B, DLll-E, DMCll,
DPll, DQll, DUll, and DUPll allow I/O requests to be queued directly
for them.
These devices have drivers of their own and can be accessed
by means of the logical device names listed in Table 1-1.
These names
can be used in assigning LUNs with the Assign LUN system directive, at
task build, or with the REASSIGN MCR command.
The
following
subsections briefly discuss the message-oriented interfaces supported
for RSX-llM.

12-1

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 12-1
Message-Oriented Communication Interfaces

Model

Type

Rate
(KBaud)

Duplex
Half/Full

Data block
(words)

Synchronous
Character

32K

500

Serial, asynchronous

0.05-9.6

32K

Programmable

DMCll

Serial, synchronous

19.2-1000

DPlll

Serial, synchronous

2-19.2

32K

Programmable

DQ11 1

Serial, synchronous

2.4-1000

32K

Programmable

ou11l

Serial, synchronous

0.05-9.6

32K

Programmable

DUPll

Serial, synchronous

0.05-9.6

32K

Programmable

DAll-81

Parallel

DL11-E2

1. Support is not provided on RSX-llM-PLUS systems.
2. DLll-E support is provided on RSX-llM-PLUS
terminal driver only.

12.1.1

systems

using

the

full-duplex

DAll-B Parallel Interface

The DAll-B provides a bit-parallel, direct memory access interface
between two PDP-11 computer systems. Data transfers are performed a
word at a time and are made directly between the memories of the two
systems. The maximum transfer rate is 500,000 baud, and is adjustable
by the user to match the system configuration requirements.
Being a
parallel device, the DAll-B does not utilize sync characters. The
interface is half-duplex and transfers data in blocks of up to 32K
words.
The DAll-B requires two cooperating computers to effect a data
transfer.
In order to control the physical link between the
computers, the device driver contains its own simple line. protocol.
This protocol requires one system to issue a receive QIO and the other
to issue a transmit QIO before any data is actually transferred.

12.1.2

DLll-E Asynchronous Line Interface

The DLll-E is an asynchronous, serial-bit, single-line interface.
It
is a block-transfer device used for remote terminal and multicomputer
communications. Baud rates are selectable between 50 and 9600, and
full data-set control is supported.l

1. Software support for data-set control consists of interlocking RTS
and CTS for data transmission, and the setting of DTR (data terminal
ready) to enable auto-answer modems to answer incoming calls.
DTR is
set when an IO.INL QIO (initialize) is issued.
12-2

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12.1.3

DMCll Synchronous Line Interface

The DMCll provides a direct memory access interface between two PDP-11
computer systems using the DDCMP line protocol, thus delivering high
throughput and reliability while simplifying programming.
The DMCll
supports Non-Processor Request (NPR) data transfers of up to 8K words
at rates of 1,000,000 baud for local operation (over coaxial cable)
and 19,200 baud for remote operation (using modems). Both full- and
half-duplex modes are supported. The DMCll also implements remote
load detect, allowing it to reinitialize a halted computer system.

12.1.4

DPll Synchronous Line Interface

The DPll provides a program interrupt interface between a PDP-11 and a
serial synchronous line.
This interface facilitates the use of the
PDP-11 in remote batch processing, remote data collection, and remote
concentration applications. The modem control feature allows the DPll
to be used in switched or dedicated configurations.
On the DPll, baud rates are selectable between 2000 and 19,200.
The
programmer can select a specific sync character that is used to
synchronize the transmitting and receiving systems.

12.1.5

DQll Synchronous Line Interface

The DQll provides a direct memory access interface between a PDP-11
and
a
serial
synchronous
line.
The
direct memory access
characteristic of the DQll allows the device to operate at speeds
higher than those of program interrupt devices, and with a lower
interrupt overhead. Modem control of the DQll allows the device to be
used in switched or dedicated configurations.
The DQll handles data rates from 2400 baud to 1,000,000 baud.
The
limiting rate is determined by the modem and data set interface level
converters.
The DQll sync character is programmable in the same manner as the DPll
and the DUll.
The maximum data block length transmitted is 65,536
characters.

12.1.6

DUll Synchronous Line Interface

The DUll synchronous line interface is a single-line communications
device that provides a program-controlled interface between the PDP-11
and a serial synchronous line. The PDP-11 can be interfaced with a
high-speed line to perform remote batch processing, remote data
collection, and remote concentration applications. Modem control is a
standard feature of the DUll and allows the device to be used in
switched or dedicated configurations. The DUll transmits data at a
maximum rate of 9600 baud; this rate is limited by modem and data set
interface level converters.
The DUll can be programmed to accept any user-defined sync character.
The use of the sync character is the same for the DUll and the DPll.

12-3

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12.1.7

DUPll Synchronous Line Interface

The DUPll is identical to the DUll, except that
hardware to perform cyclic redundancy checking.

12.2

incorporates

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive
(the first characteristics word)
contains the following
information for message-oriented communication interfaces.
A bit
setting of 1 indicates that the described characteristic is true for
the interfaces described in this chapter.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Words 3 and 4 are undefined, and word 5 has a special meaning for the
DLll-E, DQll, DPll, and the DUll interfaces.
Byte 0 of word 5
contains the number of sync characters to be transmitted before a
synching message {for example, after line turn-around in half-duplex
operation), and byte 1 is used as a sync counter.

12-4

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12 • 3

QIO MACRO

This section summarizes the standard and device-specific functions of
the QIO macro that are valid
for
the communication interfaces
described in this chapter.

12.3.1

Standard QIO Functions

Table 12-2 lists the standard functions of
valid for the communication devices.

the

QIO

macro

that

are

Table 12-2
Standard QIO Functions for Communication Interfaces
Function

Format
QIO$C IO.ATT, •••

Attach devicel

QIO$C IO.DET, •••

Detach device

QIO$C IO.KIL, •••

Cancel I/O requests

QIO$C IO.RLB, ••• ,<stadd,size>

READ logical block (stripping
sync)

QIO$C IO.WLB, .•• ,<stadd,size>

WRITE logical block {preceded by
syncs)

1. Only unmounted channels may be attached.
An attempt to attach
a mounted channel will result in an IE.PRI status being returned
in the I/O status doubleword.
stadd
The starting address of the data
boundary) •

buffer

(may

byte

size
The data buffer size in bytes (must be greater than 0).

12.3.2

Device-Specific QIO Functions

The specific functions of the QIO macro that are valid
communication line interfaces are shown in Table 12-3.

12-5

for

the

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 12-3
Device-Specific QIO Functions for Communication Interfaces
Function

Format
QI0$C IO.FDX

Set device to full-duplex
Not applicable to DAll-B

mode;

QIO$C IO.HDX, ••• ,<stat,mode>

SET device to half-duplex
Not applicable to DAll-B

mode;

QIOSC IO.INL, •••

Initialize device
characteristics

device

QIO$C IO.RNS, ••• ,<stadd,size>

READ
logical
block,
without
stripping
sync
characters
(transparent mode); Not applicable
to DQll;
for DAll-B and DMCll,
treated like IO.RLB

QIO$C IO.SYN, ••• ,<syn>

SPECIFY sync character; not
applicable to DAll-B or DMCll

QIO$C IO.TRM,...

Terminate communication,
disconnecting from physical channel

QIO$C IO.WNS, ••• ,<stadd,size>

WRITE
logical
block
without
preceding
sync
characters
{transparent mode);
for DAll-B and
DMCll, treated like IO.WLB

and

set

stadd
The starting address of
boundary) •

the

data

buffer

{may

byte

size
The data buffer size in bytes (must be greater than 0).
syn
The sync character, expressed as an octal value.
stat
The station assignment {primary or secondary).
mode
The transmission mode (normal or maintenance) •
The device-specific functions listed in Table 12-3
greater detail below.

12-6

are

described

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12.3.2.1 IO.FOX - The IO.FOX QIO function is used to set the mode on
a DLll-E, DPll, DQll, DUll, DUPll, or DMCll unit to full-duplex.
The
IO.FDX function code can be combined (ORed) with the
IO.SYN function
code,
if desired, to set the operational characteristics of the
physical device unit.

12.3.2.2 IO.BOX - The IO.HDX QIO function is used to set the mode on
a DLll-E, DPll, DQll, DUll, DUPll, or DMCll unit to half-duplex.
The
IO.HDX function code can be combined (ORed together) with the
IO.SYN
function code,
if desired, to set the operational characteristics of
the physical device unit.
Setting half-duplex on the DMCll also
involves setting the station
assignment
(primary/secondary)
and may include selecting maintenance
mode (MOP) as opposed to normal mode.
The station assignment is
included
in optional QIO parameter pl.
A 0 indicates primary station
and a nonzero indicates secondary station. The DMCll works properly
if both ends are primary stations or if there is one primary and one
secondary station.
It does not work if both ends are secondary
stations.
Optional QIO parameter p2 is used to select the mode. A 0
selects normal mode and a nonzero selects MOP mode.
A DMCll in MOP
mode cannot communicate with a DMCll in normal mode.

12.3.2.3 IO.INL and IO.TRM - These two QIO functions have the same
function code but different modifier bits.
IO.INL is used to
initialize a physical device unit for use as a communications link.
It turns the device on line, sets device characteristics, and ensures
that the appropriate data terminal is ready.
IO.TRM disconnects the
device.
If the device has a dial-up interface, it also hangs up the
line.

12.3.2.4 IO.RNS - The IO.RNS QIO function i~ used to read a
logical
block of data, without stripping the sync characters that may precede
in
the data. A similar function is IO.RLB, which is nontransparent,
that it causes sync characters preceding the data message to be
IO.RLB is used at the start of a segmented data request, in
stripped.
which the block might have the following layout:

DATA
2

Ics I

8
ZK-007-81

s
A sync character.
H

A header character.

cs
A validity check character.

12-7

MESSAGE-ORIENTED COMMUNICATION DRIVERS
The programmer must strip sync characters from the beginning of a data
block in this way. Stripping only at the beginning of a read allows a
later character which happens to have the same binary value as a sync
character to be read without stripping. IO.RLB is used to read a
logical block with leading sync characters stripped; IO.RNS is used
to read the block without stripping leading sync characters. Since
the DAll-B is a parallel device and there are no sync characters, it
treats the latter as if it were IO.RLB. Generally, IO.RLB should be
used.

12.3.2.5 IO.SYN - This QIO function allows the programmer to specify
the sync character to be recognized when an IO.RLB or IO.WLB function
is performed. IO.SYN can be combined (ORed together) with IO.HDX or
with IO.FDX to set the characteristics of the physical device unit.

12.3.2.6 IO.WNS - This QIO function causes a logical block to be
written with no preceding sync characters. To ensure that the two
systems involved in a communication are synchronized, two or more sync
characters are transmitted by one system and received by the other
before any other message can be sent. IO.WLB is used to write a block
of data, preceded by sync characters; IO.WNS is used to perform a
block transfer without sending sync characters first.
Since the
DAll-B is a parallel device and there are no sync characters, it
treats the latter as if it were IO.WLB. Generally, IO.WLB should be
used.

12.4

STATUS RETURNS

The error and status conditions listed in Table 12-4 are
the communication drivers described in this chapter.

returned

Table 12-4
Communication Status Returns
Code

rs. sue

Reason
Successful completion
The operation specified in the QIO directive was
The second word of the I/O
completed successfully.
status block can be examined to determine the number
of bytes processed, if the operation involved reading
or writing.

I IS. PND

I I/O request pending
The operation specified in the QIO directive has not
yet been executed.
The I/O status block is filled
with Os.
(continued on next page)

12-8

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 12-4
(Cont.)
Communication Status Returns
Code

Reason
Block check error

IE.BCC

When the Cyclic Redundancy Check
(CRC)
option is
present on the DQll, a check character is appended to
each message transmitted.
The receiver of
the
messages
recalculates
the
check character and
compares it with the one transmitted.
This error
code is returned when the two check characters do not
I

IE.CNR

:::::~t::: ::::::::ts a transmission error.

(DMCll only.) The DMCll has detected that the device
on the other end of the line has restarted itself.
The user can recover by issuing IO.INL
(initialize),
and then reissuing the QIO in question.
IE.DAO

Data overrun
Due to UNIBUS traffic or a modem problem, the DQll
controller was unable to maintain the data rate
required to prevent data loss (that is, the receipt
of another byte before processing of a previous byte
was completed) •

IE.DNR

Device not ready
The physical device unit specified
in the
QIO
directive was not ready to perform the desired I/O
operation.
This code is returned to indicate one of
the following conditions:
•

The physical device unit could not be initialized
(that is, the circuit could not be completed).

•

The transmission of a character was not followed
by an interrupt within the period of time selected
as the device time-out period.
This time-out
occurs only when a transmission is in progress and
the interrupt marking completion of a message does
not occur.
The appropriate response to this
condition is to attempt to resynchronize the
device by initializing and accepting the next
request. A time-out does not occur on a read.
If
the rece1v1ng device is not ready, the transfer
will not be initiated by the transmitting device.
Once the transfer is initiated, however, it will
complete either by satisfying the requested byte
count or by timing out.
(continued on next page)

12-9

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 12-4
(Cont.)
Communication Status Returns
Code
IE.IFC

Reason
Illegal function
A function code was specified in an I/O request that
is
illegal
for
message-oriented
communication
devices.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line. When
the system was booted, a device check indicated that
this
physical
device
unit
was
not
in the
configuration.

IE.SPC

Illegal address space
The buffer specified for a read or write request was
partially or totally outside the address space of the
issuing task.
Alternatively, a byte count of 0 was
specified.

IE.VER

Nonrecoverable error (DAll-B only)
The data transfer terminated before all of the data
has been transmitted.
The error.code is returned on
transmit when both systems attempt to transmit at the
same time.
This condition is detected by the device
protocol.
The error code is returned on receive when
the transmit data count of the transmitting side does
not equal the data count specified by the receive
QIO.

IE.ABO

Operation Aborted
The specified I/O operation was canceled by IO.KIL
while in progress or while still in the I/O queue.

IE.RSU

Sharable Resources in use
The task attempted to allocate
Unibus
Mapping
Registers.
All UMRs were allocated to other tasks
and were unable to complete the transfer.

IE.TMO

Timeout Error
The physical device unit associated with the LUN
specified
in the QIO directive timed out.
This
occurs during a data transfer operation when the task
does not receive an interrupt within a specified
amount of time.

12-10

MESSAGE-ORIENTED COMMUNICATION DRIVERS

12.5

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the message-oriented communication
interfaces described in this chapter.

12. 5.1

•Transmission Validation

Because there is no way for the transmitting device to verify that the
data block has successfully arrived at the receiving device unless the
receiver responds, the transmitter assumes that any message that is
clocked out on the line (without line or device outage) has been
successfully transmitted. As soon as the receiver is able to satisfy
a read request, it returns a successful status code (IS.SUC) in the
I/O status block. Of course, only the task receiving the message can
determine
whether
the
message
has actually been transmitted
accurately.
The receiving device should be ready to receive
request) at the time the transmission is sent.

12.5.2

data

(with

read

Redundancy Checking

By the nature of message-oriented communications, only the task that
receives a communication can determine whether the message was
received successfully. The transmitter simply transfers data, without
validation of any kind.
It is therefore the responsibility of the
communicating tasks which use the device to check the accuracy of the
transmission. A simple validity check is a checksum-type longitudinal
redundancy check. A better approach to validating data is the use of
a cyclic redundancy check (CRC)
A CRC can be computed in software or
with a hardware device, such as the KG-11 communications arithmetic
option.
5

Both DQll and DUPll incorporate hardware to compute a CRC.
CRC hardware requires an extra system unit.

12.5.3

The

DQll

Half-Duplex and Full-Duplex Considerations

Because there is a single I/O request queue, only one QIO request can
be performed at a time. It is therefore not possible, through QIOs,
for a device to send and receive data at the same time.
Also, since
timeouts are not set for receive functions, a receive QIO is
terminated only by receiving a message from the remote system, or by
issuing an IO.KIL QIO for the device. Therefore, if no message is
transmitted by the remote system, a receive will not terminate, and no
further I/O can be performed on that device until the receive is
killed by issuing an IO.KIL QIO.
Both half-duplex and full-duplex lines can be used with the DLll-E,
DMCll, DPll, DQll, DUll, and DUPll. The mode is settable by using
IO.FDX for full-duplex and IO.HDX for half-duplex.
In half-duplex
mode, the modem signal RTS (Request To Send) is cleared after each
"transmit message." In full-duplex, this signal is always left on.
Using full-duplex mode eliminates modem delays in transmission, but
requires full-duplex hardware and communication links.

12-11

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Only half-duplex mode is available with
nature of the hardware.

the

DAll-B

because

the

The DMCll Driver maintains both transmits and receives separately in
its own internal queues.
Thus, it is a full-duplex driver.
There is
no limit on the number of outstanding I/O requests that can be active
at any given time.
The DMCll hardware, however, allows a maximum of
only seven transmits and seven receives to be active at any time.
The
driver gives the first seven transmits (or receives) direct~y to the
DMCll and queues the eighth and subsequent transmits
(or receives)
internally until
the DMCll acknowledges a successful I/O request.
When running on an 11/70, the driver gives only two transmits
(or
receives)
to the DMCll because each request requires a UNIBUS mapping
register.
The DMCll driver is assigned
five UMRs:
one for base
table(s), two for active transmits, and two for active receives.

12.5.4

Low-Traffic Sync Character Considerations

If message traffic on a line
is low, each message sent from a
communications device should be preceded by a
sync train.
This
enables the controller to resynchronize if a message is "broken" (that
is,
part or all of it is lost in transmission).
Correspondingly,
every message received by a communications device under low-traffic
conditions, when messages are not contiguous (back-to-back), should be
read with an IO.RLB (read, strip sync) function.
This requires that
the first character in the data message itself not have the binary
value of the sync character.

12.5.5

Vertical Parity Support

Vertical parity is not supported by the DAll-B,
DUll.
Codes are assumed to be 8-bit only.

12.5.6

DLll~E,

DPll, DQll, or

Powerfail with DMCll

The DMCll currently cannot recover after a power failure because the
RAM in
its
internal microprocessor is erased when power fails.
Any
I/O requests outstanding at the time of a power failure will
return
IE.ABO.
These requests must be reissued after initializing the DMCll
(IO.INL).

12.5.7

Importance of IO.INL

After the type of communication line has been determined, and after
IO.SYN has specified the sync character, it is extremely important
that IO.INL be issued before any transfers occur.
This ensures that
appropriate parameters are initialized and
that the interface is
properly conditioned. Note that IO.INL provides the only means of
setting device characteristics,
such as sync character.
For this
reason, IO.INL should always be used immediately prior to the first
transfer over a newly activated link.

12-12

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Tasks sending messages to the DMCll should begin by terminating and
reinitializing the device (IO.TRM,IO.INL) .1
IO.INL must be issued
after each IO.KIL
(which effectively kills the
DMCll),
after
power-fail, and upon receipt of any error code.

12.6

PROGRAMMING EXAMPLE

The following example illustrates the initialization,
device
parameters, and transmission of a block of
message-oriented communication device.

TXAST:

setting of
data on a

.MCALL

ALUN$S,QIO$S

ALUN$S
QIO$S
QIO$S
QIO$S

ll,#"XP,#0
; USE LUNl FOR DPll
#IO.HDX!IO.SYN,<#1,,,,,#226> ; SET DEVICE PARAMETERS
#IO.INL,#1
; PUT DEVICE ON LINE
#IO.WLB,#1,,,<#TXSTS,#TXAST,#TXBUF,#lOO>; SEND A BLOCK

CMPB

#IS.SUC&377,@(SP)+

BEQ

10$

WAS DATA CLOCKED OU
SUCCESSFULLY?
IF SO, SET UP FOR NEXT
BLOCK

1. Note that this will cause the error IE.CNR to be
I/O outstanding on the other end of the line.
12-13

returned

any

CHAPTER 13
PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

13.1

INTRODUCTION

PCLll Parallel Communications Link
hardware
is
supported
on
RSX-llM-PLUS
systems by two drivers.
One driver supports the
transmitter function and the other driver supports the receiver
function.
The PCLll-B is a hardware interface that functions as a
time division multiplexed (TDM) interface over which several PDP-11
computers can transfer data to each other.
Each PCLll-B consists of a
transmitter, receiver, and master section.
The transmitter section
can transfer parallel 16-bit words along the TOM bus to a receiver
section of a separate PCLll-B on a different PDP-11 computer's UNIBUS.
One of the PCLll-B units attached to the TDM bus must have its master
section enabled to effect the data transfer.

13.1.1

PCLll-B Hardware

Each PCLll-B transmitter and receiver section has a
unique TDM bus
address
(hardware-configured).
When a master section is enabled, it
places a transmitter address on the TOM bus for a period of time,
called a timeslice. During the timeslice, the addressed transmitter
can address the desired receiver section and transmit one word;
the
transmitter waits for the receiver to acknowledge the word or an
indication that the word was not accepted.
If the word is not
accepted,
it will normally retransmit the word on the next available
timeslice.
Thus, a message up to 32k words long can be transmitted to
a
receiver one word at a time during the time in which other similar
TDM transactions are multiplexed for other PCLll-B devices.

13.1.2

PCLll Transmitter Driver

The PCLll transmitter driver provides two basic functions.
First,
it
must receive data sent by the attached task and store it in a silo
buffer in the PCLll hardware.
Then, the driver passes proper receiver
address and command information to the PCLll transmitter hardware to
effect the actual transfer over the TDM bus.

13.1.3

PCLll Receiver Driver

The PCLll receiver driver also performs two basic functions.
First,
it must remove data from the receiver silo and send it to the
connected task.
In addition, the receiver driver must acknowledge a
transmitter when a data transmission is requested by that transmitter.
Subsequent requests by other transmitters on the TDM bus are ignored
until pll message transactions with the current transmitter are
completed.
13-1

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
13.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the Get LUN Information system
directive (the first characteristics word) contains the following
information for the PCLll transmitter and receiver drivers. A setting
of 1 indicates that the described characteristics is true for PCLll
transmitter and receiver drivers.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Word 3 contains device driver-specific information, as follows:
Transmitter driver:
The low byte of word 3 contains the number of transmit retries
remaining after completing the current data transmit function if
the current data transmit function attempt is not accepted by the
addressed receiver. The high byte of word 3 is undefined.
Receiver driver:
The low byte of word 3 contains the index of the current state of
the receiver driver.
These states are primarily used for
diagnostic purposes and are defined as follows:
Index Value
0

Meaning
No task is connected.

Task connected but not triggered.

Task triggered and
IO.ATF function.

13-2

waiting

for

IO.RTF

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
Index Value

Meaning

Task triggered and timed out while waiting for
IO.RTF or IO.ATF function.

-2

IO.ATF function is in progress.

-4

Task connected,
not triggered,
IO.ATF function in progress.

-6

An IO.RTF function is in progress.

The high byte of word 3 is undefined.
the default buffer size in bytes.
bytes.

13.3

and

has

Word 4 is undefined.
Word 5 is
For the PCLll, this value is 64

QIO MACRO -- PCLll TRANSMITTER DRIVER FUNCTIONS

13.3.1

Standard QIO Functions

Table 13-1 lists the standard functions of
valid for the PCLll transmitter driver.

the

QIO

macro

that

are

macro

that

Table 13-1
Standard QIO Functions for PCLll Transmitters
Format

13.3.2

Function

QIO$C IO. ATT, ..•

Attach device

QIO$C IO.DET, •••

Detach device

QIO$C IO. KIL, •••

Cancel I/O request

Device-Specific QIO Functions

Table 13-2 lists the device-specific functions of the QIO
are valid for the PCLll transmitter driver.

Table 13-2
Device-Specific QIO Functions for PCLll Transmitters
Format
QIO$C IO.ATX, .•• ,<stadd,size,
flagwd,id,retries,retadd>
f"'ITf"'l~f""'

~..LVY''-

Tf"'I
C'C"f""'
..L\..l•L...1.J.:1'-"t•••f

QIO$C IO.STC, ••• ,<stadd,size,
[state], [mode], ,retadd>

Function

Attempt message transmission
Sense

---.J...-- section status

ma;::;Lt:r

Set master section characteristics

13-3

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

stadd
The starting address of a data buffer.
(Its description
function is dependent upon the specific QIO function.)

and

The data buffer size in bytes.
(Its description and function
dependent upon the specific QIO function.)

size

flagwd
The value of the flagword that is to precede the message being
sent. The flags specify the desired receiver function as defined
by the user's protocol.
id
The identifier of the CPU to which the message is to be sent.
This identifier is the desired receiver's TDM bus address. It
appears in the high byte of the first word of the master section
I/O status block.
The identifier number is an octal value
contained in the high byte of the parameter word.
For example,
receiver number 1 is specified as 400, receiver number 2 is
specified as 1000, and so forth.
retries
The number of retries that will be attempted, following the first
attempt,
that will be performed if the first attempt is
unsuccessful, or upon detecting transmission errors or master
down conditions, before returning error status to the calling
task.
retadd
The starting address of a 7-word buffer into which the contents
of
the
six
transmitter
registers
and
the transmitter
master/maintenance register are moved prior to returning to the
calling task.
Information describing the contents of these
registers can be obtained by referring
to
the
hardware
documentation supplied with the PCLll option.
state
The desired state setting for the transmitter, as follows:
Parameter
Specified

State

SS.MAS

TDM bus master

SS.NEU

Neutral (default state)

13-4

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
mode
The desired mode setting for allocating transmitter timeslices on
the TDM bus, as follows:
Parameter
Entered

Mode
addr~ssing

MS.AUT

Auto

MS.ADS

Address silo

(default mode)

13.3.2.1 IO.ATX - This I/O function requests an attempt to transmit a
message to a specified CPU.
The message to be transmitted is
contained in a data buffer starting at the address specified in the
stadd parameter.
This address must be on a word boundary. The data
buffer size specified in the size parameter must be an even, positive
value.
The flagword parameter contains user-defined information that
the receiving task will use in determining whether to accept or reject
the message.
The id parameter is the receiver TDM bus address. The
task uses this address to direct a message to a specific CPU.
Other
parameters are as previously described.

13.3.2.2 IO.SEC - This I/O function is used to sense the master
section status. Upon successful completion of this function, the I/O
status block will contain a typical I/O status code (IS.SUC) return in
the
low
byte
of
the
first
word, and current Transmitter
Master/Maintenance Register (TMMR) contents in the second word, as
follows:

Status Code

Current TMMR Contents

NOTE
The optional isb parameter (see Section
1.5.1) must be included in this QIO
request.

13.3.2.3 IO.STC - This I/O function
sets
the
master
section
operational
characteristics.
IO.STC can only be issued by a
privileged task. Correct use of the function depends upon the current
(or specified) operating state of the master section and proper use of
parameters. Each parameter is used as described in the following
paragraphs.
Refer to all parameters in the sequence shown for a
correct interpretation of parameter usage.

13-5

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
State -- The state parameter determines the overall function of this
master section
(and transmitter and receiver sections) in the PCLll
communications link as it relates to the TDM bus.
The neutral state
(SS.NEU) places the master section in an inactive state where the unit
will send and receive messages in a normal manner, but the master
section cannot control transmitter timeslice allocation on the TDM
bus.
The master state
{SSeMAS)
designates this unit as TDM bus
master, enabling control of transmitter unit timeslice allotments on
the TDM bus; only one master section on the TDM bus can be designated
TDM bus master.
Mode -- The TDM bus master can allocate transmitter timeslices in one
of two ways:
auto address mode
(MS.AUT)
or address silo mode
(MS.ADS). When operating in the auto address mode (MS.AUT), which is
the default mode for the TDM bus master, equal timeslice allotments
are given to each transmitter unit;
transmitter unit addresses are
sequentially put on the TDM bus in descending order, one address for
each timeslice. When operating in the address silo mode,
transmitter
unit addresses are transmitted in a user-specified sequence, allowing
up to 50% of the timeslices to be allocated to one transmitter unit,
if desired.
The actual sequence of transmitter timeslice allocations for
the
address silo mode is set up in the user's task data buffer referenced
by the stadd parameter. Certain constraints must be observed when
specifying this information, as follows:

13.4

•

Each entry in the buffer is a byte
unit address.

containing

transmitter

•

At least 20 entries, but not more than 50 entries, must be
specified.
If less than 20 entries are specified, the driver
will repeat the entire sequence, as specified,
in order to
attain the required minimum of 20 addresses.
If more than 50
addresses are specified, no change in timeslice allocation
will be effected and an IE.VER error status will be returned
to the task.

•

Identical transmitter addresses in either adjacent bytes or in
first and last bytes should be avoided.
When identical
addresses appear in adjacent bytes in this manner, the driver
inserts invalid "pad" transmitter addresses between identical
addresses, effectively resulting in no-operation timeslices.

•

Transmitter addresses are decimal values ranging from 1 to 32
(inclusive)
which correspond to addresses implemented on the
actual transmitter unit hardware.

•

The size parameter must correctly specify the number of
address bytes contained in the buffer referenced by the stadd
parameter.

PCLll'TRANSMITTER DRIVER STATUS RETURNS

Table 13-3 lists PCLll transmitter
probable reasons.

driver

13-6

return

status

codes

and

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
Table 13-3
PCLll Transmitter Driver Status Returns
Code
IS. sue

Reason
Successful completion
The QIO function was successfully completed.
If
an IO.ATX function was completed, the second
status word contains
the
number
of
bytes
transferred;
the message was not truncated. If
an IO.SEC function was completed, the second
status word contains the current contents of the
master section's TMMR.

IS. TNC

Successful transfer but message truncated
The IO.ATX function was completed, but the message
was truncated by the receiver (the receiver buffer
is too small).
The transmitter unit
cannot
determine how many words were actually received by
the receiver unit; the second word of the I/O
status block contains the length of the requested
transfer, rather than the actual count of words
successfully received in the receiver's buffer.

IE. BAD

Bad parameter specification
A bad parameter specification was included in the
IO.ATX function, or an invalid state parameter or
TDM bus timeslice allocation addressing mode was
specified in the IO.STC function.
This error status is also returned when an IO.STC
function, issued to a TDM bus master operating in
the address silo mode, refers to a data buffer
containing
an
illegal series of transmitter
addresses. An illegal series of addresses occurs
when the number of entries specified for the
timeslice allocation, plus the required number of
pad addresses, either exceeds 50 or is less than

IE. DNR

Device not ready
This error status return occurs in response to an
IO.ATX function when one of the following occurs:
•

Power failure in this CPU.

•

Device time-out (no response from the addressed
receiver).

•

Receiver was too slow in accepting or rejecting
the transfer request.

•

The master section is inoperative. This error
status is returned only after the number of
retries specified in the IO.ATX function have
been attempted without success.
(continued on next page)

13-7

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
Table 13-3
(Cont.)
PCLll Transmitter Driver Status Returns
Code
IE.VER

Reason
Unrecoverable error
The IO.STC function state setting could not be
achieved because the task is not privileged or
another device is TOM bus master.

IE.SPC

Illegal user buff er
The buffer address specified in
the
IO.ATF
function
is outside of the issuing task's address
space.

IE.REJ

Transfer rejected
The data transfer request specified in the IO.ATX
function
was
rejected
by
the
addressed
receiver--based on the source CPU identifier of
the task issuing the request--and flagword.

IE.FLG

Event flag already specified
An event flag was
IO.STC function.

IE.BBE

previously

specified

Transmission error
This error status is returned only after the
number of retries specified in the IO.ATX function
have
been
attempted
without
a
successful
transmission.
(Cycle redundancy check errors or
parity errors have been detected on each attempt.)

IE.ABO

Request terminated
This status is returned when a pending
I/O
function has been aborted in response to an IO.KIL
function being issued by the task.

IE.IFC

Illegal function
A function code was specified in an I/O
that is illegal for PCLll transmitters.

13.5
13.5.1

request

QIO MACRO -- PCLll RECEIVER DRIVER FUNCTIONS
Standard QIO Functions

Table 13-4 lists the standard function of the QIO macro that is
for the PCLll receiver driver.

13-8

valid

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
Table 13-4
Standard QIO Functions for PCLll Receivers

13.5.2

Format

Function

QIO$C IO.KIL, •••

Cancel I/O request

Device-Specific QIO Functions

Table 13-5 lists the device-specific functions of the QIO
are valid for the PCLll receiver driver.

macro

that

Table 13-5
Device-Specific QIO Functions for PCLll Receivers
Format

Function

QIO$C IO.CRX, ••• ,<tef,bufadd>

CONNECT for reception

QIO$C IO.RTF, •••

Reject transfer

QIO$C IO.ATF, ••• ,<stadd,size,
retadd>

Accept transfer

QIO$C IO.DRX, •••

Disconnect from reception

tef
The number of a "trigger" event flag that will be set whenever
flagword is received over the TDM bus.

bufadd
The address of a 2-word buffer containing
trigger status, and the flagword.

the

transmitter

id,

st add
This

The address of a data buffer to receive the message.
address must occur on a word boundary (even address) •
size
The data buffer size in bytes._
even, positive value.

The size

specified

must

retadd
The address of a 6-word buffer into which the contents of the six
PCLll
receiver
hardware
registers will be returned upon
successful completion of the function.
Information describing
the contents of these registers can be obtained by referring to
the hardware documentation supplied with the PCLll option.

13-9

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
13.5.2.1 IO.CRX - This I/O function connects the issuing task to the
receiver, if the receiver is not currently connected to another task.
When connected, this task is the only task capable of receiving
messages by means of the receiver on this CPU. The trigger event flag
(a local, common, or group-global event flag) informs the task when a
message is pending.
It is set when a flagword is received over the
TDM bus. When this happens, a significant event is declared and the
connected task is considered "triggered." The flagword is the first
word transmitted by a transmitter when attempting to send a message to
the receiver unit.
The bufadd parameter must be included in this I/O function to
the address of a 2-word block, as follows:
id

specify

sts
f lagwd

sts
The current trigger status.
id
The identification code of the transmitter attempting to send the
message.
f lagwd

The flagword transmitted to the connected receiver.
Based on the information contained in the
flagword
and
the
identification code of the transmitter unit, the task can accept or
reject the transfer.
(Two I/O functions are provided for this
purpose;
see Sections 13.5.2.2 and 13.5.2.3.} The receiver must
respond to the transmitter's request within approximately 1.5 seconds;
otherwise, an IE.DNR error status is returned to the task attempting
the transmission.

13.5.2.2 IO.RTF - This function informs the transmitter device that
the message is being rejected by the receiver. Any attempt to issue
this I/O function when the trigger event flag is not set will be
ignored, and an IE.NTR error status will be returned to the task.

13.5.2.3 IO.ATF - This function informs the transmitter device that
the message is being accepted.
Parameters specify both the data
buffer into which the received data will be transferred, and the
6-word buffer that will receive the contents of the receiver section
hardware registers upon successfully completing the function.
Unlike the IO.RTF function, the IO.ATF function can be issued before
the task is triggered.
When this is done, the IO.ATF function is
queued for reception of any flagword. When the flagword is received,
the receiver driver immediately executes the IO.ATF function; the
connected task is not triggered and the flagword is not made available
to the task.
This approach is useful when it is not necessary to
examine flagwords or to accept messages based on the source.

13-10

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

13.5.2.4

IO.DRX - This function is issued by a task to disconnect the
receiver for use by other tasks.

13.6

PCLll RECEIVER DRIVER STATUS RETURNS

Table 13-n lists
probable reasons.

PCLll

receiver

driver

return

status

codes

and

Table 13-6
PCLll Receiver Driver Status Returns
Reason

Code

rs.sue

Successful completion
The I/O function or triggering of the task was
successfully
completed.
When this status is
returned upon completion of the
IO.ATF function,
the high-order byte of the first word in the I/O
status block contains the identification code of
the transmitter device that sent the flagword.
The second word of the I/O status block contains
the number of bytes transferred over the TDM bus.
When this status is returned as a
result of an
IO.CRX function, and the task being triggered, the
I/O status block contains information that enables
the task to accept or reject the message (see
Section 13. 5. 2.1).

IS.TNC

Successful transfer but message truncated
This I/O status is returned when the message is
terminated
because the
receiver
task message
buffer specified in the
IO.ATF function
is too
small to contain the message being received.
The
second word of the I/O status word contains the
number of bytes successfully transferred.

IE. BAD

Bad parameter specification
A bad parameter specification was included in
requested function.

IE.DNR

the

Device not ready
This error status return occurs in response to an
IO.RTF
or
IO.ATF function when one of the
following occurs:
•

Power failure in this CPU.

•

Device time-out
receiver).

•

Receiver was too slow in accepting or rejecting
the transfer request.

•

The master section is inoperative.

(no

response

from

addressed

(continued on next page)

13-11

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
Table 13-6
(Cont.)
PCLll Receiver Driver Status Returns
Code
IE.SPC

Reason
Illegal user buffer
The buffer address specified
in
the
IO.ATF
function
is outside of the issuing task's address
space.

IE.DNA

Task not connected for reception
The requested function cannot be executed because
the task is not connected to the receiver.

IE.DAO

Data overrun
This I/O status code is returned when the task is
triggered, but the previous transfer request has
neither been accepted nor rejected. When the task
issues an IO.RTF or IO.ATF function, it will apply
to the new (most recent) flagword;
the previous
request is ignored.

IE.DAA

Device already connected for reception
This I/O status code is returned
in response to
the
IO.CRX function when the receiver is already
connected to this task or any other task.
No
operation is performed.

IE.NTR

Task not triggered
This I/O status code is returned when a task
attempts to issue an IO.RTF function prior to the
task being triggered.

IE.BBE

Transmission error
This error status is returned when an IO.ATF
function
is in progress and a cycle redundancy
check error or parity error has been detected.

IE.ABO

Request terminated
This status is returned when a pending
I/O
function has been aborted in response to an IO.KIL
function being issued by the task.

IE.FHE

Fatal hardware error
The requested function cannot be executed
of a hardware failure.

IE.IFC

because

Illegal function
A function code was specified in an I/O
that is illegal for PCLll transmitters.

13-12

request

CHAPTER 14
ANALOG-TO-DIGITAL CONVERTER DRIVERS

14.1

INTRODUCTION

The AFCll and ADOl-D analog-to-digital (A/D) converters are used to
acquire industrial and laboratory analog data.
(AFCll and ADOl-D
driver support is not provided on RSX-llM-PLUS systems.) Although each
has its own driver, programming for both is quite similar and both are
multichannel, programmable gain devices.
The ADOl-D should not be
confused with the ADUOl, a UDC module, which is described in Chapter
15. Table 14-1 compares the AFCll and the ADOl-D briefly, and
subsequent sections describe these devices in greater detail.
Table 14-1
Standard Analog-to-Digital Converters
AFCll

ADOl-D

Maximum Sampling Rate (Points
per Second)

200 (20 per single)
channel

Approximately
10,000

Number of Bits

13 or 14

10 or 11

Maximum Number of Analog Channels
That Can Be Multiplexed

1024

14.1.1

AFCll Analog-to-Digital Converter

The AFCll is a differential analog input subsystem for
industrial
data-acquisition and control systems.
It multiplexes signals, selects
gain, and performs a 13- or 14-bit analog-to~digital conversion under
program control.
With the use of appropriate signal-conditioning
modules, the system can intermix and accept low-level, high-level, and
current inputs, with a high degree of noise immunity.

14.1.2

ADOl-D Analog-to-Digital Converter

The ADOl-D is an extremely fast analog data-acquisition system.
It
multiplexes signals, selects gain, and performs a 10- or 11-bit
analog-to-digital conversion under program control.
The ADOl-D is

normally

unipolar,

but

optional

operation.

14-1

sign-bit

facilitates

bipolar

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.2

GET LUN INFORMATION MACRO

If a GET LUN INFORMATION system directive is issued for a LUN
associated with an analog-to-digital converter, word 2 (the first
characteristics word) contains all Os, words 3 and 4 are undefined,
and word 5 is not significant, since there is no concept of a default
buffer size for analog-to-digital converters.

14.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
analog-to-digital converter drivers.

14.3.1

Standard QIO Function

The standard function that is valid for
is shown in Table 14-2.

analog-to-digital

converters

Table 14-2
Standard QIO Function for the A/D Converters
Format

Function

QIO$C IO.KIL, •••

Cancel I/O requests

Since all requests are processed within a small amount of time, no
in-progress request is ever canceled. This function simply cancels
all queued requests.

14.3.2

Device-Specific QIO Function

The device-specific function of the QIO macro that
analog-to-digital converters is shown in Table 14-3.

valid

for

Table 14-3
Device-Specific QIO Function for the A/D Converters
Format

Function

QIO$C IO.RBC, ••• ,<stadd,size,stcnta>

INITIATE multiple A/D
conversions

stadd
The starting address of the
boundary).

data

14-2

buffer

(must

word

ANALOG-TO-DIGITAL CONVERTER DRIVERS
size
The control buffer size in bytes (must be even and
O); the data buffer is the same size.

greater

than

stcnta
The starting address of the control buffer (must be on a word
boundary); each control buffer word must be constructed as shown
in Table 14-4.
Table 14-4
A/D Conversion Control Word
Bits

Meaning

0-11

Channel number

Range:

12-15

Gain value for this
sample, expressed as
a bit pattern as
follows:

Gain:

0
0
0

0
0
0
0
1
1
1
1
0
0
0
0

0
0
1
1
0
0
1
1
0
0
1
1
0
0
1
1

0
1
0
1
0
1
0
1
0
1
0
1
0
1

0
0

0
0
1
1
1
1
1
1

1
1

14.4

1
1
1

ADOl-D

AFCll
0-1023

1
2
illegal
illegal
10
20
illegal
illegal
50
100
illegal
illegal
200
1000
illegal
illegal

Range:

0-63

Gain:

1
2
4
8

illegal
illegal
I illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal

FORTRAN INTERFACE

A collection of FORTRAN-callable subroutines provide FORTRAN programs
access to the AFCll and the ADOl-D. These are described in this
section. All are reentrant and may be placed in a resident library.

14.4.1

Synchronous and Asynchronous Process Control I/O

The ISA standard provides for synchronous and asynchronous I/O.
Synchronous I/O is indicated by appending a "W" to the name of the
subroutine (for example, AISQ/AISQW). The synchronous call suspends
task
execution
until the I/O operation is complete.
If the
asynchronous form is used, execution continues and the calling program
must periodically test the status word for completion.

14-3

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.4.2

The isb Status Array

The isb {I/O status block) parameter is a 2-word
integer array that
contains the status of the FORTRAN call,
in accordance with ISA
convention.
This array serves two purposes:
l.

It is the 2-word I/O status block to which the driver returns
a status code on completion of an I/O operation.

The first word of isb receives a status code from the FORTRAN
interface in ISA-compatible format, with the exception of the
I/O pending condition, which is indicated by a status of O.
The ISA standard code for this condition is +2.

The meaning of the contents of isb varies, depending on the FORTRAN
call that has been executed;
but Table 14-5 lists certain general
principles that apply.
The section describing each
subroutine
provides further details.
Table 14-5
Contents of First Word of isb
Contents

Meaning

isb{l)

Operation pending;

isb{l)

Successful completion

isb{l)

Interface
subroutine
unable
to
generate QIO directive, or number of
samples is 0

I/O in progress

< isb{l) < 300

QIO
directive rejected and
error code = -{isb(l) - 3)

actual

> 300

Driver rejected
request and
error code = -(isb(l) - 300)

actual

isb{l)

Unless otherwise specified, the value of isb{2) is the value
by the driver to the second word of the I/O status block.

returned

FORTRAN interface subroutines depend on asynchronous system traps to
set their status.
Thus,
if the trap mechanism is disabled, proper
status cannot be set.

14.4.3

FORTRAN Subroutine Summary

Table 14-6 lists the FORTRAN interface subroutines supported
AFCll and ADOl-D under RSX-llM.

14-4

for

the

ANALOG-TO-DIGITAL CONVERTER DRIVERS
Table 14-6
FORTRAN Interface Subroutines for the AFCll and ADOl-D
Subroutine

Function

AIRD/AIRDW

Perform input of analog data in random
s quence

AISQ/AISQW

Read a series
input channels

ASADLN

Assign a LUN to the ADOl-D

ASAFLN

Assign a LUN to the AFCll

sequential

analog

The following subsections briefly describe the function and format of
each FORTRAN subroutine call. Note the use of ASADLN and ASAFLN to
assign a default logical unit number.

14.4.4

AIRD/AIRDW: Performing Input of Analog Data in Random Sequence

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog
random sequence. These calls are issued as follows:

CALL

AIRD }
{ AIRDW

data

(inm,icont,idata, [isb], [lun])

inm
The number of analog input channels.
icont
An integer array containing terminal connection data-channel
number
(right-justified in bits 0-11) and gain (bits 12-15), as
shown in Table 14-4.
idata
An integer array to receive the converted values.
isb
A 2-word
returned.

integer

array

which

lun
The logical unit number.

14-5

the

subroutine

status

ANALOG-TO-DIGITAL CONVERTER DRIVERS
The isb array has the standard meaning defined in Section 14.4.2.
If
inm = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

14.4.5

AISQ/AISQW: Reading Sequential Analog Input Channels

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of
sequential analog input channels. These calls are issued as follows:

CALL {

AISQ

}

(inm,icont,idata, [isb], [lun])

AISQW

inm
The number of analog input channels.
icont
An integer array containing terminal connection data-channel
number (right-justified in bits 0-11) and gain (bits 12-15), as
shown in Table 14-4.
id a ta
An integer array to receive the converted values.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
For sequential analog input, channel number is computed in steps of
one, beginning with the value specified in the first element of icont.
The channel number field is ignored in all other elements of the
array.
The gain used for each conversion is taken from the respective element
in icont. Thus, even though the channel number is ignored in all but
the first element of icont, the gain must be specified for each
conversion to be performed.
The isb array has the standard meaning defined in Section 14.4.2.
If
inm = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

14-6

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.4.6

ASADLN: Assigning a LUN to the ADOl-D

The ASADLN FORTRAN subroutine assigns the specified LUN to the ADOl-D
and defines it as the default logical unit number to be used whenever
a LUN specification is omitted from an AIRD(W)/AISQ(W)
subroutine
call. It is issued as follows:
CALL ASADLN (lun,[isw],(iun])
lun
The logical unit number to be assigned to the ADOl-D and
as the default unit.

defined

An integer variable to which the result of the ASSIGN LUN
directive is returned.

system

isw

iun
The unit number to be assigned.
assumed.

If unspecified, a value of 0

Only the LUN specified in the last call to ASADLN or ASAFLN is defined
as the default unit.

14.4.7

ASAFLN: Assigning a LUN to the AFCll

The ASAFLN FORTRAN subroutine assigns the specified LUN to the AFCll
and defines it as the default logical unit number to be used whenever
a LUN specification is omitted from an AIRD(W)/AISQ(W) subroutine
call. It is issued as follows:
CALL ASAFLN (lun,[isw],[iun])
lun
The logical unit number to be assigned to AFCll
the default unit.

and

defined

An integer variable to which the
system directive is returned.

the

ASSIGN

LUN

If unspecified, a value of 0

isw
status

from

iun
The unit number to be assigned.
assumed.

Only the LUN specified in the last call to ASAFLN or ASADLN is defined
as the default unit.

14-7

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.5

STATUS RETURNS

The error and status conditions listed in Table 14-7 are returned
the analog-to-digital converter drivers described in this chapter.
Table 14-7
A/D Converter Status Returns
Reason

Code

rs.sue

IS.PND

I/O request pending
The operation specified in the QIO directive has not
yet been executed.
The I/O status block is filled
with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled with
while still in the I/O queue.

IE.BAD

IO.KIL

Bad parameter
An illegal specification was supplied for one or more
of the device-dependent QIO parameters (words 6-11}.
For the analog-to-digital converters, this
code
indicates that a bad channel number or gain code was
specified in the control buffer.

IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a data or control
buffer,
but
only word alignment is legal for
analog-to-digital converters.
Alternatively,
the
length of the data and control buffer is not an even
number of bytes.

IE.DNR

Device not ready
The physical device unit specified in the
QIO
directive was not ready to perform the desired I/O
operation.
For the AFCll, this code is returned
if
an interrupt time-out occurred or the power failed.
In the case of the ADOl-D, which is not operated
in
interrupt
mode,
this code indicates a software
time-out occurred (that is, a conversion did not
complete within 30 microseconds}.
(continued on next page)

14-8

ANALOG-TO-DIGITAL CONVERTER DRIVERS
Table 14-7 {Cont.)
A/D Converter Status Returns
Code
IE.IFC

Reason
Illegal function
A function code was specified in an I/O request
is illegal for analog-to-digital converters.

IE.OFL

that

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line. When
the system was booted, a device check indicated that
this
physical
device
unit
was
not
in the
configuration.

IE. SPC

Illegal address space
The data or control buffer specified for a conversion
request was partially or totally outside the address
space of the issuing task. Alternately, a byte count
of 0 was specified.

FORTRAN interface
Section 14.5.1.

14.5.1

values

for

these

subroutines

are

presented

FORTRAN Interface Values

The values listed in Table 14-8 are
calls.

returned

FORTRAN

Table 14-8
FORTRAN Interface Values
Status Return

FORTRAN Value

IS. sue
IS. PND

+01
+00
+315
+101
+301
+319
+313
+303
+100
+302
+99
+323
+305
+316
+317
+102
+306
+08
+04

IE.ABO
IE.ADP
IE.BAD
IE.BYT
IE.DAO
IE.DNR
IE.IEF
IE.IFC
IE. ILU
IE.NOD
IE.CNP
IE.PR!
IE.RSU
IE.SOP
IE.SPC
IE.ULN
IE.UPN

14-9

subroutine

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.6

FUNCTIONAL CAPABILITIES

The AFCll and ADOl-D operate only in multisample mode, because the
user can simulate single-sample mode by simply specifying one sample.
Multisample mode permits many channels to be sampled at approximately
the same time without requiring the user to queue multiple I/O
requests.
The maximum number of channels in the configuration is specified at
system-generation time.
This value is stored in the respective AFCll
and ADOl-D unit control blocks.

14.6.1

Control and Data Buffers

The user must define two buffers of equal size:
the control buffer
and the data buffer. The former contains the control words needed to
perform one A/D conversion per channel specified.
Each control word
indicates the channel to be sampled and the gain to be applied (see
Table 14-4).
The data buffer receives the results of the conversions.
Each result
is placed in the data buffer location that corresponds to the control
word that specified it.

14.7

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the analog-to-digital converter
drivers described in this chapter.

14.7.1

Use of A/D Gain Ranges

Note that the A/D gain ranges overlap.
The key to successful use of
the A/D converters is to change to a higher gain whenever a full-scale
reading is imminent, and to change to a lower gain whenever the last
A/D value recorded was less than half of full scale. This method
maintains maximum resolution while avoiding saturation.

14.7.2

Identical Channel Numbers on the AFCll

When requesting sampling of more than one channel, the user should not
specify multiple sampling of a single channel without 10 or more
intervening samples on other channels.
This ensures 50 milliseconds
between samples on a single channel.
If sampling occurs more often
than this on a single channel, partial results are returned
(see
Section 14.7.3}.

14-10

ANALOG-TO-DIGITAL CONVERTER DRIVERS
14.7.3

AFCll Sampling Rate

Although the AFCll can sample a maximum of 200 points per second, a
single channel can only be sampled at 20 points per second. Because
the channel capacitor needs 50 milliseconds to recharge after each
conversion, more frequent sampling may result in partial readings. If
this occurs, the user will receive no indication that information is
being lost.
To ensure that information is not lost on any one
channel, the user should sample approximately 10 other channels before
returning to the first one.

14.7.4

Restricting the Number of AD01-D Conversions

The ADOl-D is an extremely fast device, providing a 25-microsecond
conversion rate, and is driven programmably to minimize system
overhead. However, an excessive number of conversions in a single
request essentially locks out the rest of the system, because the
driver does not return control to the system until it has finished all
the specified conversions. No other task can run, although interrupts
can still occur and are processed.

14-11

CHAPTER 15
UNIVERSAL DIGITAL CONTROLLER DRIVER

15.l

INTRODUCTION

The UDCll is a digital input/output system for industrial and process
control applications.
It interrogates and/or drives up to 252
directly addressable digital sense and/or control modules.
The UDCll
operates under program control as a high-level digital multiplexer,
interrogating digital inputs and driving digital outputs.
(UDCll
driver support is not provided on RSX-llM-PLUS systems.)
The UDC driver will support either the UDCll or ICSll subsystem.
The
ICSll
{Industrial Control Subsystem)
operates as an input/output
device that is functionally similar to the UDCll.
A maximum of 16 I/O
modules can be placed in one ICSll subsystem;
up to 12 ICSlls can be
interfaced to one computer system.
The ICSll subsystem is also
supported by the ICS/ICR-11 driver described
in Chapter 18. The
reader should consult that chapter for a comparison of driver
features.
While performing analog-to-digital conversions, the UDCll driver can
handle other functions, such as contact or timer interrupts or
latching output.
These functions are performed immediately, without
requiring any in-progress analog-to-digital conversions to first be
completed.
Unlike other RSX-llM I/O device drivers, the UDCll driver is neither a
multicontroller nor a multiunit driver.

15.1.1

Creating the UDCll Driver

Each installation must assemble the driver source module with a prefix
file that defines the particular hardware configuration.
The prefix
file is created during system generation according to the user's
response to questions relating to the UDCll.
This file is named
RSXMC.MAC
and
includes
symbolic
definitions
of
the
UDCll
configuration.
These definitions encode the relative module number
and the number of modules for each generic type specified
in the
system generation dialog.
The encoding has the following format:
8
number of modules

8
starting module number

15-1

UNIVERSAL DIGITAL CONTROLLER DRIVER
One or more of the following symbols is generated:
Symbol
U$$ADM
U$$AOM
U$$CIM
U$$CSM
U$$LTM
U$$SSM
U$$TIM

Moduie Type
Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

Note that all modules of a given type must be
sequential slots.

15.1.2

installed

together

Accessing UDCll Modules

RSX-llM provides two methods of accessing the UDCll:
1.

A QIO macro call issued to the driver

Restricted direct access by any task to
dedicated to the UDCll

I/O

page

registers

The first method, access through the driver, is required to service
interrupting modules and to set and
record the state of latching
digital output modules.
The second method, direct access, is a high-speed, low-overhead way to
service noninterrupting modules.
The following functions may be
performed in this manner:
•

Analog output

•

Contact sense input

•

Single-shot digital output

•

Read a contact interrupt module

•

Read a timer module

15.1.2.l
modules:

Driver Services - The driver services the following types of

•

Contact interrupt

•

Timer (I/O counter)

•

Analog input

•

Latching digital output

Contact and timer interrupts need not be serviced
One task may be connected to contact interrupts,
interrupts. A nonprivileged task can connect to
these classes by providing a circular buffer
information and an event flag to allow triggering
a buffer entry is made.

15-2

by a single task.
and another to timer
either or both of
to receive interrupt
of the task whenever

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.1.2.2 Direct Access - A global common block within the I/O page
provides restricted direct access to the UDCll device registers.
In a
mapped system, the length of the block is set to prevent access to
other device registersa
In an unmapped system, the use of the common
block is optional, unless ISA FORTRAN calls are used.
The ISA
routines refer symbolically to the UCDll registers, and thus require
the use of global common.
Section 15.4 explains direct access more
fully.

15.2

GET LUN INFORMATION MACRO

If a GET LUN INFORMATION system directive is issued for a LUN
associated with the UDCll, word 2 (the first characteristics word)
contains all zeros, words 3 and 4 are undefined, and word 5 is not
significant, since there is no concept of a default buffer size for
universal digital controllers.

15.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the UDCll driver.
In issuing them, note the numbering conventions
described in 15.7.2.

15.3.1

Standard QIO Function

The standard function that is valid for the UDCll is
15-1.
Table 15-1
Standard QIO Function for the

shown

Table

UD~ll

Format

Function

QIO$C IO.KIL, •••

Cancel I/O requests

IO.KIL cancels all queued requests and disconnects all
interrupt
connections, but does not stop any I/O that is currently in progress.

15.3.2

Device-Specific QIO Functions

Table 15-2 summarizes device-specific QIO functions that are supported
for the UDC12.

15-3

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-2
Device-Specific QIO Functions for the UDCll
Format

Function

QIO$C IO.CCI, ••• ,<stadd,sizb,tevf>

CONNECT a buffer to contact
interrupts

QIO$C IO.CTI, ••• ,<stadd,sizb,tevf,arv>

CONNECT a buffer to timer
interrupts

QIO$C IO.DC!,...

Disconnect a buffer from
contact interrupts

QIO$C IO.DTI,...

Disconnect a buffer from timer
interrupts

QIO$C IO.ITI, ••• ,<mn,ic>

INITIALIZE a timer

QIO$C IO.MLO, ••• ,<opn,pp,dp>

OPEN or close latching digital
output points

QIO$C IO.RBC, ••• ,<stadd,size,stcnta>

INITIATE multiple A/D
conversions

stadd
The starting address of the
boundary) •

data

buffer

(must

word

sizb
The data buffer size in bytes (must be even and large
include a 2-word buffer header plus one data entry;
may cross a 4K boundary).

enough to
the buffer

tevf
The trigger event flag number.
arv
The starting address of the table of initial/reset
be on a word boundary) •

values

(must

mn
The module number.
ic
The initial count.
opn
The first latching digital output point number, which must be
a module boundary (evenly divisible by 16).

15-4

UNIVERSAL DIGITAL CONTROLLER DRIVER
pp
The ln-bit mask.
dp
The data pattern.
size
The control buffer size in bytes (must be even and
O);
the data buffer is the same size.

greater

than

stcnta
The starting address of the control buffer (must be on a word
boundary); each control buffer word must be constructed as shown
in Table 15-3.
The following sections describe the functions listed in Table 15-2.
Table 15-3
A/D Conversion Control Word
Bits

Meaning

0-11

Channel number

Range: 0-4095

12-15

Gain value for this
sample, expressed as
a bit pattern as
follows:

Gain:

ADUOl

15
-

14
-

-13

12
-

0
0
0
0
0
0
0
0
1
1
1
1
1
1
1
1

0
0
0
0
1
1
1
1
0
0
0
0
1
1
1
1

0
0
1
1
0
0
1
1

0
1
0
1
0

0
1
1
0
0
1
1

0
1
0
1
0
1
0

1
0
1

15-5

1
2
Illegal
Illegal
10
20
Illegal
Illegal
50
100
Illegal
Illegal
200
1000
Illegal
Illegal

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.3.2.1 Contact Interrupt Digital Input {W733 Modules) - Digital
input and change of state information from contact interrupt modules
is reported in a requester-provided circular buffer.
The buffer
consists of a 2-word header, followed by a data area in the following
format:
1

2
3
4

driver index
user index
entry
entry

.
.
.

Whenever a change of state occurs in one or more contact points, an
interrupt is generated.
The UDCll driver gains control, determines
whether the change of state is of interest (that is, a contact closure
and point closing
(PCL)
is set on the module), and then optionally
makes an entry in the data area of the buffer, updates the index
words, and sets the trigger event flag of the connected task.
Each entry consists of five words in the following format:
Word

Contents

Entry existence indicator

Change-of-state (COS) indicator

Module data (current point values)

Module number (interrupting module)

Generic code (interrupting module)

The driver enters data in the location currently indicated by the
driver index. This pointer can be cons~dered as a FORTRAN index into
the bµffer;
that is, the first location of the buffer is associated
with the index 1. The beginning of the data area is the location of
the first entry (index 3). Entries are made in a circular fashion,
starting at the beginning of the data area, filling in order of
increasing memory address to the end of the data area, and then
wrapping around from the end to the beginning of the data area.
It is expected that the connected task will maintain its own pointer
(the user index)
to the location in the buffer where it is next to
retrieve contact interrupt data. When a task is triggered by the
driver,
it should process data in the buffer starting at the location
indicated by its pointer and continuing in a circular fashion until
the two pointers are equal or a zero entry existence indicator is
encountered. Equality of pointers means that the connected task has
retrieved all the contact interrupt information that the driver has
entered into the buffer.
The entry existence indicator is set to nonzero when a buffer entry is
made.
When a requester has removed or processed an entry, he must
clear the existence indicator in order to free the buffer entry
position.

15-6

UNIVERSAL DIGITAL CONTROLLER DRIVER
If data input occurs in a burst sufficient to overrun the buffer, data
is discarded and a count of data overruns is incremented. The nonzero
entry existence indicator also serves as an overrun indicator.
A
positive value (+l) indicates no overruns between entries; a negative
value is the two's complement of the number of times data have been
discarded between entries.
The module number indicates a module on which a change of state in the
direction of interest has been recognized for one or more discrete
points. The direction of the change may be from 0 to 1 or 1 to O,
depending on the PCL (point closing) and POP (point opening) module
jumpers. The change of state (COS) indicator specifies which point or
points of the module have changed state.
The bit position of an on-bit in the COS indicator provides the
low-order bits (3-0) of a point number and the module number provides
the high-order bits (15-4). The module data indicates the logical
value (polarity) of each point in the module at the time of the
interrupt.
Contact interrupt data can be reported to only one task.
The
functions IO.CCI and IO.DCI in Table 15-2 are provided to enable a
task to connect and disconnect from contact interrupts.
If the
connection is successful, the second word of the I/O status block
contains the number of words passed per interrupt in the low-order
byte and the initial FORTRAN index to the beginning of the data area
in the high-order byte.
NOTE
The size of the data area
multiple of the entry size.

must

15.3.2.2 Timer {W734 I/O Counter Modules) - A timer (I/O
counter)
module is a clock that is initialized (loaded), counts up or down, and
then causes an interrupt. The UDCll driver treats such modules in a
way similar to that in which it handles contact interrupts. The
requester provides a circular buffer similar to that for contact
interrupts.
Each entry consists of four words in the following
format:
Word

Contents

Entry existence indicator

Module data (current value)

Module number (interrupting module)

Generic code (interrupting module)

15-7

UNIVERSAL DIGITAL CONTROLLER DRIVER
The IO.CTI function in Table 15-2 enables a task to connect to timer
interrupts.
The table of initial/reset values is used to initially
load the timers and to reload them on interrupt (overflow).
The table
contains one word for each timer module.
The contents of the first
word are used to load the first module, and so forth.
If a timer has
a
nonzero value when it interrupts,
it is not reloaded, so that
self-clocking modules and modules that interrupt on half count can
continue counting from the initial value.
The IO.DTI function in Table 15-2 disconnects a task from timer
interrupts, and the IO.IT! function provides the capability of
initializing a single timer.
Requests to
initialize a counter are
valid only if the issuing task has connected a buffer for receiving
counter interrupts.
NOTE
The size of the data area
multiple of the entry size.

must

15.3.2.3 Latching Digital Output {M685, M803, and M805 Modules) Each module has 16 latching digital output points.
The IO.MLO
function in Table 15-2 opens or closes a set of up to 16 points.
Bit
n of the mask and data pattern corresponds to the point opn + n.
If a
bit in the mask is set, the corresponding point is opened or closed,
depending on whether the corresponding bit in the data pattern is
clear or set.
If a bit in the mask is clear, the corresponding point
remains unaltered.

15.3.2.4 Analog-to-Digital Converter (ADUOl Module) - Each
ADUOl
module has eight analog input channels.
The IO.RBC function in Table
15-2 initiates A/D conversions on multiple ADUOl
input channels.
Restrictions on maximum sampling rates are the same as those defined
for the AFCll in Chapter 14.
The converted analog value is returned as 12 bits, left-justified,
a 16-bit word with the low-order 4 bits set to o.

15.3.2.5 ICSll Analog-to-Digital Converter
(IAD-IA Module) - Each
IAD-IA Module has eight analog input channels.
The channel capacity
may be expanded to 120 by the addition of IMX-IA multiplexers.
Each
multiplexer adds 16 input channels to the converter. Restrictions on
maximum sampling rates are the same as those defined for the AFCll in
Chapter 14. The IAD-IA module preempts eight module slots regardless
of the number of IMX-IA multiplexers installed.
For addressing purposes, each converter occupies a block of 120
channels.
Thus, A/D converter 0 is addressed by referencing channels
O through 119; A/D converter 1 is addressed by referencing channels
120 through 239, and so forth. When fewer than seven multiplexers are
installed, not all addresses within the block are valid.
The converted analog value is returned as 12 bits, left-justified,
a 16-bit word with the low-order 4 bits set to 0.

15-8

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.4

DIRECT ACCESS

Section 15.1.2 describes UDCll functions that may be performed by
referencing a module through its physical address in the I/O page.
Under RSX-llM such access is accomplished· by one of the following
methods:
1.

A privileged task or any task running in an unmapped system
has unrestricted access to the I/O page, and may therefore
access each module by absolute address.

Using the Task Builder, a task may link to a global common
area whose physical address limits span a set of locations in
the I/O page. This method applies to either a mapped or
unmapped system.

The latter method allows a task to be transported to any other system
simply by relinking.
Furthermore, in a mapped system the memory
management hardware will abort all references to device registers
outside the physical address limits of the common block.
The operations required to implement each method may be summarized
follows:
1.

Unrestricted access to the I/O page
a.

An object module is created that defines the UDCll
configuration through a list of absolute global addresses
and addressing limits for each module type.

The object module is included in the system library file.

A task is created containing the appropriate global
references.
Such references are resolved when the task
builder automatically searches the system library file.

Steps a and b are executed once, during system generation (see the
RSX-llM System Generation and Management Guide). Step c is performed
each time a task 1s created---ui"at references the UDC12.
2.

Access to the I/O page through a Global Common Block
a.

An object module is created that defines the UDCll
configuration
through a list of relocatable global
addresses and addressing limits for each module type.

The object module is linked, using the Task Builder,
create an image of the Global Common block on disk.

The SET command is used to define
resides on the I/O page.

The INSTALL MCR command is used to make the Global Common
Block resident in memory.

A task is created containing the appropriate global
references.
Such references are resolved by directing
the Task Builder to link the task to the common block.

common

block

to
that

Steps a through d are executed once, during system generation. Step e
is performed each time a task is created that references the UDCll
common block. The following paragraphs describe each step in detail.

15-9

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.4.1

Defining the UDCll Configuration

The source module UDCOM.MAC,l when assembled with the proper prefix
file, provides global definitions for the following parameters:
•

The starting address of each module type

•

The highest point number within a given module type

•

The highest module number within a given module type

The last two parameters are absolute quantities that may be used to
prevent a task from referencing a module that is nonexistent or out of
limits.
By means of conditional assembly, the list of addresses may be created
as absolute symbols defining locations in the I/O page, or as symbols
within a relocatable program section to be used when building and
linking to the UDCll Global Common area.

assembled
15.4.1.1 Assembly Procedure for UDCOM.MAC - UDCOM.MAC is
with the RSX-llM configuration parameters contained in the file
RSXMC.MAC.
To create relocatable module addresses, either the parameter U$$DCM or
M$$MGE must be defined.
M$$MGE will be included in RSXMC.MAC if
memory management was specified when the system was generated.
If
not,
the user should edit the file to include the following
definition:
U$$DCM=O
The file may then be assembled using the MCR command:
>MAC UDCOM,UDLST=[ll,lO]RSXMC,UDCOM
This command invokes the MACR0-11 assembler, which processes the input
files RSXMC.MAC and UDCOM.MAC to create UDCOM.OBJ and UDLST.LST.
To create absolute module addresses, both U$$DCM and M$$MGE must be
undefined.
Edit RSXMC.MAC, if necessary, to remove definitions and
then invoke the MACR0-11 assembler with the following MCR command:
>MAC UDCDF,UDLST=[ll,lO]RSXMC,UDCOM
In this sequence the files UDCDF.OBJ and UDLST.LST are created from
the specified source modules. UDCDF.OBJ contains the module addresses
in absolute form.

15.4.1.2 Symbols Defined by UDCOM.MAC - This
symbolic definitions created by UDCOM.MAC.

section

lists

the

1. This module resides on the RK05 cartridge of the RSX-llM RK
distribution kit labeled EXECUTIVE SOURCE. For RP distribution kits,
it resides on the RP image. The file is located under UIC [11,10].
15-10

UNIVERSAL DIGITAL CONTROLLER DRIVER
The following symbols define the absolute or
the first module of a given type:

relocatable

address

Symbol

Module Type

$.ADM
$ .AOM
$.CIM
$.CSM
$.LTM
$.SSM
$.TIM

Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

The addresses in relocatable form are defined
named UDCOM having the attributes:
REL OVR D
GBL -

program

section

relocatable
overlaid
data
global scope

Note that these attributes correspond to those
common block within a FORTRAN program.
In either the absolute or relocatable case,
referenced by the corresponding symbolic
module index.

attached

named

individual modules are
address plus a relative

The following symbols define the highest digital point within a module
type:
Symbol

Module Type

P$.CIM
P$.CSM
P$.LTM
P$.SSM

Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output

The highest point number is defined relative to the first point on the
first module of a specific type.
For example, if two contact
interrupt modules are installed, the symbol P$.CIM will have an octal
value of 37.
The following symbols define the highest module number within a
module type.
Symbol

Module Type

MS.ADM
M$. AOM
M$. CIM
M$.CSM
M$.LTM
M$.SSM
M$.TIM

Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

given

The highest module number is defined relative to the first module of a
given type.
Thus, based on the previous example, M$.CIM will have a
value of L

15-11

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.4.2

Including UDCl Symbolic Definitions in the System Object
Module Library

As described in Section 15.4, a task having unrestricted access to the
I/O page may reference a UDCll module by absolute address. The object
module UDCDF contains symbolic definitions of
absolute
module
addresses and may be included in the System Object Module Library:
SY: [l, 1] SYS LIB. OLB
The Task Builder automatically searches this file to resolve any
undefined globals remaining after all input files have been processed.
The following example illustrates the procedure for including the file
UDCDF.OBJ in the library:
>SET /UIC=[l,l]
>LBR SYSLIB/IN=[200,200]UDCDF
The SET MCR command is issued to establish the current UIC as (1,1].
Next, the RSXllM Librarian is invoked and instructed, through the use
of the /IN switch, to include the object module UDCDF.OBJ in the file
SYS LIB. OLB.

15.4.3

Referencing the UDCll through a Global Common Block

The following sections define the procedure for creating a Global
Common block in the I/O PAGE, making the block resident in memory, and
creating a task that references UDCll modules within the block.
Examples are given for both mapped and unmapped systems.

15.4.3.1 Creating a Global Common Block - The
following
sequence
illustrates the use of the object file UDCOM.OBJ to create a disk
image of the global common area in a mapped system:
>SET /UIC=(l,l]
>TKB
TKB>UDCOM/MM,LP:,SY:UDCOM/PI/-HD=[200,200]UDCOM
TKB>/
ENTER OPTIONS:
TKB>PAR=UDCOM:O:lOOO
TKB>STACK=O
TKB>/
In the above example, a current UIC of (1,1] is established and the
Task Builder is initiated. The initial input line to the Task Builder
specifies the following files:
•

A core image output file to be named UDCOM.TSK

•

A memory map output to the line printer

•

A symbol table file to be named UDCOM.STB

All files reside on SY: under UIC [1,1].
The single input file
UDCOM.OBJ, containing the UDCll address definitions as relocatable
values, constitutes the input.

15-12

UNIVERSAL DIGITAL CONTROLLER DRIVER
The switches specified for the output
information to the Task Builder:

files

convey

the

following

/MM

indicates that the core image of the common block
reside on a system with Memory Management.

/PI

indicates that the core image is position independent;
that is, the virtual address of the common block may
appear on any 4K boundary within a task's address
space.

/-HD

indicates that the core image will not contain a
header.
A header is only required for a core image
file that is to be installed and executed as a task.

The names of the partition, task file,
agree.

and

symbol-table

will

files

must

The STACK option must be used to eliminate the stack space.
The following sequence illustrates the corresponding procedure for
unmapped system:

>SET /UIC=[l,l]
>TKB
TKB>UDCOM/-MM,LP:,SY:UDCOM/PI/-HD=[200,200]UDCOM
TKB>/
ENTER OPTIONS:
TKB>STACK=O
TKB>PAR=UDCOM:l71000:1000
TKB>/
Again the task builder is requested to produce a core image and symbol
table file under the UIC [1,1], and a map file on the line printer
from the input file UDCOM.OBJ. The output file switches convey the
following information:
/-MM

indicates that the core image of the common block
reside on an unmapped system.

will

/PI

Indicates that the core image is position independent.
In an unmapped system, the core image is fixed in the
same address space for all tasks; however, the global
symbols defined in the symbol table file retain the
relocatable attribute.

/-HD

indicates that a core image without a header is
created.

The PAR option specifies the ~ase and length of the common area to
coincide with the standard UDCll addresses in the I/O page. All
references to the common block by tasks will be resolved within this
region.

15.4.3.2 Making the Common Block Resident - The following SET command
creates a UDCll common block residing in the I/O page for a mapped
system:
>SET /MAIN=UDCOM:7710:10:DEV

15-13

UNIVERSAL DIGITAL CONTROLLER DRIVER
The corresponding command in an unmapped system is:
>SET /MAIN=UDCOM:l710:10:DEV
The preceding sequence specifies the allocation of a common block in
the I/O page whose physical address limits correspond to the UDCll
standard locations. Note that the address bounds and length are
defined in units of 32 words.
The command
>INS [l,l]UDCOM
declares the common block resident in the system.

15.4.3.3 Linking a Task to the UDCll Common Block - A task may access
UDCll modules by linking to the common block as follows:
TKB>TASK,LP:=TASK.OBJ
TKB>/
ENTER OPTIONS:
TKB> COMMON=UDCOM:RW
TKB>/
The above sequence is valid for either a mapped or unmapped system.
In both cases the Task Builder will link the task to the common block
by resolving references to the Global symbol definitions contained in
UDCOM.STB.
If memory management is present, the Executive will map
the appropriate physical locations into the task's virtual addressing
space when the task is made active.

15.5

FORTRAN INTERFACE

A collection of FORTRAN-callable subroutines provide FORTRAN programs
access to the UDC12. These are described in this section. All are
reentrant and may be placed in a resident library.
Instead of using the FORTRAN-callable subroutines described in this
section, a FORTRAN program may use the global common feature described
in Section 15.4 to reference UDCll modules directly in the I/O page,
as shown in the following example:

c
C

c
c

UDCll GLOBAL COMMON
COMMON /UDCOM/ ICSM(lO) ,IAO(lO)
READ CONTACT SENSE MODULE l DIRECTLY
ICS=ICSM(l)

Note that the position of each module type must correspond to
sequence in which storage is allocated in the common statements.

15-14

the

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.5.1

Synchronous and Asynchronous Process Control I/O

The ISA standard provides for synchronous and asynchronous process
I/O.
Synchronous I/O is indicated by appending a "W" to the name of
the subroutine (for example, AO/AOW). But due to the fact that nearly
all UDCll I/O operations are performed immediately, in most cases the
"W" form of the call is retained only for compatibility and has no
meaning under RSX-llM.
In the case of A/D input, however, the "W"
form is significant: The synchronous call suspends task execution
until input is complete. If the asynchronous form is used, execution
continues and the calling program must periodically test the status
word for completion.

15.5.2

The isb Status Array

The isb (I/O status block) parameter is a 2-word integer array that
contains the status of the FORTRAN call, in accordance with ISA
(Instrument Society of America) convention.
This array serves two
purposes:
1.

It is the 2-word I/O status block to which the driver returns
an I/O status code on completion of an I/O operation.

The meaning of the contents of isb varies, depending on the FORTRAN
call that has been executed; but Table 15-4 lists certain general
principles that apply. The section describing each subroutine gives
more details.
In some cases, the values or states of points being read,
latched are returned to isb word 2.

pulsed,

FORTRAN interface subroutines for analog input depend on asynchronous
system traps to set their status. Thus, if the trap mechanism is
disabled, proper status cannot be set.
Table 15-4
Contents of First Word of isb
Meaning

Contents
isb(l) = o

Operation pending;

isb(l) = 1

Successful completion

isb(l) = 3

Interface subroutine unable to generate
QIO
directive or number of points
requested is zero

3 < isb(l) < 300

I/O in progress

QIO directive rejected and actual error
- 3)

code = -(isb(lj

isb(l) > 300

Driver rejected request and
error code = -(isb(l) - 300)

15-15

actual

UNIVERSAL DIGITAL CONTROLLER DRIVER
For direct access calls (indicated in Table 15-5 below}, errors are
detected and returned by the FORTRAN interface subroutine itself,
rather than by the driver. Although the use of a 2-word status block
is therefore unnecessary, these errors are returned in standard format
to retain compatibility with functions called through QIO directives
and handled by other drivers.
Errors of this type that may be
returned are:
isb(l} = 3

Number of points requested is
0

isb(l)

15.5.3

+321

Invalid UDCll module

FORTRAN Subroutine Summary

Table 15-5 lists the FORTRAN interface subroutines supported for the
UDCll under RSX-llM.
(D)
indicates a direct access call, and the
optional logical unit number for such a call may be specified to
retain compatibility with RSX-llD; but this specification is ignored
by RSX-llM.
The following subsections briefly describe the function and format of
each FORTRAN subroutine call.
Note the use of ASUDLN to specify a
default logical unit number. Also consider the numbering conventions
described in 15.7.2.
The following FORTRAN functions do not perform
facilitate conversions between BCD and binary.

I/O

directly,

but

Convert four BCD digits to a binary number:
IBIN

= KBCD2B(IBCD)

Convert a binary number to four BCD digits:
IBCD = KB2BCD(IBIN)
Table 15-5
FORTRAN Interface Subroutines for the UDCll
Subroutine

Function

AIRD/AIRDW

Perform input of analog
sequence

data

random

AISQ/AISQW

Read a series of sequential analog
channeis

input

AO/AOW

Perform analog output on several channels
(D)

ASUDLN

Assign a LUN to the UDCll

CTDI

Connect a circular buffer
contact interrupt data

receive

{continued on next page)

15-111

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-5 (Cont.)
FORTRAN Interface Subroutines for the UDCll
Function

Subroutine
CTTI

Connect a circular
timer interrupt data

DFDI

Disconnect
interrupts

DFTI

Disconnect a buffer from timer interrupts

DI/DIW

Read several
fields (D)

DOL/DOLW

buffer

buff er

16-point

from

contact

receive
contact

sense

I
I Latch or unlatch several 16-point fields

DOM/DOMW

Pulse several 16-point fields (D)

RC I PT

Read the state of
interrupt point (D)

RDCS

Read the contents of a contact interrupt
circular buffer, returning data on only
those points that have changed state

RDDI

Read the contents of a contact interrupt
circular buffer, one point for each call

RDTI

Read the contents of a timer interrupt
circular buffer, one entry for each call

RDWD

Read the contents of a contact interrupt
circular buffer, returning 16 bits of
module
data
and
change-of-state
information

RSTI

Read a single timer module (D)

SCTI

Set a timer module to an initial value

15.5.4

single

contact

AIRD/AIRDW: Performing Input of Analog Data in Random Sequence

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog
random sequence. These calls are issued as follows:
CALL

{ AIRD } (inm,icont,idata, [isb] ,lun)
AIRDW

inm
The number of analog input channels.

15-17

data

UNIVERSAL DIGITAL CONTROLLER DRIVER
icont
An integer array containing terminal connection data-channel
number (right-justified in bits 0-11) and gain (bits 12-15), as
shown in Table 15-3.
id a ta
An integer array to receive the converted values.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
NOTE
lun is a required parameter.
The isb array has the standard meaning defined in Section 15.5.2.
If
inm
O, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

15.5.5

AISQ/AISQW:

Reading Sequential Analog Input Channels

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of
sequential analog input channels. These calls are issued as follows:
CALL { AISQ } (inm,icont,idata,[isb] ,lun)
AISQW
inm
The number of analog input channels.
icont
An integer array containing terminal connection data-channel
number (right-justified in bits 0-11) and gain (bits 12-15), as
shown in Table 15-3.
id a ta
An integer array to receive the converted values.

15-18

UNIVERSAL DIGITAL CONTROLLER DRIVER
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
NOTE
lun is a required parameter.
For sequential analog input, channel number is computed in steps of
one, beginning with the value specified in the first element of icont.
The channel number field is ignored in all other elements of the
array.
The gain used for each conversion is taken from the respective element
in icont. Thus, even though the channei number is ignored in all but
the first element of icont, the gain must be specified for each
conversion to be performed.
The isb array has the standard meaning defined in Section 15.5.2.
If
inm
O, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

15.5.6

AO/AOW: Performing Analog Output

The ISA standard AO/AOW FORTRAN subroutines initiate analog output
several channels. These calls are issued as follows:
CALL { AO
AOW

}

(inm,icont,idata,[isb],[lun])

inm
The number of analog output channels.
icont
An integer array containing the channel numbers.
idata
An integer array containing the output voltage settings,
range 0-1023.

15-19

the

UNIVERSAL DIGITAL CONTROLLER DRIVER
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number (ignored if present).
The isb array has the standard meaning defined in Section 15.5.2.

15.5.7

ASUDLN: Assigning a LUN to the UDCll

The ASUDLN FORTRAN subroutine assigns the specified LUN to the
specified unit and defines it as the default logical unit number to be
used whenever a LUN specification is omitted from a UDCll subroutine
call. It is issued as follows:
CALL ASUDLN ( l un, [ i sw] , [ i un] )
lun
The logical unit number to be assigned to the specified unit, and
defined as the default.
isw
An integer variable to which the result of the ASSIGN LUN
directive is returned.

system

iun
An integer defining the UDCll
specified, 0 is assumed.

15.5.8

unit

number.

number

CTDI: Connecting to Contact Interrupts

The CTDI FORTRAN subroutine connects a task to contact interrupts and
specifies a circular buffer to receive contact interrupt data. The
length of this buffer can be computed by considering the following:
•

Rate at which contact module interrupts occur

•

Number of modules that can interrupt simultaneously

•

Rate at which the circular buffer is emptied

15-20

UNIVERSAL DIGITAL CONTROLLER DRIVER
The UDCll driver generates a 5-word entry for each contact interrupt
and the interface subroutine itself requires 10 words of additional
storage. Thus the isz parameter, described below, can be computed as
follows:
isz

(10 + 5 * n)

where n is the number of entries in the buffer and isz is expressed in
words.
The call is issued as follows:
CALL CTDI (ibuf ,isz,iev, [isb], [lun])
ibuf
An integer array that is to receive contact interrupt data.
isz
The length of the array in words, with a minimum size of 15.
iev
The trigger event flag number. The specified event flag
whenever the driver inserts an entry in the data buffer.

set

status

isb
A 2-word
returned.

integer

array

which

the

subroutine

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.

15.5.9

CTTI: Connecting to Timer Interrupts

The CTTI FORTRAN subroutine connects a task to timer interrupts and
specifies a circular buffer to receive timer interrupt data. The
length of this buffer can be computed by considering the following:
•

Rate at which timer module interrupts occur

•

Number of modules that can interrupt simultaneously

•

Rate at which the circular buffer is emptied

15-21

UNIVERSAL DIGITAL CONTROLLER DRIVER
The UDCll driver generates a 4-word entry for each timer interrupt and
the interface subroutine itself requires 8 words of additional
storage. Thus the isz parameter, described below, can be computed as
follows:
isz

(8 + 4 * n)

where n is the number of entries in the buffer and isz is expressed in
words.
When a timer module interrupt occurs, the driver resets the count to
an initial value, normally that specified in iv. The initial value
for a specific module can be modified by calling the SCTI subroutine
(see Section 15. 5.19).
The call is issued as follows:
CALL CTTI (ibuf ,isz,iev,iv, [isb], [lun])
ibuf
An integer array that is to receive timer interrupt data.
isz
The length of the array in words, with a minimum size of 12.
iev
A trigger event flag number. The specified event flag
whenever the driver inserts an entry in the data buffer.

set

iv
An integer array that contains the initial timer module values,
with one entry for each timer module, where entry n corresponds
to timer module number n-1.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.

15.5.10

DFDI: Disconnecting from Contact Interrupts

The DFDI FORTRAN subroutine disconnects
interrupts. It is issued as follows:
CALL DFDI ([isb],[lun])

15-22

task

from

contact

UNIVERSAL DIGITAL CONTROLLER DRIVER
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.

15.5.11

DFTI: Disconnecting from Timer Interrupts

The DFTI FORTRAN subroutine disconnects a task from timer
It is issued as follows:

interrupts.

CALL DFTI ([isb],[lun])
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.

15.5.12

DI/DIW: Reading Several Contact Sense Fields

The ISA standard DI/DIW FORTRAN subroutines read several
contact sense fields. These calls are issued as follows:
DI
CALL

{

DIW

}

16-point

{inm,icont,idata,isb,[lun])

inm
The number of fields to be read.
icont
An integer array containing the
field to be read.

initial

point

number

each

bits

idata

An integer array that is to receive
contact data for each field read.

15-23

input data,

UNIVERSAL DIGITAL CONTROLLER DRIVER
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number {ignored if present).
The isb array has the standard meaning defined in Section 15.5.2.

15.5.13

DOL/DOLW: Latching or Unlatching Several Fields

The ISA standard DOL/DOLW FORTRAN subroutines latch or unlatch one
more 16-point fields. These calls are issued as follows:
CALL

DOL
{

}

(inm,icont,idata,imsk, [isb], [lun])

DOLW

inm
The number of fields to be latched or unlatched.
icont
An integer array containing the
16-point field.

initial

point

number

each

id a ta
An integer array that specifies the points to be latched or
unlatched; bit n of idata corresponds to point number icont + n;
if the corresponding bit in imsk is set, the bit is changed;
a
bit value of 1 indicates latching, and O unlatching; each entry
in the array specifies a string of 16 points.
imsk
An integer array in which bits are set to indicate points whose
states are to be changed in the corresponding idata bits; each
entry in the array specifies a 16-bit mask word.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.

15-24

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.5.14

DOM/DOMW: Pulsing Several Fields

The ISA standard DOM/DOMW FORTRAN subroutines pulse several 16-bit
fields
(1-shot digital output points).
These calls are issued as
follows:
CALL

{DOM }
DOMW

{inm,icont,idata,[idx],[isb],[lun])

inm
The number of fields to be pulsed.
icont
An integer array containing the
16-point field.

initial

point

number

each

idata
An integer array which specifies the points to be pulsed;
of idata corresponds to point number icont + n.

bit

idx
A dummy argument retained for compatibility with
existing
Instrument Society of America standard FORTRAN process control
calls.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number (ignored if present).
The isb array has the standard meaning defined in Section 15.5.2.

15.5.15

RCIPT: Reading a Contact Interrupt Point

The RCIPT FORTRAN subroutine reads the state
interrupt point. It is issued as follows:

single

contact

CALL RCIPT (ipt,isb,[lun])
ipt
The number of the point to be
sequentially from 0, the first
interrupt module.

15-25

read;
point

points
on the

are numbered
first contact

UNIVERSAL DIGITAL CONTROLLER DRIVER
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number (ignored if present).
The isb array has the same basic meaning defined
in Section
However,
isb word
2 1s set to one of the following
representing the state of the point:
Setting

15.5.2.
values,

Meaning

.FALSE.

(0)

Point is open

.TRUE.

(-1)

Point is closed
NOTE

To increase throughput, the subroutines
RDCS,
RODI, RDTI, and RDWD described in
the following four sections do not issue
the clear Event Flag directive until a
buffer-empty condition is detected.
The
calling
task,
therefore, must avoid
issuing a Wait-For directive until a
buffer-empty is reported.

15.5.16

RDCS: Reading Contact Interrupt Change-of-State Data from a
Circular Buffer

The RDCS FORTRAN subroutine reads contact interrupt data
from a
circular buffer that was specified
in a CTDI call (see Section
15.5.8).
It does no actual input or output,
but rather performs a
point-by-point scan of an interrupt entry in the buffer, returning the
state of each point that has changed state as a
logical value.
The
trigger event flag that was specified in the CTDI call is cleared when
the "buffer empty" condition is detected.
On the initial call to RDCS,
the module number, module data, and
change-of-state word of the next interrupt entry are read from the
circular buffer and stored for subsequent reference.
The subroutine
then searches the entry change-of-state word until a nonzero point is
encountered.
The point number is computed and returned to the caller
along with the state of the point.
Scanning for points that have
changed state resumes on the next call;
all other points are
bypassed.
The next entry is automatically read when the caller has
received all change-of-state information from the current entry.
If a
valid entry is not found, ipt is set negative and ict (if specified)
is either assigned a value of 0 or an overrun count maintained by the
UDCll driver.
If
ict is O, no further entries remain.
A nonzero
value indicates that the driver received more data than could be
stored
in the buffer, and ict represents the number of entries that
were discarded.

15-26

UNIVERSAL DIGITAL CONTROLLER DRIVER
The RDCS call is issued as follows:
CALL RDCS (ipt,ival,[ict])
ipt
A variable to which the digital input point number
it may be set as follows:
•

returned;

ipt O if no valid entry is found (that is, no interrupt data
currently in buffer, or overrun detected).
One of the
following values is returned to indicate the
condition
detected:
-1
-2

Buff er empty
Overrun detected

ipt => O if the value indicated is a point number
changed state; the state is returned to ival.

that

has

A variable to which the state of the point is returned;
be set as follows:

may

•

ival

•

.FALSE.

(0) if the point is open

•

.TRUE.

(-1) if the point is closed

ict
An integer variable for receiving the overrun count.
A nonzero
positive count indicates that the driver was unable to store the
number of interrupts indicated.

15.5.17

RDDI: Reading Contact Interrupt Data from a Circular Buffer

The RDDI FORTRAN subroutine reads contact interrupt data from a
circular buffer that was specified in a CTDI call (see Section
15.5.8). It does no actual input or output, but rather performs a
point-by-point scan of an interrupt entry in the buffer, returning the
state of each point as a logical value. The trigger event flag that
was specified in the CTDI call is also cleared.
On the initial call to RDDI, the module number and data of the next
interrupt entry are read from the circular buffer and stored for
subsequent reference. The subroutine then sets the current data bit
number n to O, examines the state of data bit n, and converts bit n to
a point number by the following formula:
ipt = module number * 16 + n

15-27

UNIVERSAL DIGITAL CONTROLLER DRIVER
On each subsequent call, n is incremented by one and then data bit n
is examined in the stored module data. When n reaches 16, it is reset
to 0 and an attempt is made to read the next interrupt entry from the
circular buffer.
If a valid entry is not found, ipt is set negative
and ict (if specified) is either assigned a value of 0 or an overrun
count maintained by the UDCll driver. If ict is O, no further entries
remain. A nonzero value indicates that the driver received more data
than could be stored in the buffer, and ict represents the number of
entries that were discarded.
The RODI call is issued as follows:
CALL RODI {ipt,ival,[ict])
ipt
A variable to which the digital input point number
it may be set as follows:
•

returned;

ipt 0 if no valid entry is found (that is, no interrupt data
currently in buffer, or buffer empty). One of the following
values is returned to indicate the condition detected:
-l=Buf fer empty
-2=0verrun detected

•

ipt => 0 if the value indicated is a point number;
is returned to ival

the

state

ival
A variable to which the state of the point is returned;
be set as follows:
•

.FALSE.

(0)

•

.TRUE.

(-1)

may

if the point is open
if the point is closed

ict
A variable to which the overrun count may be returned; a nonzero
positive count indicates that the driver was unable to store the
number of entries indicated.

15.5.18

RDTI: Reading Timer Interrupt Data from a Circular Buffer

The RDTI FORTRAN subroutine reads timer interrupt data from a circular
buffer that was specified in a CTTI call (see Section 15.5.9). It
does no actual input or output, but rather performs a scan of each
entry in the buffer, returning the timer value for each call. The
trigger event flag that was specified in the CTTI call is also
cleared.
When a timer module interrupt occurs, the UDCll driver resets the
count to an initial value, usually that specified in the iv array on
the CTTI call. The initial value can be modified for a specific
module by calling the subroutine SCTI (see Section 15.5.19).

15-28

UNIVERSAL DIGITAL CONTROLLER DRIVER
The RDTI call is issued as follows:
CALL RDTI (imod,itm,[ivrn])
imod
A variable to which the module number is returned;
as follows:
•

it may be set

imod 0 if no valid entry is found (that is, no interrupt data
currently in buffer, or buffer empty). One of the following
values is returned to indicate the condition detected:
-l=Buf fer empty
-2=0verrun detected

•

imod > 0 if the entry is valid, indicating a module
the value of the timer module is returned in itm

number;

itm
A variable to which the timer value is returned.
ivrn
A variable to which the overrun count may be returned; a nonzero
positive count indicates that the driver was unable to store the
number of values indicated.

15.5.19

RDWD: Reading a Full Word of Contact Interrupt Data from the
Circular Buffer

The RDWD FORTRAN subroutine reads a full word of contact interrupt and
change-of-state data from the circular buffer that was specified in a
CTDI call (see Section 15.5.8). It does no actual input or output,
but rather performs a scan of each entry, returning the state of a
module and, optionally, the change-of-state data for each call.
The
trigger event flag specified in the call to CTDI is cleared.
The call to RDWD is issued as follows:
CALL RDWD (imod,ist, [ivrn], [icos])
imod
A variable to which the module number is returned;
as follows:
•

it may be set

imod 0 if no valid entry is found (that is, no interrupt data
currently
in buffer .or overrun detected).
One of the
following values is returned to indicate the
condition
detected:
-1.,.Buf fer empty
-2=0verrun detected

15-29

UNIVERSAL DIGITAL CONTROLLER DRIVER
ist
A variable to which the module data is returned.
ivrn
A variable to which the overrun count may be returned;
a
nonzero, positive count indicates that the driver was unable to
store the number of entries indicated.
icos
A variable to which the change-of-state data is returned.
One
bit is set for each point that has changed state in the direction
indicated by the "point open"
{POP) or "point closed" {PCL)
jumpers on the module.

15.5.20

RSTI: Reading a Timer Module

The RSTI FORTRAN subroutine reads a single timer module.
as follows:

It is issued

CALL RSTI {imod,isb,[lun])
imod
The module number of the timer to be read.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number (ignored if present).
The isb array has the standard meaning defined in Section 15.5.2.

15.5.21

SCTI: Initializing a Timer Module

The SCTI FORTRAN subroutine sets a timer module to an
It is issued as follows:
CALL SCTI {imod,ival,[isb] ,[lun])
imod
The module number of the timer to be set.

15-30

initial

value.

UNIVERSAL DIGITAL CONTROLLER DRIVER
ival
The initial timer value.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

lun
The logical unit number.
The isb array has the standard meaning defined in Section 15.5.2.
Calls to initialize a counter are valid only if the issuing task has
connected a buffer for receiving counter interrupts by a call to CTTI.

15.6

STATUS RETURNS

Table 15-6 lists the error and status conditions that are returned
the UDCll driver described in this chapter:
Table 15-6
UDCll Status Returns
Reason

Code

rs.sue

Sucessful completion
The operation specified in the QIO directive was
completed successfully.
The second word of the I/O
status block can be examined to determine the number
of samples completed or converted.

IS.PND

I/O request pending
The operation specified in the QIO directive has not
yet been executed.
The I/O status block is filled
with Os.

IE.ABO

Operation aborted
The specified I/O operation was canceled with
while still in the I/O queue.

IE.BAD

IO.KIL

Bad parameter
An illegal specification was supplied for one or more
of the device-dependent QIO parameters (words 6-11).
For the UDCll, this code indicates an illegal channel
number or gain code for the ADUOl.
(continued on next page)

15-31

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-6 (Cont.)
UDCll Status Returns
Code

Reason

IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a buffer but only
word alignment is legal for the UDC12. Alternately,
the length of a buffer was not an even number of
bytes.

IE.CON

Connect error
The task attempted to connect to contact or timer
interrupts, but the interrupt was already connected
to another task. Only one task can be connected to a
timer or contact interrupt. Alternately a task which
was not connected attempted to disconnect
from
contact or timer interrupts.

IE.DNR

Device not ready
The physical device unit specified in the
QIO
directive was not ready to perform the desired I/O
operation. For the ADUOl, this code is returned if
an interrupt time out occurred or the power failed.

IE.IEF

Invalid event flag number
An invalid trigger event flag number was specified in
a connect function.

IE.IFC

Illegal function
A function code was included in an I/O request that
is illegal for the UDCll, or a request to initialize
a counter (IO.ITI) was issued by a task that was not
connected
to
receive
counter interrupts.
The
function may also refer to a UDCll feature which was
not specified at system generation.

IE.MOD

Invalid UDCll module
On latching output, the user specified a starting
point number that was not legal (defined at system
generation) or was not evenly divisible by 16.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line. When
the system was booted, a device check indicated that
this
physical
device
unit
was
not
in the
configuration.
(continued on next page)

15-32

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-6
(Cont.)
UDCll Status Returns
Reason

Code
IE.PRI

Privilege violation
The task which issued the request was not privileged
to execute that request.
For the UDCll, this code
indicates that a checkpointable task attempted to
connect to timer or contact interrupts.

IE. SPC

Illegal address space
The specified control, data, or interrupt buffer was
partially or totally outside the address space of the
issuing task.
Alternately, the interrupt buffer was
too small for a single data entry (six words for
timer interrupts and seven
words
for
contact
interrupts), or a byte count of 0 was specified.

FORTRAN interface values for these status
Section 15.6.1.

15.6.1

returns

are

presented

FORTRAN Interface Values

The values listed in Table 15-7 are
calls.

returned

FORTRAN

Table 15-7
FORTRAN Interface Values
Status Return

FORTRAN Value

rs.sue

+01
+00
+315
+101
+301
+319
+313
+303

IS. PND

IE.ABO
IE.ADP
IE.BAD
IE. BYT
IE. DAO
IE.DNR
IE. IEF
IE.IFC
IE. ILU
IE.MOD
IE.ONP
IE.PRI
IE. RSU
IE. SDP
IE. SPC
IE.ULN
IE.UPN

+100

+302
+99
+321
+305
+316
+317
+102
+30f)
+08
+04

15-33

subroutine

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.7

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the UDCll driver described in this
chapter.

15.7.1

Numbering Conventions

Numbering is relative. Module numbers start at O, beginning with
first module of a given type.

the

Channel numbers also start at O, with channel 0 as the first channel
on the first module of a given type.
For the ADUOl, channel 8 is the
first channel on the second analog output module.
Each IAD-IA module installed in an ICSll subsystem occupies 120
channels
(regardless of the number of multiplexers installed).
In
this case, channel 120 is the first channel on the second
IAD-IA A/D
converter.
Point numbers start at O, with point 0 as the first point on the first
module of a given type.
For instance, point 20(8) is the first point
of the second contact sense module (that is,
relative module number
1) •

15.7.2

Processing Circular Buffer Entries

Circular buffer entries should be processed in the following sequence.
1.

Execute a WAITFOR system directive using the trigger event
flag specified
in the subroutine called to connect the
circular buffer (CTTI or CTDI).

Repeatedly call the appropriate subroutine to read
the
circular buffer until all entries have been obtained and ipt
indicates that the buffer is empty (-1).

Perform any other processing and return to step 1.

15-34

CHAPTER 16
LABORATORY PERIPHERAL SYSTEMS DRIVERS

16. 1

INTRODUCTION

The LPSll and ARll Laboratory Peripheral Systems are
modular,
real-time subsystems used for the acquisition and/or output of
laboratory analog data.
(Laboratory Peripheral Systems drivers are
not supported on RSX-llM-PLUS systems.) Table 16-1 compares the LPSll
with the ARll.
Table 16-1
Laboratory Peripheral Systems

Analog-to-Digital Conversion
(with Sample and Hold
Circuitry)

LPSll

ARll

12 bits of precision
16-channel multiplexer
with gain ranging

10 bits of precision
16-channel multiplexer
without gain ranging

Maximum of 64 channels
without gain ranging
Programmable Real-Time Clock

Yes

Digital-to-Analog Output

12 bits of prec1s1on
10 channels (including display)

10 bits of precision
2 channels (including
display)

Display Control

4096 by 409n dot matrix

1024 by 1024 dot matrix

Digital I/O Option

16 digital points
and programmable
relays

16 digital points
(available with
DRll-K option)

At system generation, the user can specify the following:
•

The number of A/D channels

•

The presence or absence of the gain-ranging option (LPSAM-SG)
(LPSll only) and the polarity of each channel
(uni- or
bi polar)

•

The presence or absence of the external D/A option (LPSVC
LPSDA), and if present, the number of D/A channels

•

The clock preset value

Hi-1

and

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.1.1

ARll Laboratory Peripheral System

The ARll is a 1-module, real-time analog subsystem that interfaces to
the PDP-11 family of computers by a "hex" small peripheral controller
slot. The system is a subset of the LPSll and, as such, enjoys the
same degree of flexibility. The ARll includes a 16-channel, 10-bit
A/D converter with sample-and-hold, a programmable real-time clock
with one external input, and a display control with two 10-bit D/A
converters.

16.1.2

LPSll Laboratory Peripheral System

The LPSll is a high-performance, modular, real-time subsystem with the
flexibility of serving a variety of applications, including biomedical
research, analytical instrumentation, data collection and reduction,
monitoring,
data
logging, industrial testing, engineering, and
technical education. The basic subsystem, built in a compact size and
designed for easy interface with external instrumentation, includes a
13-bit A/D converter, a programmable real-time clock, with two Schmitt
triggers, a display controller with two 12-bit D/A converters, and a
16-bit digital I/O option. Up to nine different option types may be
added to the basic package.

16.2

GET LUN INFORMATION MACRO

If a GET LUN INFORMATION system directive is issued for a LUN
associated with a Laboratory Peripheral System, word 2 (the first
characteristics word) contains all Os words 3 and 4 are undefined, and
word 5 contains a 16-bit buffer preset value that controls the rate of
the real-time clock interrupts, as explained in Section 16.6.1.

16.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the Laboratory Peripheral System drivers.

16.3.1

Standard QIO Function

Table 16-2 lists the standard function of the QIO macro that is
for the Laboratory Peripheral Systems.
Table 16-2
Standard QIO Function for
Laboratory Peripheral Systems
Format

Function
Cancel I/O requests

IO.KIL, •••

IO.KIL cancels all queued and in-progress I/O requests.

16-2

valid

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.3.2

Device-Specific QIO Functions (Immediate)

Except for IO.STP (see Section l~.3.4), all device-specific functions
of the QIO macro that are valid for the Laboratory Peripheral Systems
are either immediate or synchronous.
Each immediate function performs
a
complete operation, whereas each synchronous function simply
initiates an operation synchronized to the real-time clock.
Table
16-3 lists the immediate functions.
Table 16-3
Device-Specific QIO Functions for the
Laboratory Peripheral Systems (Immediate)
Format

Function

QIO$C IO.LED, ••• ,<int,num>

DISPLAY number in LED lights
(LPSll only)

QIO$C IO.REL, ••• ,<rel,pol>

LATCH output relay (LPSll only)

QIO$C IO.SDI, ••• ,<mask>

READ digital input register

QIOSC IO.SDO, ••• ,<mask,data>

WRITE digital output register

int
The 16-bit signed binary integer to display.
num
The LED digit number where the decimal point is to be placed.
rel
The relay number (0 or 1).
pol
The polarity (0 for open, nonzero for closed).
mask
The mask word.
data
The data word.
The following subsections describe the functions listed above.

16-3

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.3.2.1 IO.LED - This LPSll-only function displays a 16-bit signed
binary integer in the light-emitting diode (LED) lights. The number
is displayed with a leading blank {positive number) or minus sign
(negative number), followed by five non-zero-suppressed decimal digits
that represent the magnitude of the number. LED digits are numbered
from right to left, starting at 1.
The number may be displayed with or without a decimal point.
If the
parameter num is a number from 1 to 5, then the corresponding LED
digit is displayed with a decimal point to the right of the digit. If
the LED digit number is not a number from 1 to 5, then no decimal
point is displayed.

16.3.2.2 IO.REL - This LPSll-only function opens or closes
the
programmable relays in the digital I/O status register. Approximately
300 milliseconds are required to open or close a relay.
The driver
imposes no delays when executing this function.
Thus it is the
responsibility of the user to insure that adequate time has elapsed
between the opening and closing of a relay.

16.3.2.3 IO.SDI - This function reads data qualified by a mask word
from the digital input register. The mask word contains a 1 in each
bit position from which data is to be read. All other bits are zero
filled and the resulting value is returned in the second I/O status
word.
The operation performed is:
RETURN VALUE=MASK.AND.INPUT REGISTER

15.3.2.4 IO.SDO - This function writes data qualified by a mask word
into the digital output register. The mask word contains a 1 in each
bit position that is to be written. The data word specifies the data
to be written in corresponding bit positions.
The operation performed is:
NEW REGISTER=<MASK.AND.DATA>.OR.<<.NOT.MASK>.AND.OLD REGISTER>

16.3.3

Device-Specific QIO Functions (Synchronous)

Table 16-4 lists the synchronous, device-specific functions of the QIO
macro that are valid for the Laboratory Peripheral Systems.

16-4

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-4
Device-Specific QIO Functions for the
Laboratory Peripheral Systems (Synchronous)
Format

Function

QIO$C IO.ADS, ••• ,<stadd,size,pnt,
ticks,bufs,chna>

INITIATE A/D sampling

QIO$C IO.HIS, ••• ,<stadd,size,pnt,
ticks,bufs>

INITIATE histogram sampling
(LPSll only)

QIO$C IO.MDA, ••• ,<stadd,size,pnt,
ticks,bufs,chnd>

INITIATE D/A output

QIO$C IO.MDI, ••• ,<stadd,size,pnt,
ticks,bufs,mask>

INITIATE digital input
sampling

QIO$C IO.MDO, ••• ,<stadd,size,pnt,
ticks,bufs,mask>

INITIATE digital output

stadd
The starting address of the
boundary).

data

buff er

(must

word

size
The data buffer size in bytes (must
multiple of four bytes).

greater

than

and

pnt
The digital point numbers (byte 0 - starting input/output point
number;
byte 1 - input point number to stop the function).
Points are numbered from 0 to 15, allowing a maximum of 16 points
to be specified.
ticks
The number of real-time clock
transfers, as appropriate.

ticks

buf s
The number of data buffers to transfer.

16-5

between

samples

data

LABORATORY PERIPHERAL SYSTEMS DRIVERS
chna
The analog-to-digital conversion specification. Byte 0 contains
the starting channel number. For LPSll this must be in the range
of 0-63; for ARll the range is 0-15. If the LPSll gain-ranging
option is present, the channel number must be in the range of
0-15, and bits 4 and 5 specify the gain code.
Byte 1 contains the number of consecutive analog-to-digital
channels to sample. For LPSll this must be in the range of 1-64;
for ARll or the LPSll with gain-ranging, the range is 1-16.
chnd
The digital-to-analog output channel specification.
Byte 0
contains the starting channel number. For LPSll this must be in
the range of 0-9; for the ARll the range is 0-1.
Byte 1 contains the number of consecutive channels to be output.
For LPSll this must be in the range of 1-10; for ARll the range
is 1-2.
mask
The mask word.
The following subsections describe the functions listed above.

16.3.3.1 IO.ADS - This function reads one or more A/D channels at
precisely timed intervals, with or without auto gain-ranging. If two
or more channels are specified, all are sampled at approximately the
same time, once per interval.

Sampling may be started when the request is dequeued or when a
specified digital input point is set. A digital output point may
optionally be set when sampling is started.
Sampling may
be
terminated by a program request (IO.STP or IO.KIL), by the clearing of
a digital input point, or by the collection of a specified number of
buffers of data.
All input is double buffered with respect to the user task. Each time
a half buffer of data has been collected, the user task is notified
(by the setting of an event flag)
that data is available to be
processed while the driver fills the other half of the buffer. If the
user task does not respond quickly enough, a data overrun may result.
This occurs if the driver attempts to put another data item in the
user buffer when no space is available.
The subfunction modifier bits are identical to those described in
Section 16.3.3.2. In addition, setting bit 3 to a 1 means LPSll auto
gain-ranging is requested. Bit 3 is ignored for the ARll. If bits 7
and 6 are both set to 1, the digital input point and digital output
point number are assumed to be the same.

16-6

LABORATORY PERIPHERAL SYSTEMS DRIVERS
If LPSll auto gain-ranging is used, the LPSAM-SG hardware option must
be present and specified at system generation.
The auto gain-ranging
algorithm causes a channel to be sampled at the highest gain at which
saturation does not occur.
If the gain-ranging option is present and
auto gain-ranging is not specified in bit 3 of the subfunction code,
then bits 4 and 5 of the starting channel number specify the gain at
which samples are to be converted.
Gain codes are as follows:
Code

Gain

00
01
10
11

1
4

16
64

Data words written into the user buffer contain the converted value in
bits 0-11 and the gain code, as shown below, in bits 12-15:
Code

Gain

0000
0001
0010
0011

1
4
16
64

If the LPSAM-SG option is present, then each channel must have been
defined as uni- or bipolar at system generation.
In addition, if
bandwidth filtering is enabled (and so indicated at system generation
time), a software delay is imposed by the driver when the multiplexer
channel is changed.
This delay must have been specified at SYSGEN.
See the LPSll Laboratory Peripheral System User's Guide.
The ARll always returns data that is equivalent to an LPSll gain of 1.
Channel polarity must always be specified for the ARll at system
generation, since this operation is software selectable at the time
sampling is initiated.

16.3.3.2 IO.HIS - This LPSll-only function measures the elapsed time
between a series of events by means of Schmitt trigger 1.
Each time a
sample is to be taken, a counter is incremented and Schmitt trigger 1
is tested.
If it has fired, then the counter is written into the user
buffer and reset to 0.
Thus, the data item returned to the user is
the number of sample intervals between Schmitt trigger firings.
If the counter overflows before Schmitt trigger 1 fires,
then a
0
value is written into the user buffer.
Sampling may be started and
stopped as described
in Section 16.3.3.1.
All
input is double
buffered with respect to the user task.
The subfunction modifier bits appear below.
the action listed in the right-hand column.

16-7

A setting of 1

indicates

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Bit

Meaning

0-3

Unused

Stop on number of buffers

Stop on digital input point clear

Set digital output point at start of operation

Start on
digital
input
point
set
(a
0
specification means start immediately). Points
are numbered from 0 to 15, allowing a maximum of
16 points to be specified.

16.3.3.3 IO.MDA - This function writes data into one or more external
D/A converters at precisely timed intervals. If two or more channels
are specified, all are written at approximately the same time, once
per interval.
Output may be started or stopped as described in
Section 16.3.3.1. All output is double buffered with respect to the
user task.
D/A converters 0 and 1 correspond to the X and Y registers of the
display control. Note that there are no specific driver functions to
set the display status register. This is reserved for the user.
D/A
converters 2 through 9 correspond to the LPSll, LPSDA external D/A
option.
The subfunction modifier bits are
Section 16.3.3.2.

identical

those

described

16.3.3.4 IO.MDI - This function provides the capability to read data
qualified by a mask word from the digital input register at precisely
timed intervals. Sampling may be started and stopped as described in
Section 16.3.3.1.
All input is double buffered with respect to the
user task.
The mask word contains a 1 in each bit position from which data is
be read. All other bits are O.

The subfunction modifier bits are
Section 16.3.3.2.

identical

those

described

16.3.3.5 IO.MOO - This function writes data qualified by a mask word
into the digital output register at precisely timed intervals. Output
may be started and stopped as described in Section 16.3.3.1.
All
output is double buffered with respect to the user task.
The subfunction modifier bits are
Section 16.3.3.2.

identical

16-8

those

described

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.3.4

Device-Specific QIO Function (IO.STP)

Table 16-5 lists the device-specific function of the QIO macro,
is valid for the Laboratory Peripheral Systems.

which

Table 16-5
Device-Specific QIO Function for the
Laboratory Peripheral Systems (IO.STP)
Format

Function

QIO$C IO.STP, ••• ,<STADD>

STOP in-progress request

stadd
The buffer address of the function to stop (must be the
the address specified in the initiating request).

same

16.3.4.1 IO.STP - IO.STP stops a single, in-progress synchronous
request.
It is unlike IO.KIL in that it cancels only the specified
request, whereas IO.KIL cancels all requests.

16.4

FORTRAN INTERFACE

A collection of FORTRAN-callable subroutines provide FORTRAN programs
access to the Laboratory Peripheral Systems.
These routines are
described in this section.
Some of these routines may be called from FORTRAN as
either
subroutines or functions.
All are reentrant and may be placed in a
resident library.

16.4.1

The isb Status Array

The isb (I/O status block) parameter is a 2-word integer array that
contains the status of the FORTRAN call, in accordance with ISA
convention. This array serves two purposes:
1.

It is the 2-word I/O status block to which the driver returns
an I/O status code on completion of an I/O operation.

The first word of the isb receives a status code from the
FORTRAN
interface
in
ISA-compatible format, with the
exception of the I/O pending condition, which is indicated by
a status of O. The ISA standard code for this condition is
+2.

The meaning of its contents varies, depending on the FORTRAN call that
has been executed, but Table 16-6 lists certain general principles
that apply. The sections describing individual subroutines provide
more details.

16-9

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-6
Contents of First Word of isb
Contents

Meaning

isb{l)

= 0

Operation pending;

isb{l)

= 1

Successful completion

isb{l)

= 3

Interface subroutine unable to generate QIO
directive, or illegal time or buffer value

< = isb{l) < 300

I/O in progress

QIO
directive rejected
code = -(isb(l) - 3)

and

actual

error

and

actual

error

Driver rejected request
code = -{isb(l) - 300)

isb{l) > 300

FORTRAN interface routines depend on asynchronous system traps to set
their status. Thus, if the trap mechanism is disabled, proper status
cannot be set.

16.4.2

Synchronous Subroutines

RTS, DRS, HIST (LPSll only), SDO, and SDAC are FORTRAN subroutines
that
initiate synchronous functions.
When they are used, the
appropriate Laboratory Peripheral System driver and the FORTRAN
program communicate by means of a caller-specified data buffer of the
following format:
BUFFER HEADER

CURRENT BUFFER POINTER
ADDRESS OF SECOND 110 ST A TUS WORD
ADDRESS OF END OF BUFFER + 1
ADDRESS OF ST ART OF DAT A

START OF DATA
HALF BUFFER
END OF BUFFER
ZK-008-81

The buffer header is initialized when the synchronous function
initiation routine is called. The length of the buffer must be even
and greater than or equal to 6. An even length is required so that
the buffer is exactly divisible into half buffers.
The drivers perform double buffering within the half buffers.
Each
time a driver fills or empties a half buffer, it sets a user-specified
event flag to notify the user task that more data is available or
needed.
The user task responds by putting more data into the buffer
or by removing the data now available.
If the user task does not respond quickly enough, a data overrun may
result.
This occurs if the driver attempts to put another data item
in the user buffer when no space is available (that is, the buffer is
full of data), or if the driver attempts to obtain the next data item
from the user buffer when none is available (that is, the buffer is
empty) •
10-10

LABORATORY PERIPHERAL SYSTEMS DRIVERS
All synchronous functions can be initiated
immediately or when a
specified digital
input point is set
(that is, a start button is
pushed).
They can be terminated by any combination of a program request,
the
processing of the
required number of full buffers of data, or the
clearing of a specified digital input point (that is, a stop button is
pushed).
A digital output point may also optionally be set at the
start of a synchronous function.
This could be used, for example, as
a signal to start a test instrument.

16.4.3

FORTRAN Subroutine Summary

Table 16-7 lists the FORTRAN interface subroutines supported for
the
Laboratory Peripheral Systems under RSX-llM.
S and F indicate whether
they can be called as subroutines or functions, respectively.
Table 16-7
FORTRAN Interface Subroutines for Laboratory Peripheral Systems
Subroutine

Function

ADC

Read a single A/D channel

ADJLPS

Adjust buffer pointers (S)

ASARLN

Assign a LUN to ARO:

(S)

ASLSLN

Assign a LUN to LSO:

(S)

CVSWG

Convert a switch gain A/D value to floating point (F)

DRS

Initiate synchronous digital input sampling (S)

HIST

Initiate histogram sampling (S)

IDIR

Read digital input (F,S)

!DOR

Write digital output (F,S)

IRDB

Read data from
(F,S)

LED

Display number in LED lights (S)

LPSTP

Stop an in-progress synchronous function

PUTD

Put data into a synchronous function output buffer (S)

RELAY

Latch an output relay (S)

RTS

Initiate synchronous A/D sampling (S)

SDAC

Initiate synchronous D/A output (S)

SDO

Initiate synchronous digital output (S)

(F,S)

synchronous

(LPSll only)

function

input

buff er

(LPSll only)
(S)

(LPSll only)

The following subsections briefly describe the function and format
each FORTRAN subroutine call.

16-11

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.4

ADC: Reading a Single A/D Channel

The ADC FORTRAN subroutine or function reads a single converted value
from an A/D channel.
If the gain-ranging option is present in the
LPSll hardware, the channel may be converted at a specific gain or the
driver can select the best gain (the gain providing the most
significance). The converted value is returned as a normalized
floating-point number. The call is issued as follows:
CALL ADC { ichan, [var], ( igain], [ isb])
ichan
The A/D channel to be converted.
var
A floating-point variable that receives the
floating-point format.

converted

value

igain
The gain at which the specified A/D channel is to be converted.
The default is 1.
If specified, igain may have the following
values:
igain
0

Gain
Auto gain-ranging {driver
provides most significance)

selects

gain

that

A gain of 1 is always used by the ARll driver.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.
When the function form of the call is used, the value of the function
is the same as that returned in var. If this value is negative, an
error has occurred during the A/D conversion (see Section 16.5.3).
Otherwise, this value is a floating-point number calculated from the
following formula:
var

= (64 * converted value) I conversion gain

16-12

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.5

ADJLPS: Adjusting Buffer Pointers

The ADJLPS FORTRAN subroutine adjusts buffer pointers for a buffer
that a laboratory peripheral system driver is either synchronously
filling or emptying. It is usually called when indexing is being used
for direct access to the data in a buffer.
When data in a buffer is to be processed only once, the IRDB and PUTD
routines may be used. In some cases, however, it is useful to leave
data in the buffer until processing is complete. The user program can
process the data directly, and then call ADJLPS to free half the
buffer. Using the routine for synchronous output functions is quite
similar.
When a half buffer of data is ready for output, ADJLPS is
called to make the half buffer available.
When ADJLPS is used for either input or output, care must be taken to
insure that the program stays in sync with the driver. If the program
loses its position with respect to the driver, the function must be
stopped and restarted. An attempt to over-adjust will cause a 3 to be
returned in isb(l) and no adjustment to take place.
The call is issued as follows:
CALL ADJLPS (ibuf,iadj,[isb])
ibuf
An integer array that was previously specified in
input or output function.

synchronous

iadj
The adjustment to be applied to the buffer pointers.
For an
input function, this specifies the number of data values that
have been removed from the data buffer. For an output function,
this specifies the number of data values that have been put into
the data buffer.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.

16.4.6

ASLSLN: Assigning a LUN to LSO:

The ASLSLN FORTRAN subroutine assigns a logical unit number (LUN)
to
the LPSll. It must be called prior to executing any other Laboratory
Peripheral Systems FORTRAN function or subroutine.
Subsequent calls
to other interface routines then implicitly reference the LPSll with
the LUN assigned.

16-13

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The call is issued as follows:
CALL ASLSLN (lun,[isb],[iun])
lun
The number of the LUN to be assigned to LSO:
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

iun
The unit number of the device to be assigned (defaults
not specified).

The isb array has the standard meaning described in Section 16.4.1.

16.4.7

KSARLN: Assigning a LUN to ARO:

The ASARLN FORTRAN subroutine assigns a logical unit number (LUN) to
the ARll.
It must be called prior to executing any other laboratory
peripheral system FORTRAN function or subroutine. Subsequent calls to
other interface routines then implicitly reference the ARll with the
LUN assigned.
The call is issued as follows:
CALL ASARLN (lun,[isb],[iun])
lun
The number of the LUN to be assigned to ARO:.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

iun
The unit number of the device to be assigned (defaults
not specified).
The isb array has the standard meaning described in Section

16-14

l~.4.1.

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.8

CVSWG: Converting a Switch Gain A/D Value to Floating-Point

The CVSWG FORTRAN subroutine converts an A/D value from a synchronous
A/D sampling function
to a
floating-point number.
Each data item
returned by a laboratory peripheral system driver consists of a gain
code and converted value packed
in a single word
(see Section
16.3.3.1). This form is not readily usable by FORTRAN,
but is much
more efficient than converting each value to floating point in the
driver.
This routine unpacks the gain code and value, and then
converts
the
result
to a
floating-point number.
It can be
conveniently used in conjunction with the IRDB routine
(see Section
16.4.13).
The call is issued as follows:
CVSWG (i va 1)
ival
The value to be converted to floating point.
Its format must be
that returned by a synchronous A/D sampling function.
The
conversion is performed according to the following formula:
var

= (64 * converted value)/conversion

gain

For the various gain codes,
var

= x * converted value

as shown below:

16.4.9

Gain

DRS: Initiating Synchronous Digital Input Sampling

The DRS FORTRAN subroutine reads data qualified by a mask word from
the digital input register at precisely timed intervals.
Sampling may
be started or stopped as for RTS (see Section 16.4.18) and all
input
is double buffered with respect to the user task.
Data may be
sequentially retrieved from the data buffer by the IRDB routine
(see
Section 16.4.12), or the ADJLPS routine (see Section 15.4.5) may be
used in conjunction with direct access to the input data.
The call is
issued as follows:
CALL DRS (ibuf ,ilen,imode,irate,iefn,imask,isb, [nbuf],
[ istart], [is top])

16-15

LABORATORY PERIPHERAL SYSTEMS DRIVERS
ibuf
An integer array that is to receive the input data values.
ilen
The length of ibuf (must be even and greater than or equal to 6).
imode
The start, stop, and sampling mode.
Its value is encoded by
adding together the appropriate function selection values shown
below.
Function
Selection
Value

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

Thus, a value of 192 for imode specifies:
•

The sampling is to be started when a specified
point is set.

digital

input

•

A digital output point is to be set when sampling is started.

•

Sampling will be stopped by a program request.

irate
A 2-word integer array that specifies the time interval between
digital
input samples.
The first word specifies the interval
units as follows:
irate{l)

Unit

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the
unsigned integer.

interval

magnitude

16-bit

iefn
The number of the event flag that is to be set each time
buffer of data has been collected.

16-16

half

LABORATORY PERIPHERAL SYSTEMS DRIVERS
imask
The digital input points to be read.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

nbuf
The number of buffers of data to be collected. It is needed only
if a function selection value of 16 has been added into imode.
is tart
The digital input pointer number to be used to trigger sampling,
and/or the digital output point number to be set when sampling is
started. It is needed only if a function selection value of 128
or 64 has been added into imode.
is top
The digital input point number to be used to stop sampling.
It
is needed only if a function selection value of 32 has been added
into imode.
When sampling is in progress, the first word of the isb array is zero
and the second word contains the number of data values currently in
the buffer.

16.4.10

HIST: Initiating Histogram Sampling (LPSll only)

The HIST FORTRAN subroutine measures the elapsed time between a series
of events with Schmitt trigger 1.
Each time a sample is to be taken, a counter is incremented and
Schmitt trigger 1 is tested. If it has fired, then the counter is
written into the user buffer and the counter is reset to O. Thus the
data returned to the user is the number of sample intervals between
Schmitt trigger firings.
If the counter overflows before Schmitt
trigger 1 fires, a 0 value is written into the user buffer. Sampling
may be started and stopped as for RTS (see Section 16.4.18) and all
input is double buffered with respect to the user task. The call is
issued as follows:
CALL HIST (ibuf,ilen,imode,irate,iefn,isb,[nbuf],
[ istart], [is top])
ibuf
An integer array that is to receive the input data values.

16-17

LABORATORY PERIPHERAL SYSTEMS DRIVERS
ilen
The length of ibuf (must be even and greater than or equal to 6).
imode
The start, stop, and sampling mode.
Its value is encoded
adding the appropriate function selection values shown below:
Function
Selection
Value

Meaning

128

Start of digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

irate

A 2-word integer array that specifies the time interval between
samples. The first word specifies the interval units as follows:
irate(l)

Unit

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the
signed integer.

interval

magnitude

16-bit

iefn
The number of the event flag that is to be set each time
buffer of data has been collected.

half

status

isb
2-word
returned.

integer

array

which

the

subroutine

nbuf
The number of buffers of data to be collected. It is needed only
if a function selection value of 16 has been added into imode.

16-18

LABORATORY PERIPHERAL SYSTEMS DRIVERS
is tart
The digital input point number to be used to trigger sampling
and/or the digital output point number to be set when sampling is
started. It is needed only if a function selection value of 128
or 64 has been added into imode.
is top
The digital input point number to be used to stop sampling.
It
is needed only if a function selection value of 32 has been added
into imode.
The isb array has the standard meaning described in Section 16.4.1.
When sampling is in progress, the first word of the isb array is 0 and
the second word contains the number of data values currently in the
buffer.

16.4.11

IDIR: Reading Digital Input

The IDIR FORTRAN subroutine or function reads the digital input
register as an unsigned binary integer, or as four binary-coded
decimal (BCD) digits.
In the latter case, the BCD digits are
converted to a binary integer before the value is returned to the
caller. The call is issued as follows:
CALL IDIR (imode,[ival],[isb])
imode
The mode in which the digital input register is to be read.
If
imode equals 0, then the digital input register is read as four
BCD digits and converted to a binary integer. Otherwise, it is
read as a 16-bit unsigned binary integer.
ival
A variable that receives the value read.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.
When the function form of the call is used, the value of the
is the same as that returned in ival.

16-19

function

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.12

!DOR: Writing Digital Output

The IDOR FORTRAN subroutine or function clears or sets bits in the
digital output register. The caller provides a mask word and output
mode. Bits in the digital output registers corresponding to the bits
specified in the mask word are either set or cleared according to the
specified mode. The call is issued as follows:
CALL IDOR (imode,imask,[newval] ,[isb])
imode
Whether the bits specified by imask are to be cleared or set in
the digital output register. If imode equals O, then the bits
are to be cleared. Otherwise, they are to be set.
imask
The bits to be cleared or set in the digital output register.
may be conveniently specified as an octal constant.

newval
A variable that receives the updated (actual) value written
the digital output register.

into

isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.
When the function form of the call is used, the value of the
is the same as that returned in newval.

16.4.13

function

IRDB: Reading Data from an Input Buffer

The IRDB FORTRAN subroutine or function retrieves data sequentially
from
a
buffer that a laboratory peripheral system driver is
synchronously filling. If no data is available when the call is
executed, the contents of the next location in the data buffer are
returned without updating the buffer pointers. The call is issued as
follows:
CALL IRDB (ibuf,[ival])

16-20

LABORATORY PERIPHERAL SYSTEMS DRIVERS
ibuf
An integer array that was previously specified in a
input sampling request (that is, DRS, HIST, or RTS).

synchronous

ival
A variable that receives the next value in the data buffer.
When the function form of the call is used, the value of the
is the same as that returned in ival.

16.4.14

function

LED: Displaying in LED Lights (LPSll only)

The LED FORTRAN subroutine displays a 16-bit signed binary integer in
the LED lights.
The number is displayed with a leading blank
{positive number)
or minus
(negative number), followed by five
non-zero-suppressed decimal digits that represent the magnitude of the
number.
LED digits are numbered right to left starting at 1 and
continuing to 5.
The number may be displayed with or without a
decimal point. The call is issued as follows:
CALL LED (ival,[idec],[isb])
ival
The variable whose value is to be displayed.
idec
The position of the decimal point. A value of 1 to 5 specifies
that a decimal point is to be displayed. All other values
specify that no decimal point is to be displayed.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.
For example, the following call:
CALL LED (-55,2)
would cause -0005.5 to be displayed in the LED lights.

16-21

LABORATORY PERIPHERAL SYSTEMS DRIVERS

16.4.15

LPSTP: Stopping an In-Progress Synchronous Function

The LPSTP FORTRAN subroutine selectively stops
request.
The call is issued as follows:

single

synchronous

CALL LPSTP (ibuf)
ibuf
An integer array that specifies a buffer that
specified in a synchronous initiation request.

16.4.lo

was

previously

PUTD: Putting a Data Item into an Output Buffer

The PUTD FORTRAN subroutine puts data sequentially into a buffer that
a
laboratory peripheral system driver is synchronously emptying.
If
no free space is available, no operation is performed.
The call is
issued as follows:
CALL PUTD (ibuf ,ival)
ibuf
An integer array which was previously specified in a
output request (SDO or SDAC).

synchronous

ival
A variable whose value is to be placed in the next free
in the data buffer.

16.4.17

location

RELAY: Latching an Output Relay (LPSll only)

The RELAY FORTRAN subroutine opens or closes the
call is issued as follows:

LPSll

relays.

relay

one,

The

CALL RELAY (irel,istate,[isb])
irel
Which relay is to be opened or closed (0 for
relay two).

for

istate
Whether the relay is to be opened or closed.
If istate equals O,
the relay is to be opened.
Otherwise, it is to be closed.
isb
A 2-word
returned.

integer

array

which

the

subroutine

status

The isb array has the standard meaning described in Section 16.4.1.

16-22

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.18

RTS: Initiating Synchronous A/D Sampling

The RTS FORTRAN subroutine reads one or more A/D channels at precisely
timed
intervals, with or without auto gain-ranging.
The auto
gain-ranging algorithm (LPSll only) causes the channels to be sampled
at the highest gain at which saturation does not occur.
Sampling can be started when the interface subroutine is called or
when a specified digital input point is set. A digital output point
can optionally be set when sampling is started.
Sampling can be
terminated by a program request (stop-in-progress request or kill
I/O), the clearing of a digital input point, or the collection of a
specified number of buffers of data.
All input is double buffered with respect to the user task. Each time
a half buffer of data has been collected, the user task is notified
(by the setting of an event flag)
that data is available to be
processed while the driver fills the other half of the buffer. Data
can be sequentially retrieved from the data buffer with the IRDB
routine (see Section 16.4.12), or the ADJLPS routine (see Section
16.4.5) can be used in conjunction with direct access to the input
data. The call is issued as follows:
CALL RTS (ibuf ,ilen,imode,irate,iefn,ichan,nchan,isb,
[nbuf], [istart], [istop])
ibuf
An integer array that is to receive the converted data values.
ilen
The length of ibuf (must be even and greater than or equal to 6).
imode
The start, stop, and sampling mode.
Its value is encoded by
adding together the appropriate function selection values as
shown below:
Function
Selection
Value

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

Auto gain-ranging (LPSll only)

16-23

LABORATORY PERIPHERAL SYSTEMS DRIVERS
irate
A 2-word integer array that specifies the time interval between
A/D samples.
The first word specifies the interval unit as
follows:
irate(l)

Unit

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the
unsigned integer.

interval

magnitude

16-bit

iefn
The number of the event flag that is to be set each time
buffer of data has been collected.

half

ichan
The starting A/D channel of the block of channels to be sampled
synchronously (must be between 0 and 63 for LPSll and between 0
and 15 for ARll).
nchan
The number of A/D channels to be sampled (must be between
64 for LPSll and between 1 and 16 for ARll).

and

status

isb

A 2-word
returned.

integer

array

which

the

subroutine

nbuf
The number of buffers of data that are to be collected.
It is
needed only if a function selection value of 16 has been added
into imode.
istart
The digital input point number to be used to trigger sampling
and/or the digital output point number to be set when sampling is
started. It is needed only if a function selection value of 128
or 64 has been added into imode. Points are numbered from 0 to
15, allowing a maximum of 16 points to be specified.
is top
The digital input point number to be used to stop sampling.
It
is needed only if a function selection value of 32 has been added
into imode.

16-24

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The values listed for ichan and nchan above are the maximum allowable
for each of the devices. In practice, they are constrained by the
number of channels available as specified during SYSGEN.
The isb parameter
16.4.1.

has

the

standard

meaning

described

Section

When sampling is in progress, the first word of the isb array is 0 and
the second word contains the number of data values currently in the
buffer.

16.4.19

SDAC: Initiating Synchronous D/A Output

The SDAC FORTRAN subroutine writes data into one or more external D/A
converters at precisely timed intervals. Output may be started and
stopped as for RTS (see Section 16.4.18), and all input is double
buffered with respect to the user task. One full buffer of data must
be available when synchronous output is initiated.
After SDAC has initiated output and the specified event flag has been
set to notify the task that free buffer space is available, the PUTD
routine (see Section 16.4.16) may be used to put data values
sequentially into the output data buffer. The ADJLPS routine (see
Section 16.4.5) may be used in conjunction with direct access to the
output data buffer. The SDAC call is issued as follows:
CALL SDAC (ibuf ,ilen,imode,irate,iefn,ichan,nchan,isb,
[nbuf], [istart], [istop])
ibuf
An integer array that contains the output data valueso
ilen
The length of ibuf (must be even and greater than or equal to 6).
imode
The start, stop, and sampling mode.
Its value is encoded by
adding together the appropriate function selection values as
shown below:
Function
Selection
Value

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

16-25

LABORATORY PERIPHERAL SYSTEMS DRIVERS
irate
A 2-word integer array that specifies the time interval between
D/A outputs.
The first word specifies the interval units as
follows:
irate(!)

Unit

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the
unsigned integer.

interval

magnitude

16-bit

iefn
The number of the event flag that is to be set each time
buffer of data has been output.

half

ichan
The starting D/A channel of the block of channels to be written
into synchronously (must be between 0 and 9 for LPSll, and be 0
or 1 for AR l l ) .
nchan
The number of D/A channels to be written into (must be between
and 10 for LPSll, and be 1 or 2 forARll).

A 2-word
returned.

isb
integer

array

which

the

subroutine

status

nbuf
The number of buffers of data to be output. It is needed only if
a function selection value of 16 has been added into imode.
istart
The digital input point number to be used to trigger sampling
and/or the digital output point number to be set when sampling is
started. It is needed only if a function selection value of 128
or 64 has been added into imode. Points are numbered from 0 to
15, allowing a maximum of l~ points to be specified.

16-26

LABORATORY PERIPHERAL SYSTEMS DRIVERS
istop
The digital input point number to be used to stop sampling.
It
is needed only if a function selection value of 32 has been added
into imode.
The isb array has the standard meaning described in Section 16.4.1.
When sampling is in progress, the first word of the isb array is 0 and
the second word contains the number of free positions in the buffer.

lhe4e20

SDO: Initiating Synchronous Digital Output

The SDO FORTRAN subroutine writes data qualified by a mask word into
the digital output register at precisely timed intervals. Sampling
may be started and stopped as for RTS (see Section 16e4cl8) and all
input is double buffered with respect to the user task. One full
buffer of data must be available when output is initiated.
After SDO has initiated output, and the specified event flag has been
set to notify the task that free buffer space is available, the PUTD
routine (see Section 16.4.16) may be used to put data values
sequentially into the output data buffer. The ADJLPS routine (see
Section 16.4.5) may be used in conjunction with direct access to the
output data buffer. The SDO call is issued as follows:
CALL SDO (ibuf,ilen,imode,irate,iefn,imask,isb,[nbuf],
[ istart], [is top])
ibuf
An integer array that contains the digital output values.
ilen
The length of ibuf (must be even and greater than or equal to 6).
imode
The start, stop, and sampling mode.
Its value is encoded by
adding together the appropriate function selection values as
shown below:
Function
Selection
Value

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

16-27

LABORATORY PERIPHERAL SYSTEMS DRIVERS
irate
A 2-word integer array that specifies the time interval between
digital outputs. The first word specifies the interval units as
follows:
Unit

irate(l)
1

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the
unsigned integer.

interval

magnitude

16-bit

iefn
The number of the event flag that is to be set each time
buffer of data has been output.

half

The digital output points that are to be written.
conveniently specified as an octal constant.

may

A 2-word
returned.

status

imask

isb
integer

array

which

the

subroutine

nbuf
The number of buffers of data to be output.
It is needed only if
a function selection value of 16 has been added into imode.
istart
The digital input point number to be used to trigger sampling
and/or the digital output point number to be set when sampling is
started. It is needed only if a function selection value of 128
or 64 has been added into imode. Points are numbered 0 through
15, allowing a maximum of 16 points to be specified.
is top
The digital input point number to be used to stop sampling.
It
is needed if a function selection value of 32 has been added into
imode.
The isb parameter
16.4.1.

has

the

standard

meaning

described

Section

When sampling is in progress, the first word of the isb array is 0 and
the second word contains the number of free positions in the buffer.

16-28

LABORATORY PERIPHERAL SYSTEMS DRIVERS

16.5

STATUS RETURNS

The error and status conditions listed in Table 16-8 are returned by
the Laboratory Peripheral System drivers described in this chapter.
Table 16-8
Laboratory Peripheral Systems Status Returns
Code

rs.sue

IS.PND

I/O request pending
The operation specified in the QIO
not yet been completed.

IE.ABO

IE.BAD

directive

has

The specified I/O operation was canceled
IO.KIL or IO.STP) while in progress.

{by

Operation aborted

Bad parameter
An illegal specification was supplied for one or
more of the device-dependent QIO parameters {words
6-11). The second I/O status word is filled with
Os.

IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a data buffer but
only
word alignment is legal for Laboratory
Peripheral Systems. Alternatively, the length of
a buffer is not an even number of bytes.

IE.DAO

Data overrun
For Laboratory Peripheral Systems, the driver
attempted to get a value from the user buffer when
none was available or attempted to put a value in
the user buffer when no space was available.

IE.DNR

Device not ready
The physical device unit specified in the QIO
directive was not ready to perform the desired I/O
operation.
For Laboratory Peripheral Systems,
this code is returned if a device time-out occurs
while a function is in progress. The second I/O
status word contains the number of free positions
in the buffer, as appropriate.
{continued on next page)

16-29

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-8
(Cont.)
Laboratory Peripheral Systems Status Returns
Code
IE.IEF

Reason
Invalid event flag number
An invalid event flag number was
synchronous function.

IE.IFC

specified

Illegal function
A function code was included in an I/O
that is illegal for the LPSll or ARll.

IE.NOD

request

Insufficient buffer space
Dynamic storage space has been depleted, and there
is insufficient buffer space available to allocate
a secondary control block for a
synchronous
function.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified
in the QIO directive was not on line.
When the system was booted, a device
check
indicated that this physical device unit was not
in the configuration.

IE.ONP

Option not present
An option dependent function or subfunction was
requested,
and the required feature was not
specified at system generatione
For example the
gain-ranging option or D/A option is not present.
The second I/O status word contains O.

IE.PRI

Privilege violation
The task which issued the request
was
not
privileged
to
execute
that
request.
For
Laboratory Peripheral Systems, a checkpointable
task attempted
to execute a synchronous sampling
function.

IE.RSU

Resource in use
A resource needed by the function requested in the
QIO directive was being used (see Section 16.5.1).

IE.SPC

Illegal address space
The buffer specified for a read or write request
was partially or totally outside the address space
of the issuing task.
Alternately a byte count of
0 was specified.
The second
I/O status word
contains O.

FORTRAN interface values for these status
Section ln.5.4.

16-30

returns

are

presented

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16• 5•1

IE • RS U

IE.RSU is returned if a function requests a resource that is currently
being used.
The requesting task may repeat the request at a later
time or take any alternative action required.
Because certain functions do not need such resources, they never cause
this code to be returned. Other functions return this code under the
following conditions:
Function

When IE.RSU Is Returned

IO. SDO

One or more specified digital output bits are in
use.

IO.ADS

Digital output point (if specified) is in use.

IO. HIS

Digital output point (if specified) is in use.

IO.MDA

Digital output point (if specified) is in use.

IO. MDI

Digital output point: (if specified) or digital
input points to be sampled are in use.

IO.MDO

Digital output point (if specified) or output bits
to be written are in use.

The following components of the Laboratory Peripheral Systems are each
considered a single resource:
Resource

When Shareable

The A/D Converter
and clock

Always shareable

Each bit in the
digital output
register

Never shareable.

Each bit in the
digital input
register

Always shareable when used by IO.SDI
or for start/stop conditions (specified
in subfunction modifier bits), even when
in
use
by another function;
when
specified by a synchronous digital input
function, not shareable with another
such function

Each resource is allocated on a first-come-first-served basis.
(That
is, when a conflict arises, the most recent request is rejected with a
status of IE.RSU).

16.5.2

Second I/O Status Word

On successful completion of a function specified in a QIO macro call,
the rs.sue code is returned to the first word of the I/O status block.
Table 16-9 lists the contents of the second word of the status
on successful completion for each function.

16-31

block,

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-9
Returns to Second Word of I/O Status Block
Successful
Function

Contents of Second Word

IO.KIL

Number of data values before I/O was canceled

IO.LED

IO.REL

IO.SDI

Masked value read from digital input register

IO.SDO

Updated value written into digital output register

IO.ADS

Number of data values remaining in buffer

IO.HIS

Number of data values remaining in buffer

IO.MDA

Number of free positions in buffer

IO.MDI

Number of data values remaining in buffer

IO.MDO

Number of free positions in buffer

IO.STP

When IE.BAD is returned, the second I/O status word contains O/
Laboratory Peripheral Systems drivers return the IE.BAD code under the
following conditions:
When IE.BAD is Returned

Function

16.5.3

IO.REL

Relay number not 0 or 1

IO.ADS
IO.MDA

No I/O status block, illegal digital I/O point
number, or illegal channel number

IO.HIS
IO.MDI
IO.MDO

No I/O status block or illegal
digital I/O point number

IO.ADS and ADC Errors

While IO.ADS or the ADC FORTRAN subroutine is converting a sample, two
error conditions may arise. Both of these conditions are reported to
the user by placing illegal values in the data buffer.
A -1
(177777(8)
is placed in the buffer if an A/D conversion does not
complete within 30 microseconds. A -2 (177776(8)
is placed in the
buffer if an error occurs during an A/D conversion (LPSll only).

16-32

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.5.4

FORTRAN Interface Values

The values listed in Table 16-10 are returned
calls.

FORTRAN

subroutine

Table 16-10
FORTRAN Interface Values
Status Return

FORTRAN Value

rs. sue

+01
+00
+315
+101
+334
+301
+319
+313
+303
+100
+302
+99
+323
+365
+305
+316
+317
+102
+306
+08
+04

IS.PND
IE.ABO
IE.ADP
IE.ALN
IEeBAD
IE.BYT
IE.DAO
IE.DNR
IE.IEF
IE.IFC
IE. ILU
IE.NOD
IE.OFL
IE.GNP
IE.PR!
IE.RSU
IE.SDP
IE.SPC
IE.ULN
IE. UPN

16.6

I
I
I

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the Laboratory Peripheral Systems
drivers described in this chapter.

16.6.1

The LPSll/ARll Clock and Sampling Rates

The basic real-time clock frequency (count rate) for all synchronous
functions
is always lOKHz.
Device characteristics word 4 contains a
lo-bit buffer preset value -- set dynamically or at system generation,
that controls the rate of "ticks" (that is, the rate at which the
clock interrupts).
The quotient that results when this value is
divided
into lOKHz is the rate of "ticks." For example, if this value
is 2, the "tick" rate is 5KHz.
The user can use a Get LUN Information
system directive to examine the value and a SET /BUF MCR function to
modify it while the system is running.

16-33

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The ticks parameter in a synchronous function specifies the number of
"ticks" between samples or data transfers. The value of ticks is a
16-bit number. Thus 65,536 discrete sampling frequencies are possible
for each of ~5,536 different "tick" rates. This provides a maximum
single-channel sample rate of 1 sample every 100
microseconds
(possible in hardware but impractical in software) and a minimum of 1
sample every 429,495 seconds. A single-channel rate greater than 2KHz
is possible, but not recommended.
The figures below represent initial timing tests run under RSX-llM.
It should be noted that no computation was performed on the data other
than continuously removing it from or inserting it into the data
buffer.
The following data is for the LPSll on a PDP-11/40 with memory
management, with no gain-ranging option, and with digital I/O option.
Analog rates:
1 request for 1 channel at 2.5KHz
1 request for 2 channels at 2.0KHz (aggregate 4KHz)
2 requests for 1 channel at 2.0KHz (aggregate 4KHz)
Digital rates:
1 request for 2 channels at 2.5KHz (aggregate 5KHz)
The following data is for the ARll on a PDP-11/40 with no
management, no digital I/O option, and no unipolar sampling.

memory

Analog rates:
1 request for 1 channel at 3.3KHz
1 request for 2 channels at 2.5KHz (aggregate 5.0KHz)

2 requests for 1 channel at 2.5KHz (aggregate 5.0KHz)

Digital rate:
2 requests for 2 channels at 3.3KHz (aggregate 6.6KHz)

16.6.2

Importance of the I/O Status Block

An I/O status block must be specified with every synchronous function.
If the first I/O status word is nonzero, the request has been
terminated and the value indicates the reason for termination~
Otherwise, the request is in progress, and the second I/O status word
contains the number of data values remaining in the buffer (or the
number of free positions in the buffer for IO.MDA and IO.MDO).

16-34

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.6.3

Buffer Management

The buffer unload protocol for synchronous input functions
is
described below.
The user constructs a 5-word block that contains the
following:
IOSB:
CURPT:
LSTPT:
FSTPT:

.BLKW
.WORD
.WORD
.WORD

I/O STATUS
ADDRESS OF
ADDRESS OF
ADDRESS OF

BUFFER
BUFFER+n
BUFFER

DOUBLE-WORD
BUFFER
END OF BUFFER
BUFFER

and
Two of these words are required by the driver (I/O status block)
the remaining three by the user to unload data values from the buffer.
The user then issues the I/O request with the appropriate parameters
and the address of the above block as the I/O status block.
The QIO
directive Os both I/O status words to initialize them.
If the driver accepts the request 1 it sets up a write pointer to the
first word
in the user buffer.
Thus, the user has a buffer read
the
pointer and the driver has a buffer write pointer.
The user and
driver share the second I/O status word, which is the number of data
words in the buffer that contain data.
Each time the driver attempts to put a sample value into the buffer,
it increments the second I/O status word and compares the result with
the size of the buffer.
If the result is greater, buffer overrun has
occurred and
the request is terminated.
Otherwise, the value is
stored in the buffer at the address specified by the driver's write
pointer and the write pointer is updated.
If the value stored in the user buffer fills half of the buffer,
the
event flag specified in the I/O request is set in order to notify the
user that a half buffer of data is available to be processed.
Each
time the user task is awakened, it should execute the following code:
5$:
10$:

20$:
30$:

40$:

CLEF$S
#EFN
;CLEAR EFN
TST
IOSB+2
;ANY DATA IN BUFFER?
BEQ
30$
;IF EQ NO
MOV
@CURPT,RO
;GET NEXT VALUE FROM BUFFER
DEC
IOSB+2
;REDUCE NUMBER OF ENTRIES
ADD
#2,CURPT
;UPDATE BUFFER READ POINTER
CMP
CURPT,LSTPT
;END OF BUFFER?
BLOS
20$
;IF LOS NO
MOV
FSTPT,CURPT
;RESET BUFFER READ POINTER
Process data value
BR
10$
;TRY AGAIN
TSTB
IOSB
;REQUEST TERMINATED?
BNE
40$
;IF NE YES
WTSE$S
#EFN
;WAIT FOR EFN
BR
5$
;
Determine reason for termination

ln-35

LABORATORY PERIPHERAL SYSTEMS DRIVERS
For IO.MDA and IO.MOO, this protocol differs slightly. The user task
maintains a write pointer and the driver a read pointer. The entire
buffer must be full when the request is executed.

16.6.4

Use of AQJLPS for Input and Output

The following FORTRAN example illustrates the
using ADJLPS for synchronous input and output.

proper

protocol

Synchronous input:
DIMENSION IBF(l004) ,IERR(2) ,INTVL{2)

c
C INITIATE SYNCHRONOUS A/D SAMPLING,

INTVL{l)=2
INTVL(2)=5
CALL RTS(IBF,1004,160,INTVL,IEFN,6,6,IERR,50,l4,15)

c
C INITIALIZE HALF BUFFER INDEX

c
INDX=4

c
c WAIT FOR HALF BUFFER OF DATA
c
c

CALL WAITFR(IEFN)

C CLEAR EVENT FLAG

CALL CLREF ( IEFN)

c
c PROCESS HALF BUFFER OF DATA
c

SUM=O
DO 20 I=l,500
SUM=SUM+CVSWG(IBF(I+INDX))
CONTINUE
AVERG=SUM/500

C FREE HALF BUFFER FOR MORE DATA

CALL ADJLPS(IBF,500)

C ADJUST BUFFER INDEX

c
c

INDX=INDX+500
IF(INDX.GE.1004) INDX=4

C CHECK IF ANOTHER HALF BUFFER OF DATA IS AVAILABLE

IF(IERR(2) .GE.500 GO TO 15
IF(IERR(l) .NE.0) GO TO end of sampling
GO TO 10

16-36

for

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Synchronous output:
DIMENSION IBF(l004) ,IERR(2) ,INTVL(2)

c
C FIRST BUFFER OF DATA MUST BE AVAILABLE AT START

C THIS EXAMPLE ASSUMES FIRST BUFFER IS FULL AT START

c
C START SYNCHRONOUS DIGITAL OUTPUT FUNCTION

INTVL(l)=2
INTVL(2)=5
CALL SDO(IBF,1004,160,INTVL,IEFN,MASK,IERR,50,14,15)

c
C INITIALIZE HALF BUFFER INDEX

INDX=4

c
C WAITFOR ROOM IN BUFFER

c
c

CALL WAITFR(IEFN)

C CLEAR EVENT FLAG

c
15

CALL CLREF(IEFN)

c
C CALCULATE VALUES TO PUT IN BUFFER

X=(Y+2)*Z
DO 20 I=l,500
IBF(I+INDX)=X**5/A
CONTINUE

c
C SIGNIFY ANOTHER HALF BUFFER IS FULL

c
c

CALL ADJLPS(IBF,500)

C ADJUST BUFFER INDEX

c
INDX=INDX+500
IF(INDX.GE.1004)

INDX=4

c
C CHECK IF ANOTHER HALF BUFFER IS EMPTY

c
IF(IERR(2) .GE.500) GO TO 15
IF(IERR(l) .NE.O) GO TO end of sampling
GO TO 10
NOTE
In both of the examples above, care is taken to ensure
that the program stay "in sync" with the driver.
If the
program "loses" its position with respect to the driver,
the function must be stopped and restarted, since this is
the only way to recover.
Caution should be exercised to
ensure that the program sequence above be used to avoid a
possible loss of data.

ln-37

INDUSTRIAL CONTROL SUBSYSTEMS

QIO DPB format:
QIO$e IO.SAO, ••• ,<chn,vout>
chn

The output channel number.
vout

The output voltage representation.
Output voltage varies linearly with the binary input to the channel,
where O to plus 10 volts (+lOv.) is represented by integers from 0 to
1023.
Return Status:
rs.sue - Function submitted for output to controller.
IE.MOD - Nonexistent D/A channel was specified.
The second I/O status word is O.

18.3.4

Momentary Digital Output - Multi-Point

This function provides the capability of pulsing a field of up to 16
momentary (single-shot) digital output points. Fields must be aligned
on module boundaries.
QIO DPB format:
QIO$e IO.MSO, ••• ,<opn,dp>
opn

The starting digital output point number. Point number must be
aligned on a module boundary (that is, must be a multiple of 16).
dp

The 16-bit mask. One point is pulsed corresponding to
set in the mask word.

each

bit

Return Status:
rs.sue - Function submitted for output to the controller.
IE.MOD - Invalid starting point number specified.
Point
nonexistent or not aligned on a module boundary.

18-16

CHAPTER 17
PAPER TAPE READER/PUNCH DRIVERS

17.1

INTRODUCTION

The RSX-llM/M-PLUS paper tape reader/punch drivers support the PCll
paper tape reader/punch and the PRll paper tape reader. The PCll is a
high-speed reader/punch capable of reading 8-hole, unoiled, perforated
paper tape at 300 characters per second, and punching tape at 50
characters per second. The PRll has the same characteristics as those
of the paper tape reader portion of the PCll. All transfers are image
mode only, with no interpretation of data.

17.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the GET LUN INFORMATION system
directive {the first characteristics word)
contains the following
information for paper tape devices. A bit setting of 1 indicates that
the described characteristic is true for these devices.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Mass storage device

User-mode diagnostics supported

Device supports 22-bit direct addressing

Unit software write-locked

Input spooled device

Output spooled device

Meaning

17-1

PAPER TAPE READER/PUNCH DRIVERS
Bit

Setting

Pseudo device

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Meaning

Words 3 and 4 of the buffer are undefined;
word 5 indicates
default buffer size, which is 64 bytes for paper tape devices.

17.3

the

QIO MACRO

Table 17-1 lists the standard functions of
valid for the paper tape reader/punch.

the

QIO

macro

that

are

Table 17-1
Standard QIO Functions for the Paper Tape Reader/Punch
Function

Format
QIO$C

IO.ATT, •••

Attach device

QIO$C

IO.DET, •••

Detach device

QIO$C

IO.KIL, •••

Cancel I/O requests

QIO$C

IO.RLB, ••• ,<stadd,size>

READ logical block (reader only)

QIO$C

IO.RVB, ••• ,<stadd,size>

READ virtual block (reader only)

QIO$C

IO.WLB, ••• ,<stadd,size>

WRITE logical block (punch only)

QIO$C

IO.WVB, ••• ,<stadd,size>

WRITE virtual block {punch only)

stadd
The starting address of
boundary)

the

data

buffer

(may

byte

size
The data buffer size in bytes (must be greater than 0)
IO.KIL never cancels an in-progress read request.
In-progress write
requests are canceled only when the punch driver is waiting for the
punch to become ready at the start of a transfer.
The paper tape drivers support no device-specific functions.

17-2

PAPER TAPE READER/PUNCH DRIVERS
17.4

STATUS RETURNS

Table 17-2 lists error and status conditions that are returned by
paper tape reader/punch drivers.

the

Table 17-2
Paper Tape Reader/Punch Status Returns
Code

rs.sue

Reason
Successful completion
The operation specified
in the QIO directive was
completed successfully.
The second word of the I/O
status block can be examined to determine the number
of bytes processed, if the operation involved reading
or writing.

IS.PND

I/O request pending
The operation specified in the QIO directive has not
yet been executed.
The I/O status block is filled
with Os.

IE.ABO

Operation aborted
The I/O request was cancelled while
while still in the I/O queue.

IE.DAA

progress

Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.
This code indicates that the issuing task has already
attached the desired physical device unit, not that
the unit was attached by another task.

IE.DNA

Device not attached
The physical device unit specified in an IO.DET
function was not attached by the issuing task. This
code has no bearing on the attachment status of other
tasks.

IE.DNR

Device not ready
The reader and punch drivers return this code when a
time-out occurs. The reader driver also returns this
code when an error condition (see Section 17.4.1)
is
encountered
before the initiation of the first
transfer after an ATTACH command has been issued.

IE.EOF

End-of-file encountered
The reader driver encountered an error condition (see
Section 17.4.1)
at a time other than the initiation
of the first read after a valid ATTACH command.
The
second word of the I/O status buffer contains a count
of bytes successfully read before the error condition
was encountered.
(continued on next page)

17-3

PAPER TAPE READER/PUNCH DRIVERS
Table 17-2
(Cont.)
Paper Tape Reader/Punch Status Returns
Code

Reason

IE.IFC

Illegal function
An illegal function code was specified in an I/O
request that is not legal for the respective paper
tape drivers.

IE.OFL

Device off line
The physical device unit associated with the LUN
specified in the QIO directive was not on line. When
the system was booted, a device check indicated that
this
physical
device
unit
was
not
in the
configuration.
Illegal address space

IE.SPC

The buffer specified for a read or write request was
partially or totally outside the address space of the
issuing task.
Alternatively, a byte count of O was
specified.
IE.VER

Unrecoverable hardware error (punch only)
The punch driver encountered an error condition
(see
Section 17.4.1)
at a time other than the initiation
of a transfer.
Section 17.4.2 describes the action
of the punch driver when an error condition is
encountered upon the initiation of a transfer.

17.4.1

Error Conditions

There are four error conditions that are
paper tape drivers.
These conditions are:

the

When the punch driver encounters an error condition upon
initiation of a transfer, the following message is displayed:

the

•

No tape

•

Reader off line

•

Power low

•

Hardware malfunction

17.4.2

indistinguishable

Ready Recovery

*** PPn:

-- NOT READY

The unit number of the paper tape punch that is not ready.

17-4

PAPER TAPE READER/PUNCH DRIVERS
This message is repeated every 15 seconds until the error condition is
corrected, or until the I/O request is canceled. When the error
condition has been corrected, the transfer will begin within 1 second.

17.5

PROGRAMMING HINTS

information
on
important
programming
This
section
contains
considerations relevant to users of the paper tape drivers described
in this chapter.

17.5.1

Special Action Resulting from Attach and Detach

When an Attach or Detach is issued to the punch, the punch driver
initiates a transfer of 170
(decimal) nulls.
Upon the first read
after an attach to the reader, all nulls preceding the first non-null
character on the tape are read and discarded by the reader driver.

17.5.2

Reading Past End-of-Tape

When the reader driver reads past the physical end-of-tape,
it
normally generates at least two incorrect data bytes. These bytes are
included in the byte count returned by the driver.
User software that
does not prevent reads past the physical end-of-tape should discard at
least the last six characters in the buffer when IE.EOF is returned by
the driver.

17-5

INDUSTRIAL CONTROL SUBSYSTEMS

18.3.5

Bistable Digital Output - Multi-Point

This function provides the capability of setting or resetting a
field
of up to 16 bistable digital output points.
Fields must be aligned on
a module boundary.
QIO DPB format:
QIO$C IO.MLO, ••• ,<opn,pp,dp>
opn
The starting digital output point number.
Point number must be
aligned on a module boundary {that is, must be a multiple of 16).
pp
The 16-bit mask.
dp
The data pattern.
A bit is set in the mask word for each point that may change state.
The state of points corresponding to reset mask bits is unaltered.
When the mask bit is set, the output is "closed" if the data bit is
set and "open" if the data bit is clear.
Return Status:

rs.sue - Function submitted for output to the controller.
IE.MOD - Invalid starting point number specified.
Point does not
exist or is not aligned on a module boundary.

18.3.n

Unsolicited Interrupt Processing

Unsolicited interrupts consist of the following:
1.

Digital interrupts

Counter interrupts

Remote terminal input

Hardware errors

Based on the type of interrupt,
the driver may
interrupt data in one or more of the following ways:

dispose

the

The data may be furnished to a task that has issued a request
to monitor such information continually.
This alternative is
not available in the DSS/DRS driver.

A task may be activated by a
specific
input.
That is,
a
dormant task can be requested to run, or an event flag may be
set if the task is currently active.

18-17

CHAPTER 18
INDUSTRIAL CONTROL SUBSYSTEMS

18.1

INTRODUCTION

This chapter describes RSX-llM drivers for two process I/O subsystems:
the
ICS/ICRll and the DSS/DRSll=
(Driver support for these I/O
subsystems is not provided in RSX-llM-PLUS systems.)
ICSll and
rCRll are local and
remote process
r/o
subsystems,
respectively.
They operate under program control as devices capable
of interrogating digital and analog input, and driving digital and
analog output.
DSSll and DRSll are digital input and output subsystems, respectively.
Under program control they drive digital output and interrogate
digital input.

18.1.1

Hardware Configuration

A single res or rcR controller can handle up to 16 I/O modules in any
configuration;
a module contains 16 bits of input or output data,
providing a total of 256 digital points.
Up to 12 rcR or
res units
are supported.
The
rcs/rCR driver is tailored to the user's needs,
interactively,
through the SYSGEN
(System
Generation
program)
dialogue.
The driver is capable of handling any combination of rcR or
res controllers installed on a single system.
The DSSll provides 49 optically isolated
inputs,
including
48
nonbuffered, sense-data inputs and one interrupt input.
The DRSll
provides 48 open-collector, buffered outputs plus one interrupt input.
The DSS/DRS driver is shaped to the user's system configuration in the
SYSGEN dialog.
The driver supports up to 16 DSSll and/or DRSll
modules.

18.1.1.1 ICS/ICR Address Assignments - Each rCRllA Unibus interface
or rcs11 file box must be configured at SYSGEN time for individually
addressable interrupt vectors, Control and Status Registers
(rCSR),
and module Address Registers (rCAR), as shown in Table 18-1.

18-1

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-1
ICS/ICR Address Assignments
Interrupt Vectors

ICS/ICR Unit No.

Module Addresses

ICSR/ICAR Addresses

i 7i000-i 7i036

i 7i 770-i 7i 776

234-236

l 71040-171076

171760-171766

xxx-xxx+2

171100-171136

l 71750-171756

xxx+4-xxx+6

171140-171176

171740-171746

xxx+10-xxx+12

171200-171236

l 71730-171736

xxx+l4-xxx+l6

l 71240-1 71276

1 71720-171726

xxx+20-xxx+22

1 71300-171336

171710-171716

xxx+24-xxx+26

171340-171376

l 71 700-1 71 706

xxx+30-xxx+32

171400-171436

171670-171676

xxx+34-xxx+36

171440-171476

l 71660-1 71666

xxx+40-xxx+42

171500-171536

171650-171656

xxx+44-xxx+46

171540-171576

1 71640-1 71646

xxx+50-xxx+52

NOTES
nnnnn6
nnnnn4

Control and Status Register
Address Register

Additional controllers
addresses above 300.

are

assigned

vector

18.1.1.2 DSS/DRS Address Assignments - Unlike the ICS/ICR
DSS/DRS devices are not restricted
to specified bus
However, the following constraints apply:

subsystem,
addresses.

All DSSll modules
addresses.

must

occupy

contiguous

set

bus

All DRSll modules
addresses.

must

occupy

contiguous

set

bus

The total number of DSSll and DRSll modules

not

exceed

may

16.
4.

system,
the DRSll
If both module types are installed in a
must occupy the lower set of bus and _ interrupt-vector
addresses.

Bus request priority is BR4.

18-2

INDUSTRIAL CONTROL SUBSYSTEMS
18.1.1.3 Supported ICS/ICR I/O Modules - The following
optional, are supported by the ICS/ICR driver:

modules,

all

D/A Converters
IDA-QA -

4-channel digital-to-analog converter

A/D Converters
IAD-IA IMX-IA -

8-channel wide-range differential
analog-to-digital
converter
16-channel flying capacitor relay multiplexer

Counters
IDC-IC -

16-bit binary counter

Bistable Digital Outputs
IDC-OA
IAC-OA
IRL-OA
IRL-OB

D/C flip-flop driver
A/C flip-flop driver
Bistable relay output
Flip-flop relay output

Momentary Digital Output
IDC-OB IAC-OB -

D/C momentary driver
A/C momentary driver

Digital Inputs (Noninterrupting)l
IDC-IA IDC-ID IAC-IA -

D/C voltage sense input
D/C voltage input module
A/C voltage input module

Digital Inputs (Interrupting)
IDC-IB IAC-IB -

D/C voltage interrupt input
A/C voltage interrupt input

Terminal Input/Output
110 CPS Remote Terminal Interface to ICRll

18.1.2

Alternate ICSll Support

The ICSll Industrial Control Subsystem is supported either by the
UDCll or ICS/ICRll device driver.
If the system does not have an
ICRll controller, and if a driver of minimum size is required,
then
UDCll support should be considered.
The hardware requirements for
such support are as follows:
1.

Each file box must be assigned to the same
address (normally 234).

The control and status register within each file box must
appear at the same address within the I/O page (normally
17177~\

_,_I

..L

IV}

interrupt

vector

•

1. Note that noninterrupting input modules are accessed directly by a
task.
Hence, while FORTRAN interface routines are available, no
support for such modules is included in the driver.
18-3

INDUSTRIAL CONTROL SUBSYSTEMS
If support of the IAD-IA A/D converter is required, the
module addressing and installation conventions are imposed:

following

Each
IAD-IA
converter
and
associated
IMX-IA
relay
multiplexers are assigned a fixed block of 120 logical
channel numbers. No more than 32 IAD-IA converters may be
installed in a single system. Based on this convention, A/D
converter 0 occupies channels 0-119, A/D converter 1 occupies
120-239, and so forth.

Regardless of the actual number of IMX-IA multiplexers
preempts a block of eight
installed,
each
converter
contiguous module slots.

The slots reserved for all A/D converters and
must occupy a block of contiguous module slots.

multiplexers

If necessary, Field Service personnel can make the vector and address
changes. Assuming the hardware configuration is correct, the user can
implement the desired UDCll software support by answering in the
affirmative all SYSGEN questions relating to the UDCll.
If the additional ICS/ICR-11 driver features are required
(at a
commensurate increase in the memory requirements), then each ICSll
file box must be configured for individually addressable interrupt
vectors and control status registers. This change can be performed by
Field Service personnel.
The
necessary
software
support
is
incorporated by answering in the affirmative all SYSGEN questions
relating to the ICS/ICRll.
The additional ICSll capabilities provided by the ICS/ICRll driver may
be summarized as follows:
1.

Multicontroller, parallel operation

Increased A/D conversion throughput

Activation of
counters

No requirement to
contiguous slots

digital

interrupts

same

type

Section 18.7 summarizes the software differences between the
ICS/ICR drivers in detail.

UDC

and

18.1.3

tasks

directly
install

from

modules

the

Software Support

Both ICS/ICR and DSS/DRS operations are divided into two categories:
1.

Functions performed directly by any task

Functions requiring driver services

Direct functions are accomplished through memory references to the
ICS/ICR or DSS/DRS registers on the I/O page.
In a protected system
any task may gain restricted access to the device registers by linking
to a global common block that resides within the appropriate physical
memory limits. Direct functions consist of:
1.

Reading counter modules

Reading any digital input module (DSS)

18-4

INDUSTRIAL CONTROL SUBSYSTEMS
NOTE
All functions listed in this subsection
apply to ICS/ICR modules. Those which
also apply to the DSS
and/or
DRS
subsystems are so marked.
Driver requests are divided into the following categories:
1.

Noninterrupting output functions
a.

Bistable (flip-flop) digital output (DRS)

Analog output

Momentary (single-shot) digital output

Requests for interrupting functions
a.

Analog input

Remote terminal output

Requests for unsolicited interrupts
a.

Digital interrupts (DSS/DRS)

Counter interrupts

Remote terminal input

Remote unit or serial line errors

With the exception of A/D input and remote terminal
functions are complete upon return to the user's task.

output,

all

Under RSX-llM, noninterrupting output functions are
immediately
submitted to the controller through a circular buffer that is filled
at driver level and emptied at interrupt level. A QIO is considered
successfully completed when the request is inserted in the circular
buffer.
The following operations are in this category:
1.

Bistable digital outputs

Analog outputs

Momentary digital outputs

Interrupting functions are those operations that generate an interrupt
within some fixed time after initiation. The driver allows a list of
multiple transactions to be specified in a single QIO.
Each
transaction is initiated in sequence without waiting for the preceding
interrupt, until either the list is exhausted or all modules of the
specified type are active.
The following operations are in this
category:
le

A/D inputs

Remote terminal output

18-5

INDUSTRIAL CONTROL SUBSYSTEMS
Unsolicited interrupts may require no initiation by the processor and
occur at indeterminate intervals. The following functions are in this
category:
1.

Interrupting digital inputs (DSS/DRS)

Counter modules

Remote terminal input

Error interrupts

All unsolicited interrupt data, except for errors, may be placed in a
task-provided circular buffer. On interrupt, an event flag specified
by the task is set. Such data for each module type is supplied to
only one task per controller. In addition, the driver will activate
selected tasks on the occurrence of digital or terminal input
interrupts.
Error interrupts are described later in this chapter.
Terminal support is restricted to passing terminal data between the
device and a task.
The only special character is Control-C (003),
which may cause a user-specified task to be made active. There is no
other special processing for terminal I/O except that the parity bit
is removed. This is similar to the terminal driver function of
IO.RAL.
1.

MCR is not invoked.

Characters are not echoed.

Carriage control is not performed.

TABs, RUBOUTs, and so forth are not recognized.

Line terminators are not recognized.

Fill characters are not generated.

18.1.4

UDCll Software Compatibility

Many of the MACRO and FORTRAN interfaces described in the following
paragraphs are fully compatible with existing UDCll applications
software; however, the user should consult Section 18.7 for a summary
of differences that do exist between UDC and ICS/ICR software.

18.1.5

Module Addressing Conventions

Table 18-2 illustrates the relationship between physical slot numbers,
bus
addresses
and
relative
addresses
for
a given ICS/ICR
configuration. It is referred to in the following discussion.
Each A/D converter is assigned a block of 120 channels. The number of
channels in use within the block depends on the number of multiplexers
installed. Specifically, each A/D converter has eight channels, and
each associated multiplexer has 16.

18-6

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-2
Sample ICS/ICR Configuration
Unit:

Module
Number

Slot
Number

Type

Bus Address

9.
10.
11.
12.
13.
14.
15.
16.
17.

D/A converter
A/D converter
A/D multiplexer
Counter
Flip-flop driver
D/A converter
Flip-flop driver
Counter
A/D converter

171000
171002

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

Relative Addresses
0-3.
0-119.

------

-----

171006
171010
171012
171014
171016
1 71020

0
0-15.
4-7.
16.-31.
1.
120.-239.

As noted, a block of 120 relative addresses is reserved for each A/D
converter.
The converter and multiplexer in slots 10 and 11 contain
channels 0 through 23.
The converter in slot 17 contains channels 120
through 127. An attempt to access a nonexistent channel (for example,
channel 30 or channel 129) will be rejected by the driver.
The user should observe that the bistable drivers in slots 13 and 15
contain relative point numbers 0 through 15, and 16 through 29
although the modules are not physically adjacent.
In general, the
relationship between slot number, module type, bus address, and
relative address is as follows:
1.

A set of contiguous relative addresses is defined for each
module of a given type that is installed.
Each relative
address, when qualified by type,
uniquely identifies a
digital point or channel.

A set of slot numbers and bus addresses, possibly not
contiguous, is occupied by all modules of a given type.
Such
addresses may be assigned solely on the basis of hardware and
installation considerations.
Increasing relative addresses
correspond to increasing bus addresses.

Table 18-3 is an example of the
interrupt
points,
and point
configuration.

relationship
numbers for

among bus addresses,
a sample DSSll/DRSll

Table 18-3
Sample DSS/DRS Configuration
Bus Addresses

Module Type

Po in ts

Interrupt Point

160030-160036
160040-160046

DRSll
DRSll

0-47.
48.-95.

0
1

170010-170016
170
. 0 2 0 -17
~ 00 211,

DSSll

0-47.

DSS .L.L

18-7

l"\I""'

.....

INDUSTRIAL CONTROL SUBSYSTEMS
All addressing is by point number. Except for the interrupts, all
points are numbered sequentially by type (DSS or DRS), starting with
the first point on the lowest address assigned to a given module type.
Interrupt points are defined by means of a 16-bit mask word. Each bit
in the mask defines an interrupting module;
high-order
bits
correspond to increasing bus addresses.

18.2

LUN INFORMATION

A request for logical unit information returns
the
device-dependent data in words 2 through 5 of the buffer:

18.3

WD 02

WD 03

Undefined

WD 04

Undefined

WD 05

following

ASSEMBLY LANGUAGE INTERFACE

Table 18-4 summarizes standard and device-specific QIO functions
supported by the ICS/ICR driver. Only the five functions ind·icated by
a footnote are supported by the DSS/DRS driver.
Table 18-4
Summary of Industrial Control QIO Functions
Format

Function

QIO$C

IO.CCI, .•• ,<stadd,sizb,tevf>

CONNECT a buffer to
digital interrupts

QIO$C

IO.CTI, ••• ,<stadd,sizb,tevf,
arv>

CONNECT a buffer to
counter interrupts

QIO$C IO.CTY, ••• ,<stadd,sizb,tevf>

CONNECT a buffer to
terminal interrupts

QIO$C

IO. DC I I • • •

Disconnect a buffer from
di ital interrupts

QIO$C

IO. DTI I • • •

Disconnect a buffer from
counter interrupts

QIO$C

IO.DTY, ••.

Disconnect a buffer from
terminal interrupts

QIO$C

IO.FLN, .••

Set controller off line

QIO$C

IO.ITI, ••• ,<mn,ic>

INITIALIZE a counter

QIO$C

IO.LDI, ••• ,<tname, [ ,tevf],
pn,csm>l

LINK task to digital
interrupts

QIO$C

IO.LKE, .•. ,<tname,[,tevf]>

LINK task to error
interrupts
(continued on next page)

18-8

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-4
{Cont.)
Summary of Industrial Control QIO Functions

Format

Function

QIO$C

IO.LTI, ••• ,<tname,[,tevf]
en [ , a rv] >

LINK task to counter
interrupts

QIO$C

IO.LTY, .•• ,<tname,[,tevf]>

LINK task to remote
terminal interrupts

QIO$C

IO.MLO, ••• ,<opn,pp,dp>l

OPEN or close bistable

digital output points

QIO$C

IO.MSO, .•• ,<opn,dp>

PULSE momentary digital
output points

QIO$C

IO.NLK, ••• ,<tname>l

UNLINK a task from all
interrupts

QIO$C

I 0. ONL, ••.

Place ICS/ICR controller
online

QIO$C

IO.RAD, ••• ,<stadd>l

READ activating data

QIO$C

IO.RBC, ••• ,<stadd,size,
stcnta>

INITIATE multiple A/D
conversions

QIO$C

IO.SAO, ••• ,<chn,vout>

PERFORM analog output

QIO$C IO.UDI, •.• ,<tname>l

UNLINK a task from
digital interrupts

QIO$C

IO.UER, ••• ,<tname>

UNLINK a task from error
interrupts

QIO$C

IO.UTI, ••• ,<tname>

UNLINK a
task from
counter interrupts

QIO$C

IO.UTY, ••• ,<tname>

UNLINK a task from
terminal interrupts.

QIO$C

IO.WLB, ••• ,<stadd,sizb>

TRANSMIT data to the ICR
remote terminal

I
I

1. These functions are supported by the DSS/DRS driver.

arv
The starting address of a
buffer containing
initial or reset
counter values.
The buffer must be aligned on a word boundary.

chn
The D/A channel number.

en
The counter number.

18-9

INDUSTRIAL CONTROL SUBSYSTEMS
csm
The change-of-state mask.
dp
The binary data pattern.
ic
The initial count.
mn
The module numbere
opn
The first bistable (latching) digital output point number.
This
value must be on a module boundary (evenly divisible by 16).
pn
The point number (must be assigned on a module boundary).
pp
A 16-bit mask.
sizb
The data buffer size in bytes. For a circular buffer connected
to unsolicited interrupts, this value must be even and large
enough to include one entry plus the 2-word header.
size
The data and control buffer size in bytes.
even number that is greater than O.

This value must be an

The starting address of the
boundary) •

(must

stadd
data

buffer

word

(may

staddb
The starting address of the
aligned on a byte boundary).

terminal

18-10

output

buffer

INDUSTRIAL CONTROL SUBSYSTEMS
stcnta
The starting address of the control buffer {must be on a word
boundary);
each control buffer word must be constructed as
described in Table 18-5 (Section 18.3.2).
tevf
An event flag number in the range 0 to 96, {if
event
flag
SYSGEN option was selected),
group-global event flags are not supported.

the group-global
or 0 to 64 if

tname
A task name composed of 1 to 6 alphanumeric characters in a
2-word RADIX-50 format.
Two arguments, each containing three
characters, are required for this parameter.
For example, the
task name ICNAME is specified as:

If the task name is less than four characters,
must be specified as follows for task ABC:

null

argument

vout
A binary number between 0 and 1023.
an analog output.

that is to be

converted

The following sections contain a detailed description of
each
function.
In the discussion of QIO request parameters, the following
conventions apply.
All numbering is relative.
Module numbers start at 0 beginning with the first module of a given
type.
Increasing module numbers correspond to increasing physical bus
addresses.
Channel numbers start at O, with channel 0 as the first channel on the
first module of a given type.
Point numbers start at 0 with point 0 as the first point on the first
module of a given type.
Points within a module are numbered "from
right to left" in increasing order.
It should be remembered that there is no requirement for
ICS/ICR
modules of a given type to occupy contiguous slots; thus, for
examp~e,
digital points 15(10)
and 16(10)
need not reside
on
physically adjacent modules.
This restriction does apply to DSS/DRS
modules, however.

18-11

INDUSTRIAL CONTROL SUBSYSTEMS

It is assumed that the number of points or channels per module is a
constant for each generic type. Specifically, the following weights
apply:
1.

Each ICS/ICR Digital I/O Module contains 16 points.

Each DSS/DRS Digital I/O Module contains 48 points.

Each. Counter Module contains 1 channel.

Each D/A Module contains 4 channels.

Each A/D Converter contains 120 channels.

As stated above, an A/D converter is assigned a block of 120 channels.
The number of channels in use within the block depends on the number
of multiplexers installed. The driver will reject an attempt to
address a nonexistent channel.

18.3.1

General Error Status Returns

The system recognizes and handles two kinds of status conditions
they occur in I/O requests:

•

Directive conditions, which indicate
rejection of the QIO directive itself

•

I/O status conditions, which indicate the success or
of the I/O operation

Table 18-7 lists numerical values
language and FORTRAN interfaces.

returns

the

for

acceptance

both

failure
assembly

The following directive and I/O status returns apply uniformly to
requests.

18.3.1.1

when

all

Directive Conditions

rs.sue - Directive accepted.

The first six parameters of the QIO
directive were valid, and sufficient dynamic memory was
available to allocate an I/O packet.
The directive is
accepted.

IE.ADP - Invalid address. The I/O status block or the QIO DPB was
outside of the issuing task's address space or was not
aligned on a word boundary.
IE.IEF - Invalid event flag number.
IE.ILU - Invalid logical unit number. The
directive was invalid for the
there were only five logical unit
task, and the value specified for

18-12

lun specification in a QIO
issuing task. For example,
numbers associated with the
lun was greater than five.

INDUSTRIAL CONTROL SUBSYSTEMS
IE.NOD - Insufficient dynamic memory.
There was not enough dynamic
memory to allocate an I/O packet for the I/O request.
The
user can try again later by blocking the task with a WAITFOR
SIGNIFICANT EVENT directive.
Note that WAITFOR SIGNIFICANT
EVENT is the only effective way for the issuing task to block
its execution, since other directives that could be used for
this purpose themselves require dynamic memory for their
execution (for example, MARK TIME).
IE.SDP - Invalid DIC number or DPB size.
The directive identification
code (DIC) or the size of the directive parameter block (DPB)
was incorrect;
the legal range for a DIC is from 1 through
127, and all DIC values must be odd.
Each individual
directive requires a DPB of a certain size.
If the size is
not correct for
the particular directive,
this code is
returned.
IE.ULN - Unassigned LUN.
The logical unit number in the QIO directive
was not associated with a physical device unit.
The user may
recover from this error by issuing a valid Assign LUN
directive and then reissuing the rejected directive.

18.3.1.2

I/O Conditions

IE.ABO - Operation aborted.
The specified operation was canceled by
IO.KIL or the request timed out while the unit was off line.
IE.OFL - Controller off line.
The physical device unit associated
with the LUN specified in the QIO directive was not on line.
An ICS/ICR controller may be off line because a device check
during bootstrap load has indicated that the controller is
not in the configuration.
IE.DNR - Controller not ready.
been detected.

A nonrecoverable controller error

has

IE.IFC - Illegal function.
A function code was included
in an I/O
request that is illegal for the ICS/ICR.
The function may
also refer to an ICS/ICR module type or function that was not
specified during system generation.

18.3.2

A/D Input - Read Multiple A/D Channels

This function provides the capability of reading several A/D channels
at any permissible gain.
The driver is capable of initiating parallel
transfers when more than one A/D converter is installed in a file box;
however, only one
interrupt module request (remote terminal or A/D)
may be in progress at a given time.
QIO DPB format:
QIO$C IO.RBC, ••• ,<stadd,size,stcnta>

18-13

INDUSTRIAL CONTROL SUBSYSTEMS
stadd
The starting address of the
boundary).

data

buffer

(must

word

The data buffer size in bytes (must be even and greater than
the control buffer is the same size.

O);

size

stcnta
The starting address of the control buffer (must be on a word
boundary); each control buffer word must be constructed as shown
in Table 18-5.
Return Status:

rs.sue - Function successfully completed.
IE.BAD - Illegal channel or gain code specified.
IE.BYT - Data buffer is byte aligned. Alternatively, the
of the buffer is not an even number of bytes.
IE.DNR - Device not
occurred.

ready.

A/D

converter

Note that the second I/O status word contains
number of conversions successfully completed.

interrupt
a

count

length
time-out
of

the

One control word is paired with each data word.
That is, the data
appearing in a data array element is obtained using the gain and
channel number specified in the corresponding element of the control
array.
Control words specify the gain and channel in the format shown
in Table 18-5.
Upon receiving and validating the parameters within the I/O
the driver will initiate the following sampling procedure:

packet,

The control word is fetched and tested for validity (that is,
for legal gain and channel).
If an error is encountered or
no further control words remain, processing is terminated as
described in Step 4.

Assuming the A/D converter board is idle, the driver starts
the conversion, sets this resource busy, and returns to step
1.
If the converter is busy, the driver returns control to
the system after saving the data required to initiate the
conversion when the channel becomes idle.

On the occurrence of an A/D interrupt, the interrupt service
routine initiates the appropriate processing at the non
interrupt level that will either set the channel
idle or
initiate a previous request stored during step 2.
The
occurrence of the latter results in processing of additional
control words as described in step 1.

, n
, A
.LO-.L<2

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-5
A/D Conversion Control Word
Bits

Meaning

0-11

Channel Number range: 0-1919

12-15

Gain value for
this sample. The
binary value is
as follows:

Gain

-15

-14

-13

-12

0
0
0
0
0
0
0
0
1
1
1
1
1
1
1
1

0
0
0
0
1
1

0
0
1
1
0
0
1
1
0
0
1
1
0
0
1
1

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

1
0
0
0
0
1
1
1
1

1
2

illegal
illegal
10
20
illegal
illegal
50
100
illegal
illegal
200
1000
illegal
illegal

The converted value is returned as 12 bits, left-justified,
in a lo-bit word, with the low-order 4 bits set to 0.

A/D requests
conditions:

are

terminated

under

any

the

All control words have been processed.

A hardware error has occurred.

An error in a control word has been detected.

following

Regardless of the cause, the driver cannot complete request processing
until all pending A/D transfers have gone to completion.
Because of overlapped processing, multiple errors can occur
(for
example, a hardware error and an erroneous control word}. The driver
returns the status associated with the earliest transaction that
caused an error condition. Thus, at the user interface, the driver
appears to execute all conversions sequentially.

18.3.3

Analog Output

This function provides the capability
output channel to a specified voltage.

18-15

setting

single

analog

INDUSTRIAL CONTROL SUBSYSTEMS
The driver will allow continual monitoring for digital, counter, and
terminal inputs with the provision that, for each controller, only one
task per module type may receive such inputs.
Task activation is permitted for digital, terminal, and
error
interrupts. The processing related to hardware errors is discussed in
Section 18.5. Activation of tasks by digital, counter, and terminal
inputs is covered in Section 18.3.7.
The driver functions described in the following paragraphs allow a
task to continually receive interrupt data. To monitor such data, a
task must provide:
1.

A buffer that is filled by the driver and emptied by the task
in circular fashion

An event flag that will be set upon the
interrupt

The driver will connect a single task
interrupts from a specific module type.

per

occurrence

controller

each

receive

The buffer to be connected has the format shown below:
FORTRAN
Index

Contents

driver index

user index

word 0 of entry

word 1 of entry

The buffer consists of a 2-word header containing the driver and user
index, aas shown, followed by a data area that is subdivided into
fixed-length entries. Each entry consists of a word containing the
entry
existence
indicator
followed by one or more words of
device-dependent data. Such information usually consists of module
data, relative module number, and a code identifying a module type.
On the occurrence of an interrupt, the driver enters data in the
location currently indicated by the driver index. This index can be
considered as a FORTRAN index into the buffer.
That is, the first
location in the buffer is associated with the index 1. The beginning
of the data area is associated with the first entry, index 3. Entries
are made in a circular fashion starting at the beginning of the data
area, filling in order of increasing memory address, and wrapping
around to the beginning of the data area when there is insufficient
space for an entry at the end. Note that the size of the data area
must be an integer multiple of the entry size.
It is expected that the connected task will maintain the user index,
ensuring that it indicate where, in the buffer, the task is to process
interrupt data next.
When the task is activated by the driver, it should process data in
the buffer starting at the location indicated by its pointer, and
continuing in circular fashion until an existence indicator is
encountered that is 0.
18-18

INDUSTRIAL CONTROL SUBSYSTEMS
The existence indicator is set to +l when a buffer entry is made.
Except to record a hardware error, the contents of an entry are not
altered by the driver if the indicator is nonzero.
Hence, when a
requester has removed or processed the entry, he must clear the
existence indicator in order to free the buffer entry position.
If
the driver detects a nonzero indicator,
(that is, data input has
occurred in a burst sufficient to overrun the buffer), the data
is
discarded and a count of data overruns is incremented.
The count is
maintained in the entry existence indicator, which, as noted above, is
set to +l to indicate no overruns between entries, +2 to indicate a
hardware error entry, or a negative value recording the two's
complement of the number of times data has been discarded between
entries. The overrun count will never be allowed to wrap around to a
positive value.
In the event of a nonrecoverable controller error
(remote unit
power-fail or hard data error) all connected tasks are activated with
the following entry in the circular buffer:
WD 00

Hardware error indicator (+2)

WD nn
WD nn+l
WD nn+2

Contents of ICSR register
Physical unit number
Generic code indicator
set to 177770(8)

nn
The offset to module data word.
This entry is always placed
status.

the

buffer

regardless

overflow

The error flags are obtained from the controller ICSR word at the time
the error was detected (see Table 18-7).

18.3.6.1 Connect to Digital Interrupts - This
single task to receive digital interrupt data.

function

allows

QIO DPB format:
QIO IO.CCI, ••• ,<stadd,sizb,tevf>
stadd
The starting address of buffer to
aligned) •

connected

(must

even).

Minimum

word

sizb
The length of buffer in bytes (must
length is 14 bytes.
tevf
The trigger event flag number.

18-19

buffer

INDUSTRIAL CONTROL SUBSYSTEMS

Return Status:

rs.sue - Function successfully completed.

Second I/O status word
contains the number of words passed per interrupt in the
low byte, and the initial FORTRAN index in the high
byte.

IE.BYT - Buffer address is byte
number of bytes.

aligned

length

odd

IE.CON - Interrupt already connected to another task.
IE.IEF - Invalid event flag number.
IE.PRI - Task checkpointable and not fixed in memory.
IE.SPC - Interrupt circular buffer was not wholly within the
address space of the task. Alternatively, the buffer
was too small for a single data entry (seven words
minimum) •
Entry Format:
WD 00
WD 01
WD 02
WD 03
WD 04

Existence Indicator
Change of state indicator
Module data
Relative module number
Generic Code 1, 2, or 3, indicating a digital interrupt

The contents
previously.

the

existence

indicator

have

been

described

The change-of-state indicator records those bits for which a change of
state in the direction of interest has been detected. The direction
of the change may be from 0 to l (point closed (PCL)) or 1 to 0 (point
open (POP)) depending upon the PCL or POP jumper connections on the
digital interrupt module. The driver will assume that at least one of
these signals is always asserted.
The relative module number indicates the module on which the change of
state was recognized.
The module data word records data received at the time
was serviced.

the

interrupt

The generic code identifies the type of module that caused the
interrupt.
A digital interrupting module may have the value 1, 2, or
3 as selected by user-installed jumpers on the module.

18.3.~.2
Disconnect from Digital Interrupts - This function allows
task to terminate the processing of digital interrupt data.

QIO DPB format:
QIO$C IO.DCI, •••

18-20

INDUSTRIAL CONTROL SUBSYSTEMS
Return Status:

rs.sue - Function successfully completed.

Second I/O status word

is 0.
IE.CON - Task was not connected.

Second I/O status word is O.

18.3.5.3 Connect to Counter Module Interrupts - This function
a single task to receive counter interrupt data.

allows

QIO DPB format:

QIOSC IO.CTI, ••• ,<stadd,sizb,tevf,arv>
stadd
The starting address of circular buffer (must be word aligned).
sizb
The length of buff er in bytes (must
length is 12 bytes.

even) •

Minimum

buffer

tevf
The trigger event flag number.
arv
The starting address of table of initial counter values (must
word aligned).

Word 03 defines an array of initial counter values.
One entry is
required for each counter installed in a physical unit.
Entries are
paired with modules in logically ascending sequence.
The counter
is
set to the
initial value upon receipt of the connect function and
whenever an overflow interrupt occurs (that is, when the count reaches
0) •

Return Status:

rs.sue - Function successfully completed.

The second I/O status
word contains the number of words passed per interrupt
in the low byte, and the initial FORTRAN index in the
high byte.

IE.BYT - Buffer address is byte
number of bytes.

aligned

length

IE.CON - Interrupt already connected to another task.

18-21

odd

INDUSTRIAL CONTROL SUBSYSTEMS
IE.IEF - Invalid event flag number.
IE.PR! - Task checkpointable and not fixed in memory.
IE.SPC -

Interrupt circular buffer or table of initial values was
not wholly within the address space of the task.
Alternatively, the buffer was too small for a single
data entry (six words minimum).

Entry Format:
WO 00 - Existence indicator
WO 01 - Module data
WO 02 - Relative module number
WO 03 - Generic code (4, 5, or 6)

18.3.6.4 Set Counter Initial Value - This function allows a counter
initial value to be established.
A task need not be connected to
counter interrupts to perform this function.
QIO DPB format:
QIO$C IO.ITI, ••• ,<mn,ic>
mn
The relative module number.
ic
The new initial count.
Return Status:

rs.sue - New value submitted for output to the

controller.

The

second word of I/O status is set to O.
IE.MOD - Nonexistent module number specified.
Upon receipt of the request, the new initial value is immediately
queued
for output to the controller.
The counter is reinitialized
with this value on overflow if a
task is connected to counter
interrupts.

18.3.6.5 Disconnect from Counter Interrupts - This function allows
task to terminate counter interrupt processing.
QIO DPB

format~

18-22

INDUSTRIAL CONTROL SUBSYSTEMS
Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is set to O.
IE.CON - Task was not connected to timer interrupts.
After disconnect is complete, counters are not reset
value at the time of the interrupt.

the

initial

18.3.6.6 Connect to Terminal Interrupts - This function allows a task
to receive terminal inputs from the selected ICRll controller.
QIO DPB format:
QIO$C IO.CTY, ••• ,<stadd,sizb,tevf>
stadd
The address of the circular buffer

(must be word aligned).

sizb
The length of buffer (must be even) •
is 12 bytes.

The minimum

buffer

length

tevf
The trigger event flag number.
Return Status:

rs.sue - Function successfully completed.

The second I/O status
word contains the number of words passed per interrupt
in the low byte, and the initial FORTRAN index
in the
high byte.

IE.BYT - Buffer is byte aligned or length is
bytes

odd

number

IE.CON - Interrupt already connected to another task.
IE.IEF - Invalid event flag number.
IE.MOD - Nonexistent device.

Controller is ICSll.

IE.SPC - Interrupt circular buffer was not wholly within the
address space of the task.
Alternatively, the buffer
was too small for a single entry (six words minimum).
Entry Format:

WD 00

Existence indicator

WD 01 - High byte
WD 02

= O, low byte = terminal input character

Relative module number (normally 0)

WD 03 - Generic code indicator (normally 0)
18-23

INDUSTRIAL CONTROL SUBSYSTEMS
Note that words 2 and 3 are nonzero only when the entry
the result of a nonrecoverable controller error.

was

made

All remote terminal data is conveyed to the requesting task as
but with the parity bit removed.

input,

NOTE
Remote terminal input is not
the driver.

echoed

18.3.6.7 Disconnect from Terminal Input - This function allows a task
to discontinue the processing of terminal input.
QIO DPB format:
QIO$C IO.DTY, •••
Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is set to O.
IE.CON - Task was not connected to remote terminal interrupts.

18.3.7

Activating a Task by Unsolicited Interrupts

The functions described
capability of:

the

following

paragraphs

provide

Activating a task in response to unsolicited interrupts

Interrogating
activation

Removing a task from the activation list

the

driver

determine

the

reason

the

for

The QIO DPB parameters specify the task name,
an optional
trigger
event flag
to be set if the task is active, and device-dependent
parameters that identify the interrupt source.
A task
is linked to
interrupts (that is, made eligible for activation) provided that:
1.

The resource exists.

The task is installed.

No other task is linked to the resource.

If another task is linked to the resource, the driver will reject the
request with a status of resource-in-use (IE.RSU). A resource is
defined as a single interrupt point, remote terminal (Control-C input
only), or counter module.

18-24

INDUSTRIAL CONTROL SUBSYSTEMS
On the occurrence of the appropriate interrupt, the task is made
active if dormant; otherwise, a trigger event flag, if specified, is
set. The task may interrogate the driver to determine the conditions
that caused activation, and to signify interrupt recognition. The
function of the event flag is to allow such a task to recognize an
event that has occurred while the task was active. Recognition is
ensured prior to the completion of task execution by issuing the Exit
If system directive followed by the Clear Event Flag directive.
The linkage between a task and a specific interrupt is removed
issuing the appropriate unlink request with the QIO directive.

Only one task may be associated with each interrupt source (that is,
one task per digital interrupt point, terminal input, or counter
modulee
NOTE
The MCR command REMOVE automatically
unlinks a task from all interrupts.

18.3.7.1 Link a Task to Digital Interrupts - This function allows
task to be activated on the occurrence of digital interrupts.

QIO DPB format:
QIO$C IO.LDI, ••• ,<tname, ( ,tevf] ,pn,csm>
tname
A 1- to 6-character alphanumeric task name
format.

2-word,

Radix-50

tevf
The trigger event flag (0

none) •

pn
The point number (must be aligned on a module boundary).
csm
The change-of-state mask.
The change-of-state mask indicates those bits for which a change of
state in the direction specified by the PCL and POP jumpers causes the
task to be activated.
Only one task may be linked to a given
interrupt point. A 0 change-of-state mask is not permitted.

18-25

INDUSTRIAL CONTROL SUBSYSTEMS
Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is set to O.
IE.BAD - Change-of-state mask set to O.
IE.IEF - Invalid event flag number.
IE.MOD - Nonexistent module or point
boundary.
IE.NOD - Insufficient dynamic
control block.

not

memory

aligned

allocate

module

secondary

IE.NST - Task "tname" is not installed.
IE.RSU - One or more of the specified points is in use
tasks.

18.3.7.2
task to
module.

other

Link a Task to Counter Interrupts - This function allows a
be activated by means of an interrupt from a single counter

QIO DPB format:
QIO$C IO.LTI, ••. ,<tname,[,tevf] ,cn[,ic]>
tname
A 1- to 6-character alphanumeric task
format.

name

2-word

Radix-50

tevf
The trigger event flag

none) •

en
The relative module number.
ic
The counter value {optional).
The counter value if nonzero, is used to reinitialize the module in a
manner similar to that described for
the Set Counter function in
Section 18.3.6.4.
Initialization may be bypassed by setting this
parameter to 0.
Return Status:

rs.sue - Function successfully completed.
status is set to O.
IE.IEF - Invalid event flag number.

18-26

The second word of I/O

INDUSTRIAL CONTROL SUBSYSTEMS
IE.MOD - Nonexistent module specified.
IE.NOD - Insufficient dynamic
control block.

memory

allocate

secondary

IE.RSU - Counter is linked to another task.

18.3.7.3 Link a Task to Terminal Interrupts - This function allows a
task to be activated by means of an interrupt from a remote terminal.
The task will be activated only in response to the Control-C character
(octal 003).
QIO DPB format:
QIO$C IO.LTY, ••• ,<tname,[,tevf]>
tname
A 1- to 6-character alphanumeric task name
format.

2-word,

Radix-50

tevf
The trigger event flag (0

none).

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is O.
IE.IEF - Invalid event flag number.
IE.MOD - Nonexistent module (unit is ICSll controller).
IE.NOD - insufficient dynamic
control block.

storage

allocate

secondary

IE.NST - Task "tname" is not installed.
IE.RSU - Remote terminal is linked to another task.

18.3.7.4 Link a Task to Error Interrupts - This function allows
a
single task to be activated whenever a remote unit power-fail or
nonrecoverable serial line error is detected on any or all remote
units in a system.
Only one task within a system may be linked to
error interrupts. Once linked, the selected task may receive error
reports from any ICR controller.
QIO DPB format:
QIO$C IO.LKE, ••• ,<tname,[,tevf]>
tname
A 1- to 6-character alphanumeric task
format.

18-27

name

2-word

Radix-50

INDUSTRIAL CONTROL SUBSYSTEMS
tevf
The trigger event flag (0

none) •

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is 0.
IE.IEF - Invalid event flag number.
IE.IFC - No ICRll subsystems are installed.
IE.NOD - Insufficient dynamic
control block.

storage

allocate

secondary

IE.NST - Task "tname" is not installed.
IE.RSU - Another task is linked to error interrupts.

task

The address of 6-word buffer to receive activation data (must
wo rd a 1 i g n e d ) •

18.3.7.5 Read Activating Data - This function allows a
determine the conditions that caused it to be activated.

QIO DPB format:
QIO$C IO.RAD, ••• ,<stadd>
stadd

The buffer receives data in the following format:
WD 00

- Activation indicator

WD 01

- Physical unit number

WD 02

- Generic code

WD 03

- Relative module number

WD 04

- Hardware dependent data

WD 05

- Hardware dependent data

The activation indicator is similar in function to the existence
indicator used when reading circular buffer entries. The indicator is
set to +l on the occurrence of an interrupt to which the requesting
task is linked, and the appropriate data is stored. The indicator is
cleared when the data is solicited by the task.
If an interrupt
linked to the task occurs and the parameter is nonzero then the
previously stored data is not modified and the driver sets this
element with the two's complement of the number of linked interrupts
not recorded.
The physical unit number specifies the controller
interrupt.

i8-28

that

received

the

INDUSTRIAL CONTROL SUBSYSTEMS
The generic code is identical to that specified
entries, namely:
0

- Terminal {Control-C)

1,2,3

- Digital interrupt

4,5,6

- Counter interrupt

for

circular

buffer

generic

code

will

177770 - Fatal controller error
Hardware-dependent data is
consist of the following:

associated

with

and

Terminal:
WD 04 -

Terminal buffer contents (low byte)

WD 05 -

Undefined

Digital Interrupts:
WD 04 -

Module data

WD 05 -

Change-of-state indicator

Counter:
WD 04 -

Module data

WD 05 -

Undefined

Fatal Controller Error:
WD04

Contents of ICSR register (see Table 18-7)

WD05

Contents of ICAR register (see Table 18-8)

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is O.

IE.BYT - Buffer address is aligned on an odd byte boundary.
IE.NLK - Task "tname" was not linked to interrupts.
IE.SPC - Buffer not totally within the task's address space.

18.3.8

Unlink a Task from Interrupts

The functions described
capability of:

the

following

paragraphs

provide

the

Unlinking a task from all interrupts on a controller

Selectively unlinking a task from interrupts by module type

18-29

INDUSTRIAL CONTROL SUBSYSTEMS
18.3.8.1 Unlink a Task from All Interrupts - This function unlinks a
task from all interrupts on a given controller and from error
interrupts.
QIO DPB format:
QIO$C IO.NLK, ••• ,<tname>
tname
A 1- to 6-character alphanumeric task
format.

name

2-word

Radix-50

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is O.
IE.NLK - Task "tname" was not linked to interrupts.

18.3.8.2 Unlink a Task from all Digital Interrupts - This
function
provides the capability of unlinking a task from all digital interrupt
points on a controller.
QIO DPB format:
QIO$C IO.UDI, ••• ,<tname>
tname
a 1- to 6-character alphanumeric task
format.

name

2-word

Radix-50

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is O.

IE.NLK - Task "tname" was not linked to the
interrupt.

specified

class

IE.NST - Task not installed.
IE.MOD - Nonexistent module type specified.

18.3.8.3 Unlink a Task from Counter Interrupts - This
function
provides the capability of unlinking a task from all counter module
interrupts.
QIO DPB format:
QIO$C IO.UTI, ••• ,<tname>
tname
A 1- to 6-character alphanumeric task
format.
18-30

name

2-word

Radix-50

INDUSTRIAL CONTROL SUBSYSTEMS
Return Status:
rs.sue - Function successfully completed.
status is O.
IE.NLK - Task

The second word of I/O

tname" was not linked to the specified interrupts.

IE.NST - Task not installed.
IE.MOD - Nonexistent module type specified.

18.3.8.4 Unlink a Task from Terminal Interrupts - This
function
provides the capability of unlinking a task from terminal interrupts.
QIO DPB format:
QIO$e IO.UTY, ••• ,<tname>
tname
A 1- to 6-character alphanumeric task
format.

name

2-word

Radix-50

Return Status:
rs.sue - Function successfully completed.
status is o.

The second word of I/O

IE.NLK - Task "tname" was not linked to the specified interrupts.
IE.NST - Task not installed.
IE.MOD - Nonexistent module specified
res11 controller) •

(that

is,

device

18.3.8.5 Unlink a Task from Error Interrupts - This function provides
the capability of unlinking a task from all error interrupts.
QIO DPB format:
QIO$e IO.UER, ••• ,<tname>
tname
A 1- to 6-character alphanumeric task
format.

name

2-word

Radix-50

Return Status:
rs.sue - Function successfully completed.
status is O.

The second word of I/O

IE.IFe - No reRll controllers exist in the system.
IE.NLK - Task

tname 0 was not linked to error interrupts.

IE.NST - Task not installed.

18-31

INDUSTRIAL CONTROL SUBSYSTEMS
18.3.9

Terminal Output

This function allows a task to perform output to the terminal device.
Characters are output exactly as they appear in the buffer. The
carriage control parameter is not recognized.
It should be noted that
only one interrupt module request per controller (terminal or A/D) may
be in progress at a given time. Thus, the driver will not initiate an
A/D operation on a given controller, until any terminal output in
progress for that controller has been completed.
QIO DPB format:
QIO$C IO.WLB, ••• ,<staddb,sizb>
staddb
The buffer address {may be odd).
sizb
The byte count (may be odd) •
Return Status:

rs.sue - Function successfully completed.

Second word
status contains the number of bytes output.

IE.MOD - Nonexistent hardware function.
an ICSll controller.

18.3.10

Request was

I/O

issued

for

Maintenance Functions

The functions described below allow a privileged task to enable and
disable error reporting while troubleshooting or maintenance on a
remote unit is in progress.

18.3.10.1 Disable Hardware Error Reporting - This function allows a
privileged task to disable error reporting and error interrupts, and
restrict access to the controller while remote unit troubleshooting or
module calibration is in progress (see Section 18.5.1). Upon receipt
and validation of the request, error interrupts are disabled and
subsequent controller time-outs are ignored. The occurrence of device
time-out while A/D conversion or remote terminal input is in progress
results in termination of the request with the error code IE.ABO.
When error reporting is disabled in this manner, access to the
controller for input or output to I/O modules is restricted to
privileged tasks. All other requests not requiring the transmission
of data to or from the device are permitted for all tasks. Such
requests are as follows:
1.

Disconnect
interrupts

from

digital,

Unlink from interrupts

Read activating data

18-32

counter,

remote

terminal

INDUSTRIAL CONTROL SUBSYSTEMS
4.

Link to digital, remote terminal, or error interrupts

Connect a buffer to digital or remote terminal interrupts

All other requests not issued by a privileged task are
the error code IE.DNR.

rejected

with

QIO DPB format:
QIO$C IO.FLN, •••
Return Status:

rs.sue - Function successfully completed
IE.FLN - Unit already off line
IE.PR! - Task not privileged

18.3.10.2 Enable Hardware Error Reporting - This function allows a
privileged task to enable error reporting and device error interrupts.
Upon receipt and validation of the function, all device error
interrupts are enabled and the unit is marked on line. These actions
are performed regardless of the current state of the unit.
QIO DPB
format:
QIO$C IO.ONL, •••
Return Status:

rs.sue - Function successfully completed
IE.PR! - Task not privileged

18.3.11

Special Functions

18.3.11.1 I/O Rundown - An I/O rundown request from the Executive
will automatically cause the task to be disconnected from all
interrupts. The rundown operation is not finished until any A/D input
in progress for the task has been completed.

18.3.11.2 Kill I/O - The kill I/O function allows a task to initiate
I/O rundown processing for itself on any device. Request processing
is identical to that described for I/O rundown.
QIO DPB format:
QIO$C IO.KIL, •••
Return Status:

rs.sue - Function successfully completed

18-33

INDUSTRIAL CONTROL SUBSYSTEMS
18.4

FORTRAN INTERFACE

Table 18-6 lists the FORTRAN interface subroutines supported for the
ICS/ICR subsystem.
(D)
indicates a direct access call. The six
subroutines supported by the DSS/DRS driver are indicated by a
footnote.
Unless specifically noted, all subroutines are reentrant (but not
necessarily position-independent) and may be placed in an absolute
resident library.
Table 18-6
FORTRAN Interface
Function

Subroutine
AIRD/AIRDW

Input analog data from multiple channels in
sequence

AISQ/AISQW

Read a series of sequential analog
at random gain

AO/AOW

Perform analog output on several channels

ASICLN/
ASUDLN

Assign a LUN to an ICS/ICR controller

ASISLNl

Assign a LUN to a DSS/DRS controller

CTDI

Connect a circular
interrupt data

buff er

receive

digital

CTTI

Connect a circular
interrupt data

buffer

receive

counter

CTTY

Connect a circular buffer to receive
terminal data

DFDI

Disconnect a buffer from digital interrupts

DFTI

Disconnect a buffer from counter interrupts

DFTY

Disconnect a buffer from remote terminal interrupts

DI/Diwl

Read several 16-point digital sense fields (D)

DOL/DOLWl

Latch or unlatch several 16-point
fields

bistable

output

DOM/DOMW

Pulse multiple 16-point
fields

digital

output

momentary

input

random
channels

ICRll

remote

Link a task to unsolicited interrupts
OF LIN

Suppress error reporting.
status

ON LIN

Enable
status

RC I PT

Read a single digital interrupt point (D)

error

reporting.

Place unit in not

ready

Return

ready

unit

(continued on next page)
18-34

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-6 (Cont.)
FORTRAN Interface
Function

Subroutine

Read interrupt activation data
RDDI

Read the digital interrupt circular buffer

RDTI

Read the counter interrupt circular buffer

RDCS

Read digital interrupt circular buffer;
return
data on only those points for which a change of
state has been recognized

RDWD

Read digital interrupt circular buffer;
full data word

RSTI

Read a single counter module (D)

RTO/RTOW

Perform output to a remote ICRll terminal

UNLNKl

Unlink a task from unsolicited interrupts

return

1. These subroutines are supported by the DSS/DRS driver.

18.4.1

Synchronous and Asynchronous Process Control I/O

The Instrument Society of America (ISA) standard provides
for
synchronous and asynchronous I/O.
Synchronous I/O is indicated by
appending a W to the name of the subroutine (for example, AO/AOW).
Except for analog input and terminal output, all QIOs issued by the
process control subroutines are serviced immediately by the driver and
are complete upon return to the issuing task. In such cases, there is
no functional difference between the synchronous and asynchronous
forms;
however, both forms of the name are recognized. In the case
of A/D input and terminal output, the subroutines are functionally
distinct.
If the asynchronous form is used, execution continues and
the calling program must periodically test the status word for
completion.

18.4.2

Return Status Reporting

The I/O status parameter is a 2-word integer array. The first element
of the array receives the status of the FORTRAN call in accordance
with ISA convention.
This array serves two purposes:
1.

It is the 2-word I/O status block to which the driver returns
an I/O status code on completion of an I/O request.

The first word of the status block receives a status code
from the FORTRAN interface subroutine in ISA-compatible
format, with the exception of the I/O pending condition,
which is indicated by a status of O. The ISA standard code
for this condition is +2.

18-35

INDUSTRIAL CONTROL SUBSYSTEMS

For asynchronous analog input and terminal output, status is set by
means of an asynchronous trap; therefore, the trap mechanism must be
enabled while these functions are in progress.
For compatibility, the 2-word status block is also required for status
returned by the direct access calls. Errors of this type that may be
returned are:
Word 1

Number of points requested is O.

Word 1

+321

Invalid ICS/ICR module.

The status code must be interpreted in the context of the function
requested; however, the following general conditions will apply:
Meaning

Contents of Status Word 1
0

Operation pending, I/O in progress

Successful completion

Error in a calling argument has been
netected by the interface subroutine

3<Word 1<300.

QIO directive rejected.
code = -(WORD 1 - 3)

Word 1 > 300

Request rejected by driver.
error code = -(WORD 1 - 300)

Actual error
Actual

Table 18-7 lists all possible status values:
the FORTRAN value,
assembly language mnemonic, actual value, and related definition.
Table 18-7
Return Status Summary

FORTRAN
Interface
Value

Assembly
Language
Value

Assembly
Language
Mnemonic

IS. PND

Operation pending

rs.sue

Successful completion

none

Error detected in
calling sequence

-1

IE. UPN

Insufficient dynamic storage
to allocate I/O packet

-5

IE. ULN

Unassigned LUN

-6

IE.LNL

LUN usage interlocked

IE IL u

I n val i d LUN

IE. IEF

Invalid event flag number

+ 99
+100

- 96
-97

Definition

FORTRAN

(continued on next page)

18-3fi

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-7
(Cont.)
Return Status Summary
FORTRAN
Interface
Value

Assembly
Language
Value

Assembly
Language
Mnemonic

+101

-98

IE.ADP

Part of DPB out
addressing space

+102

-99

IE. SDP

Invalid DIC or DPB size

+301

-1

IE.BAD

Bad parameters

+302

-2

IE.IFC

Invalid I/O function code

+303

-3

IE.DNR

Device not ready

+306

-6

IE. SPC

Illegal buffer

+315

-15

IE.ABO

Request aborted

+316

-16

IE. PRI

Privilege violation

+317

-17

IE.RSV

Resource in use

+319

-19

IE.BYT

Buffer address or
odd

+321

-21

IE.MOD

Illegal module number

+322

-22

IE.CON

Another
task
already
connected to interrupts

+323

-23

IE.NOD

Insufficient dynamic memory
to allocate secondary control
block

+379

-79

IE.NLK

Task not linked to interrupts

+380

-80

IE.FLN

ICRll already off line

+381

-81

IE.NST

Task is not installed

+397

-97

IE. IEF

Invalid event flag number

18.4.3

Definition

user's

length

Optional Arguments

The calling sequences discussed
in subsequent sections frequently
contain optional arguments.
These arguments are enclosed in square
brackets within the calling sequence description.
A
statement
containing such arguments may be written with these parameters deleted
by truncating the argument list if the optional parameters are at the
end of the calling sequence, or by replacing them with commas if they
are embedded elsewhere in the list.
Consider the routine XYZ below
having two optional arguments:
CALL XYZ ( ibuf [, ilen]

[, i val])

If the argument ival is to be omitted, the calling sequence would be:
CALL XYZ(IBUF,ILEN)
18-37

INDUSTRIAL CONTROL SUBSYSTEMS
When an optional argument in the middle of the list is to be omitted,
it is replaced with a comma. Consider the routine XYZ, above. The
following statement is used to omit the parameter ilen:
CALL XYZ(IBUF,,IVAL)
NOTE
In some subroutines, lun -- the logical
unit number -- is indicated to be an
optional argument. It is optional only
if one of the Assign LUN subroutines has
been called (ASICLN, ASUDLN, ASISLN).
Otherwise,
the
lun
argument
is
mandatory.

18.4.4

Assigning Default Logical and Physical Units for Input and
Output - ASICLN/ASUDLN (ICS/ICR) and ASISLN (DSS/DRS)
The following subroutines must be called to assign and record a
default LUN and physical unit if either parameter is to be unspecified
in subsequent FORTRAN calls for which these parameters are optional.

Calling Sequence:
CALL ASICLN([lun] [,idsw] [,iunt])
CALL ASUDLN([lun] [,idsw] [,iunt])
CALL ASISLN(lun[,idsw] [,iunt])
Before a task can issue the call to ASUDLN, the ASN command must be
issued through MCR to assign logical device UDnn to the appropriate
physical ICS/ICR unit.
Argument Description:
lun

An integer variable whose value is the number of the LUN
to be assigned to the physical unit specified by iunt or
unit O. If unspecified, no LUN is assigned.
The lun
argument is mandatory for ASISLN (used for DRSll only) •

idsw

An optional integer variable to receive
the assign lun directive.

iunt

An optional integer variable that specifies the unit
number to be assigned. Assumed to be 0 if omitted.

the

result

Return Status:
The following values are returned to idsw:
+l

- Assignment or function successfully completed.

-5

- LUN usage is interlocked because LUN is assigned to a
device that is attached to another device, or a file is
currently open on the LUN.

-96

- Invalid LUN.

The call to ASUDLN assigns a LUN to logical device UD:
and is
provided for compatibility with existing UDCll software. The call to
ASICLN assigns a LUN to device IC:. The call to ASISLN assigns a LUN
to device IS:.
18-38

INDUSTRIAL CONTROL SUBSYSTEMS
Upon successful issuance of the Assign LUN directive,
the subroutine
executes a Get LUN Information directive to obtain the actual unit
numbers to be saved.
It is therefore possible to alter the default
physical unit referenced in a direct access call, by means of the ASN
MCR function, provided that such logical assignments are done before
the task is made active.
Examples:
le

Assign LUN 5 to ICR unit 3.

10
2.

CALL ASICLN (5,IERR,3)
IF(IERR) 20,10,10
--------------

Assign LUN 1 to logical device UD:, unit 0
a.

The following MCR command is issued to create logical
device UDO:, and assign all references to physical device
ICl:.
>ASN ICl:

= UD:

The FORTRAN call
CALL ASUDLN (1)
assigns logical device UDO:
to LUN 1.
Because of the
previous ASN command, the Executive will assign this LUN
to physical device ICl: and return a value of 1 for the
unit number in response to the GET LUN Information
directive.
This value will be
stored
and
later
referenced
whenever
the
physical
unit number is
unspecified in any of the FORTRAN calls that reference
the I/O page directly.

Assign LUN 6 to logical device IS:, unit 2.
CALL ASISLN(6,,2)

18.4.5

Analog Input

The following routines provide the capability of performing A/D input:
AIRD/AIRDW -

ISA Standard call to read
random order.
This call
control variables containing
in the format shown in Table

multiple channels in
requires one or more
A/D channel and gain
18-5 (Section 18.3.2).

AISQ/AISQW -

ISA Standard call
sequential order.

multiple

read

channels

18.4.5.1 AIRD/AIRDW: Analog Input - Specified Channel Sequence - The
ISA standard call provides the capability of reading multiple A/D
channels in a specified sequence.

18-39

INDUSTRIAL CONTROL SUBSYSTEMS
Calling Sequence:
CALL AIRD(inm,icont,idata[,isb] ,lun)
or
CALL AIRDW(inm,icont, ••• etc.)
Argument Descriptions:
inm

Integer variable specifying the number of
be read.

icont

An integer array of size inm containing control data in
the format shown in Table 18-5 (Section 18.3.2).

id at

An integer array of dimension inm to receive the
converted values. Each element in the array is paired
with a control element in icont that defines the
channel and gain.

isb

An optional 2-word integer array to receive the results
of the call as follows:

lun

channels

Conversion successfully completed.
The
second word contains the number of channels
converted.

Number of channels requested was O.

Insufficient dynamic
I/O packet.

LUN was not assigned.

+99

Invalid LUN.

+301

At least one invalid control word was
specified.
The second I/O status word
contains
the
number
of
channels
successfully converted.

+303

Device not ready. Interrupt response was
not received from an A/D channel within one
second after initiation. The second word
of
I/O status contains the number of
channels successfully converted.

+306

Control or data buffer not wholly
the user's addressing space.

+319

Control or data buffer is byte aligned.

storage

allocate

within

An integer variable specifying the ICS/ICR logical unit
number. This parameter is required.

Example:
The following example illustrates how A/D throughput can be increased
when several IAD-IA A/D Converters are in a system.
This is
accomplished by means of interleaved samples that initiate parallel
conversions on each module.
Samples are to be obtained from 12
channels on 3 IAD-IA A/D converter modules at a gain of 1.

INDUSTRIAL CONTROL SUBSYSTEMS

c
C PROGRAM TO SAMPLE 12 A/D CHANNELS
C IN RANDOM SEQUENCE FOR MAXIMUM
C THRUPUT.

c
C CHANNELS TO BE SAMPLED:

c
c

c
c
c

c
c
c
C

c
c
c

-A/D MODULE 0

3
120
121
122
123
240
241
242
243

-A/D MODULE 1

-A/D MODULE 2

C INTERLEAVED SEQUENCE FOR MAXIMUM
C THRUPUT.

c
c
c
c
c
c
c
c
c
c
c
c
c
c

120
240
1

121
241
2
122
242
3
123
243

C THE FORTRAN CONVENTION FOR ARRAY
C STORAGE CAN BE USED TO REPRESENT
C THE ABOVE SEQUENCE IN AN N X I INTEGER
C CONTROL ARRAY. WHERE:

c
C
C

N = NUMBER OF MODULES TO BE SAMPLED
I = NUMBER OF SAMPLES PER/MODULE

C ALLOCATE STORAGE FOR CONTROL ARRAY

c
c

DIMENSION !CONT (3,4)

C INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 0

c
c

DATA ICONT(l,l) ,ICONT(l,2) ,ICONT(l,3) ,ICONT(l,4)/0,1,2,3/

C INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 1

c
DATA ICONT(2,l) ,ICONT(2,2) ,ICONT(2,3) ,ICONT(2,4)/120,121,122,123/

c
C INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 2

DATA ICONT(3,l) ,ICONT(3,2) ,ICONT(3,3) ,ICONT(3,4)/240,241,242,243/

c
C ALLOCATE STORAGE FOR DATA ARRAY
C IN SIMILAR FASHION TO FACILITATE
C CHANNEL REFERENCES

18-41

INDUSTRIAL CONTROL SUBSYSTEMS

c
c
C

DIMENSION !DATA {3,4)
BEGIN EXECUTABLE STATEMENTS

c
c
C INITIATE A/D SYNCHRONOUS CONVERSION ON LUN 3

CALL AIRDW{l2,ICONT,IDATA,,3)

18.4.5.2 AISQ/AISQW: Analog Input - Sequential Channel Sequence - The
ISA standard call described below provides the capability of sampling
multiple A/D channels in sequential order. Channels are sampled in
increments of one, beginning with the channel specified in icont(l).
Calling Sequence:
CALL AISQ(inm,icont,idata [,isb] ,lun)
or
CALL AISQW(inm,icont ••• etc.)
Argument Descriptions:
inm

Integer variable specifying the number of
be read.

elements

icont

An integer array of size inm containing initial channel
in the first element only, and gain in the format shown
in Table 18-5 in the remaining elements.

idat

An integer array of size inm to receive the converted
values.
Each element is paired with the corresponding
control element in icont that defines
the
gain
parameter.
Channels are sampled sequentially starting with
first channel specified in element 1 of icont.

isb

the

An optional 2-word integer array to receive the results
of the call as follows:
+l

Conversion successfully completed.
The
second word contains the number of channels
converted.

Number of channels requested was O.

Insufficient dynamic
I/O packet.

LUN was not assigned.

+99

Invalid LUN.

storage

allocate

INDUSTRIAL CONTROL SUBSYSTEMS

lun

+301

At least one invalid control word was
specified.
The second I/O status word
of
channels
contains
the
number
successfully converted.

+303

Device not ready.
Interrupt response was
not received from an A/D channel within one
second after initiation. The second word
of
I/O status contains the number of
channels successfully converted.

+306

Control or data buffer is not wholly within
the user's addressing space.

+319

Control or data buffer is byte aligned.

An integer variable containing the logical unit number.
This parameter is required.

Example:
The following example illustrates the procedure for
sequential
sampling.
Five channels are converted at gains of 1, 2, 20, 50, and
1000, starting at channel 3.

c
C ALLOCATE SPACE FOR STATUS ARRAY

DIMENSION ISB (2)

C ALLOCATE SPACE FOR CONTROL ARRAY
C AND ESTABLISH INITIAL VALUES

c
c

DIMENSION ICONT(5)
DATA ICONT(l),ICONT(2),ICONT(3)/0000003,0010000,0050000/
DATA ICONT(4) ,ICONT(5)/0100000,0150000/

C ALLOCATE SPACE FOR DATA ARRAY

c
DIMENSION IDAT (5)

c
C INITIATE SEQUENTIAL, ASYNCHRONOUS CONVERSION
C VIA LUN 1

CALL AISQ(5,ICONT,IDAT,ISB,l)
IF(ISB(l) .NE.O) GO TO 20
(continue processing)

c
C TEST CONVERSION STATUS

c
20

GO TO 10
(test for errors or process converted data)

END

18-43

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.~

AO/AOW: Analog Output - Multichannel

This ISA standard routine is called to output
D/A channels.

voltage

from

multiple

Calling Sequence:
CALL AO(inm,icnt,idat[,isb] [,lun])
or
CALL AOW{inm,icnt ••• and so forth)
Argument Descriptions:
inm

Integer variable containing the number of
be output.

channels

icnt

Integer array containing the channel numbers to receive
output.

idat

Integer array containing the output voltage setting
a value between 0 and 1023 where:

0 = 0 volts de and
1023 = +9.99 volts (full scale).
isb

lun

Optional 2-word integer array to receive status.
of the following values is returned
in isb(l).
second element is always 0.

One
The

Function successfully completed.

No channels requested.

Insufficient dynamic storage to allocate an
I/O packet.

LUN was not assigned.

+99

Invalid LUN.

+303

Controller not ready.

+321

Nonexistent channel specified.

Integer variab~e containing the logical unit number.

Example:
Output the variable voltages .contained
channels 2 and 3, respectively.

1 Q_ .11 II

..LU-"':i:""i:

IV(l)

and

IV(2)

D/A

INDUSTRIAL CONTROL SUBSYSTEMS

c
C ALLOCATE DATA ARRAY

c
DIMENSION IV(2)

c
C ALLOCATE CONTROL ARRAY

c
DIMENSION ICNT(2)

c
C ALLOCATE STATUS ARRAY

c
DIMENSION ISB(2)

C INITIALIZE CONTROL ARRAY

c
DATA ICNT(l) ,ICNT(2)/2,3/

c
C PERFORM A/D OUTPUT VIA LUN 3

c
CALL AOW(2,ICNT,IV,ISB,3)
IF (ISB(l) .GE.3) go to error processor

18.4.7

DOL/DOLW: Digital Output - Bistable Multiple Fields

The following ISA standard call provides the capability of latching or
unlatching multiple 16-point bistable digital output fields.
Calling Sequence:
CALL DOL(inm,icnt,idat,imsk[,isb] [,lun])
or
CALL DOLW(inm,icnt •.• and so forth)
Argument Descriptions:
inm

Integer variable specifying the number of fields to
latched or unlatched.

icnt

Integer array containing the initial point within
field.

each

idat

Integer array containing binary data
that defines
points within the
field
to be latched. or unlatched.
The state of each bit is interpreted as follows:
1

Latch point

Unlatch point

18-45

INDUSTRIAL CONTROL SUBSYSTEMS
imsk

Integer array containing binary data that defines
points within the field for which a change of state is
permitted.
A bit set to 1 defines a point that may assume the
state defined by the corresponding bit in idat.
A 0
bit specifies a point for which no change of state is
permitted.

isb

lun

Optional 2-word integer array to receive the results of
the call.
Status is returned in isb(l) as shown below.
isb(2) is always O.
+l

Function successfully completed.

No points specified.

Insufficient dynamic storage to allocate an
I/O packet.

LUN was not assigned.

+99

Invalid LUN.

+303

Controller not ready.

+321

Nonexistent point number specified.
One or
more points within the field do not exist.

Integer specifying the Logical Unit Number.

Example:
Reset points 0,1,20 and 21
DIMENSION ICNT(2) ,IDAT(2) ,IMSK(2)

c
C INITIALIZE THE CONTROL ARRAY

DATA ICNT(l) ,ICNT(2)/0,20/

C INITIALIZE MASK ARRAY TO EFFECT A
C CHANGE-OF-STATE ONLY ON THE SPECIFIED
C POINTS.

DATA IMSK{l) ,IMSK(2)/0000003,0000003/

c
C RESET THE SPECIFIED POINTS.
C TO LUN 3.

ICR IS ASSIGNED

CALL DOLW(2,ICNT,IDAT,IMSK,,3)

18-46

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.8

Digital Input

Both of the following subroutines perform their functions through
direct access to the ICS/ICR hardware registers. Therefore, the
physical unit number replaces LUN in the calling sequences described
below. Note that any need for conversion of BCD encoded digital input
into binary can be accomplished through the FORTRAN function
IBIN=KBCD2B (IBCD).
Binary data can be converted to BCD through the FORTRAN function.
IBCD=KB2BCD (IBIN).
The maximum input value for conversion is 9999.
NOTE
When the physical
unit
number
is
explicitly
included
in the calling
sequence, it cannot be reassigned by the
MCR command ASN.

18.4.8.l DI/DIW: Digital Input - Digital Sense Multiple Fields - This
ISA standard subroutine provides the capability of reading multiple
16-point digital sense fields.
Calling Sequence:
CALL DI(inm,icnt,idat[,isb] [,iun])
or
CALL DIW(inm,icnt ••• and so forth)
Argument Descriptions:
inm

Integer variable specifying the number of fields to
read.

icnt

Integer array containing the initial
each field.

idat

Integer array to receive the input data.

isb

Optional, 2-word integer array to receive the results
of the call.
The status is returned in isb (1) as
follows:

point

number

Function succesfully completed.

No points requested.

+321

Nonexistent point requested. One or more
points within the 16-bit field does not
exist~

iun

Optional integer variable specifying the physical
number.

18-47

unit

INDUSTRIAL CONTROL SUBSYSTEMS
Example:
Read two contact sense fields starting at points 3 and 27 on
unit IC2:.

physical

DIMENSION ICNT(2), IDAT(2) ,ISB(2)
DATA
ICNT(l) ,ICNT(2)/3,27/
CALL DI (2,ICNT,IDAT,ISB,2)
IF (ISB(l) .GE.3) go to error procedure

18.4.8.2 RCIPT:
Digital Input - Digital Interrupt Single-Point - The
following subroutine returns the state of a single digital interrupt
point as a logical value.
Calling Sequence:
CALL RCIPT (ipt,isb[,iun])
Argument Descriptions:
ipt

Integer variable defining the point to be read.

isb

a 2-word integer array to receive status
follows.
Status is returned to isb(l).
+l

+321
iun

and

data

Function successfully completed.
Data
is
returned
to
isb(2)
as a
logical value,
where:
• 'T'RUE.

(-1)

Point closed •

• FALSE.

(0)

Point open •

Nonexistent point specified.

Optional integer variable defining
number.

the

Example:
Read the state of contact interrupt point 3 on unit O.
DIMENSION ISB (2)

CALL RCIPT (3,ISB,O)
IF (ISB(2) .EQ •• FALSE.) go to point open routine.

, Q_ 110

..LU---:tU

physical

unit

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.9

DOM/DOMW: Digital Output Momentary - Multiple Fields

This ISA standard call allows multiple 16-bit fields to be pulsed.
Calling Sequence:
CALL DOM (inm,icnt,idat[,idx] [,isb] [,lun])
or
CALL DOMW (inm,icnt •.. and so forth)
Argument Descriptions:
inm

Integer variable specifying the
pulsed.

icnt

Integer array containing
field.

idat

Integer array defining the points to be pulsed. A bit
is set corresponding to each point that is to be
triggered.

idx

Optional
dummy
integer
variable
retained
compatibility with the standard form of the call.

isb

Optional 2-word integer array to receive the results of
the call as follows in isb(l), isb(2) is set to 0.

lun

the

nu~ber

initial

of fields to
point

be
each

for

Number of fields to be output is O.

Insufficient dynamic storage to allocate on
I/O packet.

LUN not assigned.

+99

Invalid LUN.

+303

Controller not ready

+321

Nonexistent point specified. One or
points within a field do not exist.

Integer variable defining the logical unit number.

Example:
Pulse momentary digital output fields defined by points 20, 37, and
on LUN 1.
DIMENSION ICONT(3) ,IDAT(3)
DATA ICONT(l) ,ICONT(2) ,ICONT(3)/20,37,0/
CALL DOM(3,ICONT,IDAT,,l)

18-49

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.10

RTO/RTOW: Remote Terminal Output

The following function provides the capability of transmitting a
character string to a
remote ICRll terminal.
Both synchronous and
asynchronous forms are supported.
Calling Sequence:
CALL RTO (ibc,idat[,isb] [,lun])
or
CALL RTOW (ibc,idat •••• etc.)
Argument Descriptions:
ibc

Integer variable specifying
output.

idat

Bvte arrav
(LOGICAL
string to be output.

isb

Optional, 2-word integer array to receive the results
of the call in isb(l) as follows.
isb(2) is set to the
number of bytes actually transferred to the device.

lun

the

number

bytes

containing

the

character

Operation pending.

Function successfully completed.

No bytes to be transmitted.

Insufficient dynamic
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+303

Device not ready.
Terminal failed
to
respond within 1 second after character was
transmitted.

+306

Part or all of buffer is out of the issuing
task's addressing space.

+321

Nonexistent module.

storage

allocate

Device is ICSll.

Integer variable defining the logical unit number.

Example:
Output a character string
assigned to LUN 3.

remote

terminal

CALL RTOW(32,'APPLY +5 VOLTS TO A/D CHANNEL 10' ,,3)

18=50

the

ICR

unit

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.11

Unsolicited Interrupt Data - Continual Monitoring

Subroutines are provided that permit a FORTRAN program to continually
monitor unsolicited interrupt data supplied to a user circular buffer,
as described in Section 18.3.6. Such routines allow the program to
connect a buffer for input, disconnect the buffer upon completion, and
read and return the buffer contents in a format suitable for FORTRAN
processing.
The calls summarized below perform these functions for
interrupting digital input modules, counters, and remote terminal
inputs:
Interrupting Digital Inputs
CTDI

Connect a buffer to receive digital interrupts

RDDI

Read the state of a single interrupting point

RDCS

Read the state of a single interrupting point for which
a change of state has been detected

RDWD

Read 16 bits of interrupt data from the circular buffer

DFDI

D-i sconnect a buff er from digital interrupts

Counter Modules
CTTI

Connect a buffer to receive counter interrupts

RDTI

Read the counter circular buffer

DFTI

Disconnect a buffer from counter interrupts

Remote Terminal Input
CTTY

Connect a buffer to receive remote terminal inputs

RDTY

Read remote terminal data from the circular buffer

DFTY

Disconnect a buffer from remote terminal interrupts

CTDI: Connect a Buffer for Receiving Digital Interrupt Data
- The following routine allows a task to provide a circular buffer
that will receive digital interrupt data, and to define an event flag
that will be set upon the occurrence of each interrupt.
18.4.11.1

Calling Sequence:
CALL CTDI (ibuf,isz,iev[,isb] [,lun])
Argument Descriptions:
ibuf

An integer array making up the circular buffer that
to receive interrupt data.

isz

Integer variable specifying the length of the
buffer in words.

18-51

circular

INDUSTRIAL CONTROL SUBSYSTEMS

iev

Integer variable specifying the event flag that is to
be set whenever the driver receives an interrupt from a
digital input module.

isb

Optional, 2-word integer array to receive the results
of the call.
The status values specified below are
returned to isb(l).
+l

Function successfully completed.
isb(2)
receives the number of words passed per
interrupt in the low byte.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned

+99

Inv al id

+30h

LUN.

Part of buffer is out of the user's address
space or buffer is too small to accommodate

a single entry.

lun

+316

Privilege
violation - task
is
pointable and not fixed in memory.

check-

+319

Buffer address or length is an
of bytes.

number

+322

Another task
interrupts.

+397

Invalid event flag specified.

already

odd

connected

Integer variable specifying the logical unit number.

The space allocated for the circular buffer must be large enough to
accommodate at least one 5-word entry plus an additional 10 words of
storage that are required by the subroutines that read circular buffer
contents.
Thus, the buffer allocation specified by the integer
variable isz may be computed as
isz = (10 + 5

* n)

The number of entries to be contained in the buffer.
isz

Expressed in words.

18.4.11.2 Reading Digital Interrupt Data - Each of
the
following
routines reads data that has been stored in the circular buffer and
performs the following common processing:
i.

Detects, and optionally reports, the occurrence of an error
entry that has been placed in the buffer by the driver
because of a nonrecoverable device fault (for example, fatal
serial line error or remote power-fail).

18-52

INDUSTRIAL CONTROL SUBSYSTEMS
2.

Clears the trigger event flag when no further entries
to be processed.

Clears and optionally reports any overrun conditions.

Only one of the following three routines can be invoked
task:
1.

RODI:

remain

single

Read Digital Interrupt Data from a Circular Buffer

The RDDI FORTRAN subroutine reads contact interrupt data from
a circular buffer that was specified in a CTDI call (see
18.4.11.1).
It does no actual input or output,
but
rather
performs a
point-by-point scan of an interrupt entry in the
buffer; returning the state of each point as a logical value.
On the initial call to RODI, the module number and data of
the next
interrupt entry are read from the circular buffer
and stored for subsequent reference.
The subroutine then
sets the current data bit number n to O, examines the state
of data bit n, and converts bit n to a point number by the
following formula:
ipt

= module number * 16 + n

On each subsequent call, n is incremented by one and
then
data-bit n
is examined
in the stored module data.
When n
reaches lE, it is reset to 0 and an attempt is made to
read
the next
interrupt entry from
the circular buffer.
If a
valid entry is not found, ipt is set negative and
ict
(if
specified)
is either assigned a value of 0 or an overrun
count that is maintained by the ICS/ICR driver.
If ict is O,
no
further entries remain.
A nonzero value indicates that
the driver received more data than could be stored
in the
buffer,
and
ict represents the number of entries that were
discarded.
The variable ict receives the control register contents that
are
set
by
the
driver -- as
described
in Section
18.3.6 -- whenever a nonrecoverable controller error occurs.
Calling Sequence:
CALL RDDI

(ipt,ival[,ict])

Argument Descriptions:
ipt

A variable to which the digital
input point
number is returned.
It may be set as follows:
1.

ipt

0 if no valid entry is found

The specific value of
ipt reflects
that was detected as follows:
-1 - no data
(that
is,
no
currently in buffer)

the

error

interrupt

data

-2 - overrun
-3 - hardware error
2.

ipt => 0 if the value indicated is a
point
number;
the state is returned to ival.

18-53

INDUSTRIAL CONTROL SUBSYSTEMS
ival

A variable to which the state of
the
returned;
it may be set as follows:

ict

.FALSE.

(0)

.TRUE.

(-1) if the point is closed

point

if the point is open

Optional integer variable to receive the overrun
count or the contents of the CSR register on the
occurrence of
a
fatal
controller
error.
Otherwise, set to O.
NOTE
A task
reading
the circular
buffer
should
not
issue a Wait-For directive
until
a
buffer-empty
condition
is
reported.
See Section 18.4.11.11 for an
example of how to
read
circular-buffer
entries.

RDCS:

Read Digital Interrupt Points That Have Changed State

The RDCS FORTRAN subroutine returns data
in the
format of
subroutine RDDI
as described above
except that only
points that have changed state are
processed,
resulting
in
significantly improved
throughput and
reduced
processing
overhead for the calling task.
Processing specific to the routine is as follows:
On the initial call, the module number,
module data,
and
change of state information are read from the circular buffer
and stored for later reference.
The subroutine then sets the
current data bit number n
to
0 and begins scanning the
change-of-state word until a nonzero bit is found.
The point
number and current state are
then reported as previously
described.
If no change of state is found or when no further
bits
remain to be processed, the next entry is fetched as
described above.
The processing of error conditions is identical to subroutine
RDDI.
Calling Sequence:
CALL RDCS

(ipt,ival[,ict])

Argument Descriptions:
ipt

Integer variable to receive the digital
point number.
It may be set as follows:
1.

input

ipt 0 if no valid entry is found
(that is,
overrun,
error, or no data in buffer).
The
specific value of
ipt
reflects the error
that was detected as follows:
-1 -2 -3 -

no data
overrun
hardware error

18-54

INDUSTRIAL CONTROL SUBSYSTEMS

2.
ival

ict

ipt => 0 if the value indicated is a point
number, the state is returned to ival.

Integer variable to receive the
point as a logical value where:
1.

.FALSE.

(0)

Point open

.TRUE.

(-1)

Point closed

state

the

Optional integer variable.
A nonzero value
indicates that the variable has been set with an
overrun count returned by the driver, or with
the
contents
of the CSR register on the
occurrence of
a
fatal
controller
errore
Otherwise, set to O.
NOTE
A task reading the circular
buffer
should not issue a Wait-For directive
until a
buffer-empty
condition
is
reported. See Section 18.4.11.11 for an
example of how to read circular-buffer
entries.

RDWD:

Read a Full Word of Digital Interrupt Data

The following subroutine is called to return a full word of
digital
interrupt
data from the circular buffer, and
optionally change of state information. A new entry is read
for each call; hence, throughput is high when processing is
contingent upon several possible conditions within a module.
Calling Sequence:
CALL RDWD ( imod, i val [, ict] [, icos])
Argument Descriptions:
imod

Integer variable to receive the module number or
status as follows:
1.

imod 0 if no data is present or
condition or error was detected

overrun

The specific value of ipt reflects the error
that was detected as follows:
-1 -2 -3 2.

ival

no data
overrun
hardware error

imod => 0 Module number.
in ival

Integer variable
interrupt data.

18-55

Interrupt data

receive

the

digital

INDUSTRIAL CONTROL SUBSYSTEMS

ict

Optional
integer
variable
to
receive
change-of-state information.
Bits set to a 1
correspond to points for which a change of state
has been recorded.

icos

NOTE
A task reading the circular
buffer
should not issue a Wait-For directive
until a
buffer-empty
condition
is
reported. See Section 18.4.11.11 for an
example of how to read circular-buffer
entries.

DFDI: Disconnect a Buffer from Digital Interrupts - The
following routine is called to disconnect a task's circular buffer
from digital interrupts.

18.4.11.3

Calling Sequence:
CALL DFDI ( [ isb] [ ,lun])
Argument Descriptions:
isb

lun

Optional 2-word integer array to receive the results of
the call as follows.
isb(2) is always O.
+l

Function successfully completed

Insufficient dynamic
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+322

Task not connected to interrupts.

storage

allocate

Integer variable containing logical unit number.

CTTI: Connect a Buffer for Receiving Counter Data - The
following subroutine may be called to connect a circular buffer that
is to receive counter data, and to define an event flag that is to be
set upon occurrence of each interrupt.
18.4.11.4

Calling Sequence:
CALL CTTI (ibuf,isz,iev,iv[,isb] [,lun])

, o_c:
i:::
- -' \..}

.J.. u

INDUSTRIAL CONTROL SUBSYSTEMS
Argument Descriptions:
ibuf

An integer array making up the circular buffer that
to receive interrupt data.

isz

Integer variable specifying the length of the
buffer in words.

iev

Integer variable defining an event flag that is to be
set whenever the driver receives an interrupt from a
counter module.

Integer array of initial counter values.
One element
is required for each counter in the physical unit. The
value is used to initialize and reset the counter when
a value of O is reached. This parameter may be reset
for a specific module through a call to SCTI.

isb

Optional 2-word integer array to receive the results of
the call.
The status values specified below are
returned to isb(l).

lun

circular

Function successfully completed.
isb(2)
receives the number of words passed per
interrupt in the low byte.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+303

Controller not ready.

+306

Part of buffer is out of the user's address
space or buffer is too small to accommodate
a single entry.

+316

Privilege
violation -- task
checkpointable and not fixed in memory.

+319

Buffer address or length is an
of bytes.

+322

Another task
interrupts.

+397

Invalid event flag specified.

already

odd

number

connected

Integer variable specifying the logical unit number.

The space allocated for the circular buffer must be large enough to
accommodate at least one 4-word entry plus an additional 8 words of
storage required by the subroutine that reads buffer contents
(RDTI).
The buffer allocation specified by the variable isz may be computed as
isz

= (8 + 4 * n)

The number of entries to be contained in the buffer.

18-57

INDUSTRIAL CONTROL SUBSYSTEMS

NOTE
A task reading the circular
buffer
should not issue a Wait-For directive
until a
buffer-empty
condition
is
reported. See Section 18.4.11.11 for an
example of how to read circular-buffer
entries.

18.4.11.5 RDTI: Read Counter Data from the Circular
following call returns counter interrupt data from
buffer. A new entry is read on each call.

Buffer - The
the circular

Calling Sequence:
CALL RDTI (imod,ival(,ict])
Argument Descriptions:
Integer variable to receive module number and status as
follows:

imod

imod O No data in buffer, data overrun or error
condition
detected The specific value of ipt
reflects the error that was detected as follows:
-1 -

-2 -3 2.

no data
overrun
hardware error

imod => 0 Module number of counter.
is in ival.
to

receive

the

Interrupt data

iv al

Integer variable
interrupt.

counter

data

ict

Optional integer variable to receive the overrun count,
or the !CSR contents returned by the driver on the
occurrence of a fatal hardware error.
Otherwise, set
to 0.
NOTE
A task reading the circular buffer should not
issue a Wait-For directive until a buffer-empty
condition is reported. See Section 18.4.11.11
for an example of how to read circular-buffer
entries.

18.4.11.6
1.

Miscellaneous Counter Routines

RSTI:

Read a Counter Module

The following routine directly accesses a counter register to
return its current value.

18-58

INDUSTRIAL CONTROL SUBSYSTEMS

Calling Sequence:
CALL RSTI ( imod, i sb [Ii un] )
Argument Descriptions:
imod

An integer variable ~ontaining the number of the
counter to be read.

isb

A 2-word integer array to receive status and
data as follows. Status is returned to isb(l).

iun
2.

SCTI:

Function
successfully
completed.
Data is returned to isb(2).

+321

Nonexistent module specified.

Optional integer variable specifying the ICS/ICR
physical unit number.
Reset a Counter Initial Value

The following routine may be called by any task to revise the
initial value that is used to activate a counter.
Calling Sequence:
CALL SCTI (imod,ival[,isb] [,lun])
Argument Descriptions:
imod

Integer variable specifying the relative
number of the counter to be reset.

ival

Integer value specifying the new initial value.

isb

Optional 2-word integer array to receive
as follows.
isb(2) is always 0.

lun

module

status

Function successfully completed

Insufficient dynamic
allocate an I/O packet

Unassigned LUN

+99

Invalid LUN

+303

Controller not ready

+321

Nonexistent module specified

storage

Integer specifying the logical unit number.

18.4.11.7 DFTI: Disconnect a Buffer from Counter Interrupts - The
following subroutine is called to disconnect the task 1 s circular
buffer from interrupts.
Calling Sequence:
CALL DFTI ( ( isb] [, lun])

18-59

INDUSTRIAL CONTROL SUBSYSTEMS
Argument Descriptions:
isb

lun

Optional 2-word integer array
follows.
isb(2) is always O.

receive

status

Function successfully completed.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+322

Task was not connected to interrupts.

Integer variable specifying the logical unit number.

18.4.11.8 CTTY: Connect a Circular Buffer to Terminal Interrupts - The
following routine allows a task to provide a circular buffer to
receive remote terminal input data, and to define an event flag that
is set on the occurrence of each interrupt.
Calling Sequence:
CALL CTTY (ibuf ,isz,iev[ ,isb] [,lun])
Argument Descriptions:
The following arguments are identical in form and function
described for subroutine CTDI (see Section 18.4.11.1):
the

circular

those

buffer

that

ibuf

An integer array making up
receives interrupt data

isz

Length of the circular buffer in words

iev

Event flag to be set on each terminal interru?t

Buffer size is computed as
isz

= (8 + 4 * n)

The number of entries that can be stored in the buffer.
isb

Optional 2-word integer array to receive the results of
the call.
The status values specified below are
returned to isb(l).
+l

Function successfully completed.
isb(2)
receives the number of words passed per
interrupt in the low byte.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned LUN.

+99

Invalid LUN.
i8-60

INDUSTRIAL CONTROL SUBSYSTEMS

lun

+306

Part of buffer is out of the user's address
space or buffer is too small to accommodate
a single entry.

+316

Privilege
violation -- task
checkpointable and not fixed in memory.

+319

Buffer address not on a word boundary
length is an odd number of bytes.

+321

Nonexistent
ICSll.

module

Unit

+322

Another task
interrupt.

connected

+397

Invalid event flag specified.

specified.
already

Logical unit number.

18.4.11.9 RDTY: Read a Character from the Terminal Buffer - This
subroutine retrieves a single character from the terminal circular
buffer on each call.
Calling Sequence:
CALL RDTY (ind,ichr[,ivr])
Argument Descriptions:
ind

An integer variable to receive status as follows:
1.

=O character retrieved from buffer is in ichr

<O no data in buffer, overrun, or hardware error
The specific value of ind reflects the
was detected as follows:
-1 -

-2 -3 -

error

that

no data
overrun
hardware error

ichr

Logical * 1 or integer variable to receive the terminal
data.
If an integer is specified, only the low byte
will be set.

ivr

Optional integer variable to receive the overrun count,
or the ICSR contents on the occurrence of a fatal
hardware error. Otherwise, set to O.
NOTE
A task reading the circular buffer should not
issue a Wait-For directive until a buffer-empty
condition is reported. See Section 18.4.11.11
for an example of how to read circular-buffer
entries.

18-61

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.11.10 DFTY: Disconnect a Circular Buffer from Terminal Input The following
routine disconnects a task's circular buffer from
terminal inputs.
Calling Sequence:
CALL DFTY { [ i sb] [I 1 un] )
Argument Descriptions:
isb

lun

Optional, 2-word integer array to receive status
isb{l) as follows.
isb{2) is always set to O.

Function successfully completed.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+322

Task was not connected to interrupts.

An integer specifying the logical unit number.

18.4.11.11 Programming Example - The following are excerpts from a
FORTRAN program that is to monitor a remote terminal for input and
echo the received characters when a carriage return is detected.

c
C

SPECIFY BYTE FORMAT FOR TERMINAL DATA

c
LOGICAL*l TCHR

c
C
C

ALLOCATE STORAGE FOR THE TERMINAL
BUFFER

c
c
C
C
C

DIMENSION IBUF(32)
ALLOCATE STORAGE FOR THE PACKED
INPUT DATA SO THAT IT IS ALIGNED
ON A WORD BOUNDARY
DIMENSION ICHR(40)
DIMENSION TCHR(80)
EQUIVALENCE {TCHR,ICHR)

c
C
C

ALLOCATE STORAGE FOR A
2-WORD STATUS BLOCK
DIMENSION ISB{2)

c
C
C

INITIALIZE ICRll LOGICAL UNIT{7) AND
TRIGGER EVENT FLAG NUMBER{2)
DATA IEV, LUN/2, 7/

18-62

INDUSTRIAL CONTROL SUBSYSTEMS

c
C
C

CONNECT THE TASK TO TERMINAL
INPUTS. IF CONNECT FAILS--STOP 1

CALL CTTY (IBUF,32,IEV,ISB,LUN)
IF (ISB(l) .GE.3) STOP 1

C
C
C
C
C

10--POLL THE CIRCULAR BUFFER
FOR DATA. ECHO THE LINE WHEN
80 CHARACTERS ARE RECEIVED
OR A CARRIAGE RETURN IS
DETECTED.

DO 70 I

20--WAIT FOR TRIGGER EVENT FLAG

c
c

= 1,80

c
20

CALL WAITFR (IEV)

c
C
C

30--PACK THE CIRCULAR BUFFER DATA
INTO THE BYTE ARRAY

c
30

CALL RDTY (ISB,TCHR(I), IVR)

c
C

c
c

DISPATCH ON ERROR CONDITION
GO TO (20,50,40)-ISB
GO TO 60

40--REPORT HARDWARE FAULT

CALL ALARM (IVR)

GO TO 30

c
C

50--REPORT OVERRUN CONDITION

c
50

c
C
C
C

CALL LOST (IVR)

GO TO 30
60--CHECK FOR CARRIAGE RETURN,
EXIT TO ECHO ROUTINE IF
PRESENT

c
60

IF (TCHR(I) .EQ."15) GO TO 80

CONTINUE

c
C

80--FALL THROUGH TO ECHO A LINE
CALL RTOW (I,TCHR,,LUN)

c
C

DISCONNECT TERMINAL BUFFER, EXIT

c
CALL DFTY (,LUN)
CALL EXIT
END

18-63

INDUSTRIAL CONTROL SUBSYSTEMS

The procedure for reading the buffer
summarized as follows:

the

example

the

call

Wait for the trigger event flag
connect the buffer.

Upon regaining control, call the appropriate routine to read
the buffer until one of the following terminal conditions is
detected:
All data has been read.

An overrun count is detected.

A fatal error is encountered.

may

specified

above

On the occurrence of 2a or 2b, perform any appropriate
processing; then return to scan for additional data.

If a hardware error is detected, use the ICSR register
contents
for
further
fault
analysis and warning as
appropriate. In the event of such an error, the event flag
will not be set by the driver again unless normal service is
resumed.

A calling task should not execute the Wait-For directive
until a buffer-empty condition is detected. This is because
the user's buffer pointer is advanced after detecting and
clearing an overrun condition, and the trigger-event flag is
cleared only when a buffer-empty condition is detected.

18.4.12

Unsolicited Interrupt Processing - Task Activation

The following routines provide the capability of linking a task to an
interrupt, soliciting information from the driver concerning how the
task was activated, and unlinking a task from all interrupts.

18.4.12.1 LNK: Link a Task to Interrupts - This
any
installed task to be activated on the
unsolicited interrupt.
Calling Sequence:
CALL LNK (tnam,iprm[,isb] [,lun])

18-64

subroutine
occurrence

allows
of any

INDUSTRIAL CONTROL SUBSYSTEMS

Argument Descriptions:
tnam

Real variable containing
format.

task

name

iprm

A 5-word integer array
data:

containing

iprm(l)

Interrupt class.

RADIX-50

the

following

May be one of the following:

0 - Digital interrupts
l

Counters

2 - Remote terminal (CTRL/C only)
3 - Error interrupts
iprm(2)

Reserved.

iprm(3)

Optional event flag set if task to be activated is
not dormant when the interrupt occurs.

iprm(4)
iprm(5)

Hardware-dependent parameters as follows:

Interrupt Class

isb

Parameter Contents

Dioital

iprm(4)
iprm(5)

Point number
Change-of-state mask

Counter

iprm(4)
iprm(5)

Module number
Counter initial value

Remote Terminal

iprm(4)
iprm(5)

not used
not used

Error

iprm(4)
iprm(5)

not used
not used

Optional 2-word integer array to receive status in
isb(l) as follows.
isb(2) is always set to O.
+l

Function successfully completed.

Unrecognized
specified.

Insufficient
dynamic
allocate I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+301

Task tnam not installed.

18-65

interrupt
storage

class
to

INDUSTRIAL CONTROL SUBSYSTEMS

lun

+303

Controller not ready.

+317

Resource in use.
Other
linked to interrupt.

+323

Insufficient
dynamic
memory
allocate secondary control block.

+380

Task tnam not installed.

+397

Invalid event flag number specified.

Optional
number.

integer

specifying

the

task

already
to

unit

logical

Example:
Link task ALARM to
report fatal
hardware
malfunction on any ICRll physical unit.

errors

arising

from

DIMENSION I PRM { 5)

c
c

c
c
c

INITIALIZE PARAMETER ARRAY WITH:
1.
INTERRUPT CLASS
2.
RESERVED ELEMENT CLEARED
3.
GLOBAL EVENT FLAG

c
DATA IPRM(l), IPRM(2), IPRM{3)/3,0,64/

DATA ALARM/6RALARM /

CALL LNK (ALARM,IPRM,,7)

18.4.12.2 RDACT:
Read Activation Data - The following call allows a
task to determine the interrupt conditions that caused it to become
active.
Calling Sequence:
CALL RDACT { i prm [ , i sb] [, 1 un] )
Argument Descriptions:
iprm

A 6-word integer array to receive activation
in the following format.

iprm(l)

Activation indicator (see Section 18.3.7.5).

iprm(2)

Physical unit number of ICR.

18-n6

data

INDUSTRIAL CONTROL SUBSYSTEMS
Generic code.

iprm(3)

Set to one of the following values:

- Remote terminal

1,2,3

- Digital interrupt

4,5,6

- Counter interrupt

177770

- Fatal hardware error

iprm(4)

Relative module number.

iprm(5)
iprm(6)

Hardware-dependent data.

The following data is
module:
Module Type

returned

based

upon

Generic
Code

type

the

interrupt

Parameter Contents

Remote Terminal

iprm(5)
iprm{6)

terminal input character
undefined

Digital Interrupt

1,2,3

iprm(5)
iprm{F>)

module data
change-of-state data

Counter

4,5,i:i

iprm{5)
iprm(n)

value of the counter at
interrupt
undefined

iprm(5)
iprm(6)

contents of ICSR
contents of ICAR.

Error

isb

lun

177770

Optional 2-word integer array to receive
isb(l) as follows.
isb{2) is set to O.

status

Function successfully completed.

Insufficient dynamic
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+306

iprm array not fully
addressing space.

+319

Address of iprm is odd.

+379

Task not linked to ICS/ICR interrupts.

storage

within

the

allocate

task's

Integer variable specifying the logical unit number.

18-67

INDUSTRIAL CONTROL SUBSYSTEMS
Example:
The following is an excerpt from a program that reads activating data
into array IACT and conditionally exits
if the event flag (IEFN)
specified in a previous link request, issued by another task,
is not
set.

c
C

ALLOCATE SPACE FOR DATA ARRAY
DIMENSION IACT(6)

CALL RDACT (IACT,,7)

c
C

CLOSE ALL FILES

c
CALL CLOSE(l)
CALL CLOSE(2)

c
C
C

EXIT IF TRIGGER EVENT FLAG IS NOT SET
ELSE CLEAR EVENT FLAG AND RESTART.

c
CALL EXITIF (IEFN)

c
C
C

FLAG WAS SET.
CONTINUE.

CLEAR IT AND

c
CALL CLREF (IEFN)
GO TO 10
STOP
END
The foregoing example illustrates the following considerations when
task is made active by ICS/ICR interrupts:

To avoid race conditions, the
Exit-If directive should be
used
to test the state of the event flag and conditionally
exit.
Issuing a Test Event Flag directive followed
by an
Exit would cause a
flag set condition occurring after the
test to go unrecognized.

Use of the Exit-If directive bypasses the closure of all
files
that
is normally done automatically by the FORTRAN
object time system when the program executes a STOP or CALL
EXIT statement.
Thus,
to exit cleanly, the program must
explicitly close all files before invoking the directive.

18.4.12.3 UNLNK:
Remove Interrupt Linkage to a Task - The following
call removes all linkage between a task and ICS/ICR interrupts.

18-68

INDUSTRIAL CONTROL SUBSYSTEMS

Calling Sequence:
CALL UNLNK ( tnam, i prm [ , i sb J [, 1 un] )
Argument Descriptions:
tnam

Real variable containing task name in Radix-50 format.

iprm

Integer variable containing the interrupt
be one of the following:

class.

May

0 - Digital interrupts

l - Counters
2 - Remote terminal
3 -

Error interrupts

4 - All interrupts

isb

Optional, 2-word integer array to receive the results
of the call in isb(l) as follows.
isb(2) is set to O.

lun

Function successfully completed.

Insufficient dynamic storage to allocate an
I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+379

Task not linked to ICS/ICR interrupts.

+380

Task not installed.

Integer variable specifying the logical unit number.

Example:
Remove the linkage between task ALARM and all ICS/ICR interrupts.
DATA ALARM/6RALARM /
CALL UNLNK (ALARM,,,7)

18.4.13

Maintenance Functions

The following functions cause the ICS/ICR driver to suppress or enable
hardware error reporting while on-line maintenance and troubleshooting
is in progress, as described in Section 18.3.9.
OF LIN

Place selected unit off line.

ONLIN

Return selected unit to on-line status.

These calls may be issued only by a privileged task.

18-69

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.13.1 OFLIN: Place Selected Unit in Offline Status - The following
call is executed to set a controller off line:
CALL OFLIN ([isb]

[,lun])

Argument Descriptions:
isb

lun

Optional 2-word integer array to receive the results of
the call in isb(l) as follows.
isb(2) is always O.
+l

Function successfully completed.

Insufficient dynamic
I/O packet.

LUN not assigned.

+99

Invalid LUN.

+316

Issuing task not privileged.

+380

Device already off line.

Integer variable specifying the
number.

s~orage

ICS/ICR

to allocate an

logical

18.4.13.2 ONLIN: Return a Device to On-line Status - The
call will return the selected unit to on-line status.
CALL ONLIN ([isb]

unit

following

[,lun])

Argument Descriptions:
isb

lun

18.5

Optional 2-word integer array to receive the results of
the call in isb(l) as follows.
isb(2) is always o.
+l

Function successfully completed.

Insufficient dynamic storage to allocate an
I/O packet.

LUN not assigned.

+99

Invalid LUN.

+316

Issuing task not privileged.

Integer variable specifying the logical unit number.

ERROR DETECTION AND RECOVERY

Error Detection
contingencies.

and

recovery

procedures

Nonrecoverabie seriai iine errors

Power-fail at the remote station

18-70

encompass

the

following

INDUSTRIAL CONTROL SUBSYSTEMS
3.

Power recovery at the processor

No response from an interrupting module

The first two conditions are dealt with in a manner similar to that of
other types of unsolicited interrupts.
Specifically, such occurrences
may cause a task to be activated, and are reported to all
tasks that
are connected to digital, counter, or terminal input.
The following
paragraphs discuss specific driver activity relating
to each error
condition.

18.5.1

Serial Line Errors

The
driver
detects
nonrecoverable
serial
line
errors.
A
nonrecoverable error condition is defined as the occurrence of a
predetermined number of error interrupts in an interval of 1 second,
or no
response from the controller upon initiation of an output data
transfer by means of the serial
line.
The occurrence of such a
condition causes the driver to perform as follows:
1.

Place the controller in a "not ready" status.

Disable further error interrupts.

Report the condition to the task that is linked to errors,
and
to any tasks connected to receive unsolicited interrupt
data from the faulty unit.
Subsequent QIO requests that
transfer data to or from the unit are rejected with a status
of IE.DNR.

Requests for interrupting modules that are pending (A/D converters and
terminal output)
are allowed to time out with the error code IE.DNR.
The serial line error rate required to consider the link inoperative
may be specified by the user at the time of system generation.
After
reporting the error as described above,
the driver will
automatically remove the "not ready" status when the error condition
is not detected at the end of any 1-second interval.
If requested
during system generation,
the state of the following remote modules
will be restored as described.
1.

Bistable outputs - set to last recorded state

Counters -

Analog outputs -

18.5.2

reinitialized to last initial value
restored to last output value

Power-Fail at a Remote Site

The detection of AC-low from the remote site will immediately trigger
the processing described
in Section 18.5.1.
The absence of AC-low
will automatically return the unit to the "ready" status.

18-71

INDUSTRIAL CONTROL SUBSYSTEMS
If specified, the state of the following remote modules will
restored as described:
1.

Bistable outputs - set to last recorded state

Counters -

Analog outputs -

18.5.3

then

reinitialized to last initial value
restored to last output value

Power Recovery at the Processor

Power recovery by the processor will initiate the activity described
in Section 18.5.2 for both local and remote file boxes.
However,
power recovery processing at the processor will not be reported
to a
task that is linked to error
interrupts or connected to receive
unsolicited interrupt data.

18.5.4

Unit in Off-line Status

A unit that is off line (see Section 18.3.9.1)
is considered
to be
under manual control for purposes of diagnosis and maintenance.
Under
these conditions, error reporting as described in Section 18.5.1 is
unnecessary and
frequently undesirable, since fault indications are
generally a by-product of these activities (that is, a remote unit
is
shut down to
install an
I/O module), not the result of a genuine
controller fault.
Furthermore, to permit the operation of diagnostic software,
it is
advisable to attempt to service all QIO requests regardless of the
controller status.
Consequently,
under these circumstances,
error
reporting and detection are modified as follows when the controller is
off line:
1.

Access to the controller with the intention of transmitting
data to or from the device is restricted to privileged tasks.

The task linked to error interrupts and any tasks
receiving
interrupt data are not notified of remote power-fail or fatal
serial line errors.

All device error interrupts become disabled.

An attempt is made to service all QIO requests if issued by a
privileged task.
If such requests time out (that is, A/D
converter or remote terminal output),
they are terminated
with the error code
IE.ABO rather
than with IE.DNR.
No
hardware errors are
reported
for
I/O requests that are
normally completed immediately (for example, bistable digital
output).

18-72

INDUSTRIAL CONTROL SUBSYSTEMS
18.5.5

Error Data -

ICSR and ICAR Registers

Whenever a reportable error occurs, the driver returns the contents of
the appropriate control and status register (ICSR) and, in some cases,
the contents of the address
register
(ICAR),
to assist
in fault
diagnosis.
Tables 18-8 and 18-9 describe the contents of these
registers.
Table 18-8
ICSR Contents

Bit

l
r

Name

Re<;id/

Write

Description

Indicates
output
accept new data.

buffer

cannot

MAINT

R/W

Maintenance.

13 'NOT USED

Always set to 1.

ERROR

Indicates
occurrence
communication
serial
line
Reset when ICAR is read.

of
error.

MAINT

R/W

Maintenance.

I PWR FAIL

Remote Power Supply AC LO indicator.

15 !OUTPUT BUSY
14

TBMT INT EN

R/W

Enables bit 15 of ICAR to interrupt.

. MAINT

R/W

Maintenance.

MOD INT

Indicates
Module
I/O
interrupt servicing.

RESET

Resets all I/O modules.
as 0.

TTY ENABLE

R/W

Activates
mode.

PWR FAIL INT
ENABLE

R/W

Enables bit 10 to interrupt.

BMT INT ENABLE

R/W

Enables complement
interrupt.

MOD INT ENABLE

R/W

Enables Bit 7 to interrupt.

ERROR INT ENABLE

R/W

Enables Bit 12 to interrupt.

IRIF

R/W

Resets the
interrupting
module's
flag when set and
the module is
addressed.
This clearing
action
also resets the RIF bit.

1
0

18-73

TTY

mode,

requires
Always read

disables

bit

I/O

15 to

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-9
ICAR Contents
Bit

Name

Description

TBMT

Indicates TTY output
accept new data.

PCL

Pulse closed. This bit is set by a
jumper
on
a
digital interrupt
module. This jumper is removed if
contact closures are not of interest
to the user.

POP

Pulse Opened. This bit is set by a
jumper
on
a
digital interrupt
module. This jumper is removed if
contacts opening are not of interest
to the user.

buffer

can

Indicates terminal character
has
been received.
Cleared by reading
terminal character.

11-08

Generic Code

A 4-bit binary code that identifies
the type of module requesting the
interrupt.

07-00

Module Address

8-bit
address
of
the
requesting the interrupt.

18.n

module

DIRECT ACCESS

Section 18.1.3 notes those ICS/ICRll functions that may be performed
by referencing a module through its physical address in the I/O
page. Under RSX-llM such access is accomplished by one of the
following methods:
1.

A privileged task or any task running in an unmapped system
has unrestricted access to the I/O page and may therefore
access each module by absolute address.

Using the Task Builder, a task may link to a global common
area whose physical address limits span a set of locations
in the I/O page. This method applies to either a mapped or
unmapped system.

The latter method allows a task to be transported to any other
system simply by relinking. Moreover, in a mapped system the memory
management hardware aborts all references to device registers
outside the physical address limits of the common block.
Because the software allows arbitrary module placement, direct
reference, in either case, must be accomplished by translating a
relative module number to a physical or virtual register address
within the I/O page. This translation or mapping is performed by
means of a table
(ICTAB.MAC)
that is created during
system
generation, and inserted in the system object module library~

18-74

INDUSTRIAL CONTROL SUBSYSTEMS
The operations required to implement each method may
as follows:
1.

summarized

Unrestricted access to the I/O page
a.

Based upon the user's response to the ICS/ICR SYSGEN
queries,
the
MACRO
source
file
ICTAB.MAC
is
automatically created under UIC [11,10] on the source
disk.
This file contains tables that describe the
physical loca~ion of each counter, digital
interrupt,
and digital sense module in the target system.

ICTAB.MAC is assembled for eventual
system object module library.

The MACRO source file ICOM.MAC, under UIC
[11,10]
on
the source disk,
is assembled to generate global
definitions for the first ICS/ICR address on the
I/O
page and
the number of ICS/ICR controllers in the
target system.
The
resulting
object
file
is
incorporated in the system library file.

A task is built containing the appropriate global
references.
Such references are resolved when the Task
Builder automatically searches the system library.

inclusion

the

Steps a, b, and c are executed once.
Step d
is performed
each time a task that references the ICS/ICRll is created.
NOTE
ICS/ICR inputs are not valid until 3ms after power
recovery
at
the
processor.
Tasks that are
referencing inputs directly may establish a power
recovery
AST
entry point that suspends task
execution for the necessary time interval.

Access to the I/O page through a Global Common Block:
a.

Steps a and b are performed.

File !COM.MAC under UIC [11,10] is assembled to define
the first
ICS/ICR module address as a relocatable
value, the number of I/O page locations required, and
the number of controllers present on the target system.

File ICOM.OBJ, created in step b, is linked using the
Task Builder to create an image of the device common
block on disk.

The SET and INSTALL MCR or VMR commands are used to
allocate space for the common block and declare the
block resident in the target system.

A task is created containing the appropriate global
references to the common block and mapping tablee
Common block references are resolved by directing the
Task Builder to link the task to the device common
block (ICOM). The mapping table reference is resolved
from the system library module ICTAB.

18-75

INDUSTRIAL CONTROL SUBSYSTEMS
The detailed procedure for creating the necessary object files and
device common block is performed automatically as part of the system
generation process, and is described fully
in the RSX-llM System
Generation and Management Guide.
Therefore, the discussion in the
following paragraphs is limited to procedures for
linking
to
the
device common block,
and
using
the
file ICTAB.MAC to determine
module addresses within the I/O page.

18.6.1

Linking a Task to the ICS/ICR Common Block

Once the device common block has been created, a
task may access
ICS/ICR modules by linking to the common block.
This can be done by
using the Task Builder commands shown in the following example:
TKB>TASK,LP:=TASK.OBJ
TKB>/
ENTER OPTIONS:
TKB> COMMON=ICOM:RO·
TKB>/
The illustration is valid for either a mapped or unmapped system.
In both cases, the Task Builder links the task to the common block
by relocating the global symbol definitions contained in the common
block symbol table file ICOM.STB located under UIC [1,1].
If memory
management is present,
the Executive will map the appropriate
physical locations into the task's virtual addressing space when the
task is made active.

18.6.2

Accessing the I/O Page

After the task has been linked to the I/O page, either directly or
through
reference
to the device common block, access to a specific
ICS/ICR counter, or digital input modules during task execution,
is
a 3-step process:
1.

The task generates a request for module data by specifying
module type,
relative module number,
and physical unit
number.

The data contained in module ICTAB is accessed to translate
the arguments of step 1 to a physical offset from the
ICS/ICR base address on the I/O page.

The ICS/ICR base address, defined in the common block or
system library module that was created from file !COM.MAC,
is added to the offset to compute a
physical or virtual
address and the module data is read.

The next few paragraphs describe the format of the system library
module
ICTAB,
and common block module ICOM in detail.
A sample
MACRO subroutine that references these modules is then presented.

18-76

INDUSTRIAL CONTROL SUBSYSTEMS
18.6.2.l Mapping Table Format - The mapping table created by SYSGEN
(file ICTAB.MAC)
is used to translate module type, relative module
number, and physical unit number for counter, digital interrupt, and
digital sense modules, to the physical or virtual address of the
module on the I/O page. This module must be assembied and inserted
in the system object module library before the standard FORTRAN
callable routines can be used to read digital input and counter
modules.
The table contains one set of entries for each physical
unit. The entry sets are arranged in order of ascending unit number
(Figure 18-1). Entries within each unit are arranged in sequence by
module type, as shown in this figure.
DIGITAL SENSE
Ull..:1111-\L 11'1 IC

UNIT 0
MAPPING TABLE

COUNTER MODULES
INCREASING
MEMORY
ADDRESSES

.
..

DIGIT AL SENSE
DIGITAL INTERRUPT

UNIT N
MAPPING TABLE

COUNTER MODULES
ZK-009-81

Figure 18-1

Mapping Table Format

The structure of each entry is depicted in Figure 18-2. Entries are
18 bytes long.
Byte 0 contains the highest number of modules of a
given type that can be referenced for the controller.
Bytes 2
through 17, when indexed by relative module numbers, yield a value
between 0 and 255 representing the physical location of the module
within
the set of external page addresses allocated to the
ICS/ICRll.
The following global symbols are defined by this module:
.ICTAB

Location of mapping tables

I.CTBL

Length in bytes of one set of entries

18.6.2.2 I/O Page Global Definitions - As
previously
mentioned,
module ICOM contains symbolic definitions for I/O page references
that are resolved either through unrestricted access or by means of
a device common block that is resident on the I/O page. The
procedures for implementing either method are carried out during
system generation.
Upon completion, the following global symbols
are defined and later referenced
by
the
FORTRAN
callable
subroutines:

.ICMD

First ICS/ICR virtual or physical address
I/O page.

I$$Cll

Number of ICS/ICR controllers

18-77

within

the

INDUSTRIAL CONTROL SUBSYSTEMS
If the global common block was built,
the definitions above are
contained
in the symbol table file that was created by the Task
Builder; otherwise, they are included in the system object module
library.I
BYTE
RESERVED

MAX. MODULE NO.

PHYSICAL MODULE NO.

INCREASING
MEMORY
ADDRESS

4
6

8
10
12
14
16

ZK-010-81

Figure 18-2

Mapping Table Entry Format

18.6.2.3 Sample Subroutine - The following subroutine, residing
in
the system library, utilizes the modules previously described, to
read ICS/ICR module data.
READ ICS/ICR-11 DIRECT ACCESS INPUTS
LOCAL DATA
ADDRESS OF ICS/ICR-11 MAPPING TABLES
.ENABL

LSB

• REPT

12 •

.WORD

.ICTAB+I.CTBL*N>

N=O
ICMAP:

N=N+l
.ENDR
;+

1. The definitions are included in module !COM in the system library
or
in the STB file ICOM.STB under UIC[l,l] on the system disk.
The
STB file is automatically referenced by the Task Builder in response
to the use of the LIBR keyword.
18-78

INDUSTRIAL CONTROL SUBSYSTEMS
**-.RDIC-READ ICS/ICR-11 DIRECT ACCESS INPUTS
THIS SUBROUTINE IS CALLED TO TRANSLATE RELATIVE MODULE NUMBER
TO PHYSICAL EXTERNAL PAGE ADDRESS AND READ THE MODULE DATA.
INPUTS:
RO
Rl

RELATIVE MODULE NUMBER
MODULE CODE
WHERE:
0
1
2

STACK SETUP IS AS
(SP)+OO
;
(SP)+02
REFERENCED).
(SP)+04
OUTPUTS:

CONTACT SENSE
CONTACT INTERRUPTS
COUNTERS
FOLLOWS:
RETURN TO CALLER
I/O STATUS BLOCK ADDRESS (NOT
PHYSICAL UNIT NUMBER

C/CLEAR
RO

MODULE DATA

C/SET:
NONEXISTENT PHYSICAL UNIT NUMBER OR MODULE
SPECIFIED
;-

• RDIC: :
MOV
CMP
BLO
ASL

4(SP),R2
#I$$Cll-l,R2
10$
R2

MOV

ICMAP(R2) ,R2

ASL
ADD

Rl
Rl,R2

ASL
ASL
ASL
ADD
TSTB
SEC
BEQ
INCB
CMPB
BLO
INC
ADD
CLR

Rl
Rl
Rl
Rl,R2
( R2)
10$
RO
(R2)+,RO
10$
R2
RO,R2
RO

COMPUTE OFFSET TO TABLE
MODULE EXIST?
ASSUME NO
IF EQ NO
CONVERT TO NUMBER OF MODULES
LEGAL MODULE NUMBER?
IF LO NO
POINT TO TABLE ENTRIES
OFFSET TO MODULE NUMBER
SET FOR MOVB WITHOUT SIGN

BISB
ASL
MOV

(R2) ,RO
RO
.ICMD(RO),RO

GET INDEX TO MODULE
CONVERT TO WORD OFFSET
GET MODULE DATA

GET PHYSICAL UNIT NUMBER
LEGAL UNIT NUMBER?
IF LO NO
CONVERT PHYSICAL UNIT NUMBER

TO WORD
OFFSET
GET ADDRESS OF MAPPING TABLE
ENTRIES FOR THIS UNIT
CONVERT CODE TO WORD OFFSET
MULTIPLY OFFSET BY 9 AND ADD
TO TABLE ADDRESS

EXTEND

10$:
RETURN

.END
18-79

INDUSTRIAL CONTROL SUBSYSTEMS
18.7

CONVERSION OF EXISTING SOFTWARE

The following paragraphs are
intended as guidance in converting
existing UDC or res software to run under the ICS/ICR-11 driver and
associated FORTRAN support routines.
The differences described here
are
restricted to module support and features that would affect
existing software. New features, unsupported in previous systems,
are not discussed.

18.7.1

Features

Principal features affecting existing software are:
1.

Support for the ICS/ICRll as a
device

multiunit,

Removal of software restrictions
functionally similar modules

the

multicontroller
placement

Multiunit support affects any software that addresses modules
outside the range of a single file box.
In general, such software
must be modified at the source level.
Unrestricted module placement affects MACR0-11
programs
that
directly access digital
input and counter modules.
Such programs
may utilize the library routine described in Section 18.3 to
read
data from these modules.

18.7.2

18.7.2.1

Module Support

!AD-IA A/D Converter and IMX-IA Multiplexer

MACRO Interface:
Identical to UDCll driver
FORTRAN Interface:
Same as UDCll
Functional Differences:
The ICS/ICR driver can initiate parallel conversions on each
IAD-IA in a
file box that is referenced by a single QIO
request.
The UDCll driver performs all conversions serially.
The ICS/ICR driver supports any permissible configuration of
IAD-IA A/D converters and
IMX-IA multiplexers.
The UDCll
driver requires that eight module slots be reserved for each
IAD-IA in the system regardless of the actual number of
multiplexers installed.

18-80

INDUSTRIAL CONTROL SUBSYSTEMS
18.7.2.2

16-Bit Binary Counter

MACRO Interface:
Identical to UDCll driver
FORTRAN Interface:
Same as UDCll;
however, if the counter is read through a call
to RDTI,
then the task must be relinked to incorporate the
revised FORTRAN Interface routine.

Functional Differences:
The ICS/ICR driver permits any task to reset an initial counter
value
(with FORTRAN call
SCTI or through the
IO.ITI QIO
function).
The UDCll driver restricts this operation to a task
that has connected to counter interrupts.

18.7.2.3

Bistable Digital Output

MACRO Interface:
Identical to UDCll
FORTRAN Interface:
Identical to UDCll
Functional Differences:
None

18.7.2.4

Momentary Digital Output

MACRO Interface:
User interface is achieved with the QIO IO.MSO issued to
the
ICS/ICR-11 driver.
The UDCll driver does not support this
function since the module may be accessed directly through the
UDC device common block.
FORTRAN Interface:
Identical to UDCll; however, existing FORTRAN tasks must
relinked to include ICS/ICRll FORTRAN interface routines.

Functional Differences:
Momentary output operations are now processed by tne
ICS/ICR
driver, rather than through direct access to the I/O page.

18-81

INDUSTRIAL CONTROL SUBSYSTEMS

18.7.2.5

Noninterrupting Digital Input

MACRO Interface:
MACRO Interface is by means of the ICS/ICRll device
block and mapping table described in Section 18.6.

common

FORTRAN Interface:
Identical to UDCll; however, existing tasks must be relinked
to include revised ICS/ICRll FORTRAN interface routines.
Functional Differences:
None

18~7~2~6

Analog Output

MACRO Interface:
User interface is achieved with the QIO IO.SAO issued to the
ICS/ICR driver.
The UDCll driver does not support this
function since the module may be accessed directly through the
UDC device common block.
FORTRAN Interface:
Identical to UDCll; however, existing FORTRAN tasks must be
relinked to include ICS/ICRll FORTRAN interface subroutines.
Functional Differences:
Analog output operations are now processed by the ICS/ICR
driver rather than through direct access to the I/O page.

18.7.2.7

Interrupting Digital Input

MACRO Interface:
Identical to UDCll driver
FORTRAN Interface:
Identical to UDCll driver; however, if digital inputs are read
through the call to RCIPT, then the task must be relinked to
incorporate the revised ICS/ICRll FORTRAN interface routines.
Functional Differences:
None

18-82

CHAPTER 19

NULL DEVICE DRIVER

RSX-llM provides a driver for a software construct
device."
The
mnemonic
for the null device
characteristics are as follows:

called the "null
is NL:, and
its

•

A read from NL:

returns an end-of-file error (IE.EOF).

•

A write to NL:

immediately returns success (IS.SUC).

The null device functions as a "black hole" to which you can direct
output, and from which it will never return.
It is particularly
useful when used in conjunction with an indirect command file and MCR
ASN commands, as in the example below.
Figure 19-1 shows the contents of a Task Builder command file called
TESTBLD.CMD.
Symbolic device names are used for the output file, map
file, and input file.
These names may be reassigned at task-build
time.
In particular, in the example below, the map file is assigned
to the null device and thus is thrown away.
>ASN SY:=OU:
>ASN NL:=MP:

>ASN DKl:=IN:
>TKB @TESTBLD

OU:TEST,MP:TEST=IN:[200,220]TEST

I
ASG=TI:2

II
Figure 19-1

Indirect TKB Command File TESTBLD.CMD.

19-1

CHAPTER 20
GRAPHICS DISPLAY DRIVER

20.1

INTRODUCTION

RSX-llM provides support for two graphics display peripherals:
the
VTll and the VS60.
Graphics display drivers are not supported in
RSX-llM-PLUS systems.
Each consists of a CRT display, light pen, and
display processing unit (DPU).
Either may be purchased separately or
as part of a complete system.
For example, the GT46 is a
"starter
system" consisting of a VTll and a PDP-llT/34 with 32K words of memory
and disk storage.

20.1.1

VTll Graphics Display Subsystem

The VTll is a low-cost, line-drawing graphics display subsystem.
steals cycles asynchronously from the CPU whose UNIBUS it shares.
DPU instruction set supports the following features:

It
Its

•

Relative and absolute vectors -- solid, long dash, short dash,
or dotted

•

Point plotting

•

Character generation

•

Blinking display

•

Eight levels of intensity

•

Light-pen interaction

20.1.2

VS60 Graphics Display Subsystem

The VS60 supports all these features at a higher rate of performance
than the VTll.
In addition, the VS60 supports hardware subroutining,
scaling, and windowing. A second CRT may be added to the VS60.

20.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled
by the GET LUN INFORMATION system
directive (the first characteristics word) contains Os in all bits for
graphics display devices. Words 3, 4, and 5 are undefined.

20-1

GRAPHICS DISPLAY DRIVER
20.3

QIO MACRO

Table 20-1 lists the standard and device-specific functions of the QIO
macro that are valid for graphics display devices.
The standard QIO functions IO.ATT and IO.DET have little use
in the
graphics display driver,
because the specific functions IO.CON and
IO.DIS are available.
Table 20-1
Standard and Device-Specific QIO Functions for Graphics Displays
Format

Function

STANDARD FUNCTIONS

QIO$C IO. ATT, •••

Attach <levice

QIO$C IO. DET, •••

Detach device

QIO$C IO. KIL, •••

Cancel I/O requests

DEVICE-SPECIFIC FUNCTIONS
QIO$C IO.CON, ••• ,<stadd,size
[, lpef] [, lpast] >

CONNECT to graphics
device (start DPU)

QIO$C IO. CNT, •••

Continue (restart DPU)

QIO$C IO. DIS, •••

Disconnect from graphics
device (halt DPU)

QIO$C IO.STP, •••

Stop (halt DPU)

stadd
The starting address of a display file (must be word aligned).
The display file must be within the lowest 28K of physical memory
for the VTll.

size
The size of the display buffer in bytes.

lpef
The optional number of an event flag to
hit;
in the range 1-64 (10).

set

upon

light-pen

lpast
The optional address of an asynchronous system trap
point to be used upon light-pen hit.

20-2

(AST)

entry

GRAPHICS DISPLAY DRIVER
20.4

STATUS RETURNS

Table 20-2 lists error and status conditions that are returned by the
graphics display driver in the first word of the I/O status block.
The second I/O status word always contains O.
Table 20-2
Graphics Display Status Returns
Code

rs.sue

Reason
Successful completion
The operation specified
completed successfully.

IE.ABO

the

IE.DNA

directive

IO.KIL

while

The graphics device specified in an IO.CON function
already connected to another task.

was

Connection rejected

Device not attached
The graphics device specified in an IO.DET function
not attached to the issuing task.

IE.IEF

was

Operation aborted
The I/O operation was cancelled
progress or in the I/O queue.

IE.CNR

QIO

was

Illegal event flag
An event flag number specified in an IO.CON function
(lpef argument) was not in the range 1-64 (decimal).

IE.IFC

Illegal function code

A function code was specified in an I/O request that

illegal for graphics display devices.
IE.SPC

Illegal address space
The display buffer specified in an IO.CON function
(stadd argument)
was not word aligned, or (for VTll
only) was not completely within the lowest 28K of
memory.

20.5

PROGRAMMING HINTS

The graphics display driver does not determine what appears on the
screen of the VTll or VS60.
The key to what is drawn is the
collection of DPU instructions in the display buffer.

20-3

GRAPHICS DISPLAY DRIVER
Under normal circumstances, the display buffer is generated by calls
to a set of FORTRAN graphics subroutines. These subroutines provide a
more convenient access to the graphics features of the hardware than
do the raw DPU instructions. The subroutines are described in the
DECgraphic-11 FORTRAN Reference Manual, order number DEC-11-GFRMA-A-D.
Aborting a VTll task may cause an RSX-llM system to hang up
indefinitely, requiring a bootstrap.
The VTll DPU has no Halt
instruction, but the I/O driver must halt the DPU before it can return
a success status in response to an IO.KIL request.
(IO.KIL is
automatically generated when a task is aborted.) This hang situation
cannot arise with a VS60.

20-4

CHAPTER 21

LABORATORY PERIPHERAL ACCELERATOR DRIVER

21.1

INTRODUCTION

The Laboratory Peripheral Accelerator
(LPAll-K)
is an
intelligent,
direct memory access
(DMA) controller for DIGITAL's laboratory data
acquisition I/O devices.
It is a
fast,
flexible,
and easy-to-use
microprocessor subsystem that allows analog data acquisition rates up
to
150,000 samples per second.
The
LPAll-K is
designed
for
applications requiring concurrent data acquisition and data reduction
at high rates.
The LPAll-K is supported
through a device driver and a
set of
program-callable
routines.
The device driver supports multiple
controllers and can be configured as
resident or loadable.
The
program-callable support routines are linked with the user's task at
task-build time.
These routines are highly modular.
Therefore,
a
particular task contains only that code necessary for the facilities
actually used.
The
LPAll-K operates
in two
distinct
modes:
dedicated
multirequest.
The subsections that follow summarize each mode.

21.1.l

and

LPAll-K Dedicated Mode of Operation

In dedicated mode, only one user (that is, one request) can be active
at a time and only analog I/O data transfers are supported.
Up to two
analog converters can be controlled simultaneously.
Sampling
is
initiated by an overflow of the real-time clock or by an externally
supplied signal.

21.l.2

LPAll-K Multirequest Mode of Operation

In multirequest mode, sampling from all device types is supported.
Up
to eight users can be simultaneously active.
The sampling rate for
each user
is a multiple of the common real-time clock
rate.
Independent rates can be maintained for each user.
Both the sampling
rate and the device type are specified as part of each data
transfer
request.

21-1

LABORATORY PERIPHERAL ACCELERATOR DRIVER
GET LUN INFORMATION MACRO

21.2

If a Get LUN Information system directive
is
issued
for
a
LUN
associated with an
LPAll-K, word 2 (the first characteristics word)
contains all zeros, words 3 and 4 are undefined, and word 5 contains a
16-bit buffer preset value that controls the rate of the real-time
clock interrupts.

THE PROGRAM INTERFACE

21.3

A collection of program-callable subroutines provides access to
the
LPAll-K.
The
formats of these calls are fully documented here for
FORTRAN programs.
MACR0-11 programmers access these same subroutines
either
through the standard subroutine linkage or through the use of
two special-purpose macros.
Optionally, MACR0-11 users can control an
LPAll-K directly through the
use of device-specific QIO functions.
Both FORTRAN and MACRO programs must contain at least one
I/O Status
Block
(IOSB)
for
retrieval of status
information.
The following
subsections, therefore, describe:

The FORTRAN interface

•

The MACR0-11 interface

•

The I/O status block
NOTE
The subroutines documented
in
this
chapter
represent
the
high-level
interface to the LPAll-K.
Using
these
subroutines requires an understanding of
hardware
capabilities,
configuration
details,
and hardware status codes as
described
in the LPAll-K
Laboratory
Peripheral Accelerator User's Guide.

21.3.1

FORTRAN Interface

Table 21-1 lists the FORTRAN interface subroutines for
LPAll-K.

accessing

the

The calling sequences of the
routines listed
in Table
21-1 are
compatible with the K-series support routines, described in Chapter
22, except as noted.
The following subsections briefly describe the
function and format of each FORTRAN subroutine call.

21-2

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Table 21-1
FORTRAN Subroutines for the LPAll-K
Subroutine

Function

ADSWP

Initiate synchronous A/D sweep

CLOCKA

Set Clock A rate

CLOCKB

Control Clock B

CVADF

Convert A/D input to floating point

DASWP

Initiate synchronous D/A sweep

DISWP

Initiate synchronous digital input sweep

DOSWP

Initiate synchronous digital output sweep

FLT16

Convert unsigned integer to a real constant

IBFSTS

Get buffer status

IGTBUF

Return buffer number

INXTBF

Set next buffer

IWTBUF

Wait for buffer

LAMS KS

Set masks buffer

RLSBUF

Release data buffer

RMVBUF

Remove buff er from device queue

SETADC

Set channel information

SETIBF

Set array for buffered sweep

STPSWP

Stop sweep

XRATE

Compute clock rate and preset

21.3.1.1 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP
routine
initiates a synchronous A/D input sweep through an LPS-11 or an ADll-K
(and, if present, the AMll-K).
If differential input is desired for the ADll-K/AMll-K,
the channel
The default
increment must be set to 2 by calling the SETADC routine.
channel increment is 1 (single-ended input).

21-3

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The ADSWP call is as follows:
CALL ADSWP (ibuf ,lbuf, ~nbuf], (mode], (idwell], (iefn], (ldelay],
( ichn], (nchn], [ind])
ibuf
A 40-word array initialized by the SETIBF routine. The first two
words of the array are the I/O status block (IOSB).
lbuf
The size in words of each data buffer. All data buffers must be
equal in size and lbuf must be greater than 5.
In dedicated
mode, lbuf must be at least 257 words.
nbu
The number of buffers to be filled.
equal to O, indefinite sampling
terminates indefinite sampling.

If nbuf is omitted or set
occurs.
The STPSWP routine

mode
The sampling options. The default is 0.
The mode bit values
listed below that are preceded by a plus sign (+) are independent
and can be added or ORed together
(assuming that the sampling
options are applicable to the mode of operation). Those values
not preceded by a plus sign are mutually exclusive and only one
such value can be used at a time. All bit values not listed
below are reserved.
The following values can be specified:
0

Absolute channel addressing
(default).
This
mode
allows the user to directly access all 64 channels of
an A/D converter.

+32

Dual A/D conversion serial/parallel.
applies to dedicated mode only.
It
multirequest mode.

+64

Multirequest mode.
If this value is not specified, the
request is for dedicated mode.
If the request mode
does not match the mode of the hardware
(that is,
different microcode in the master microprocessor), the
LPAll-K rejects the request with an appropriate error
code.

+512

External trigger (STl).
This mode is used when a
user-supplied external sweep trigger is desired. The
external trigger is supplied by a jumper connecting the
ADll-K External Start input to the KWll-K Schmitt
Trigger 1 output. This external trigger connection can
only be used in Dedicated Mode.
If mode 512 is
selected, the user task must specify a Clock A rate of
-1 for proper A/D sampling. This is non-clock-driven
sampling.

21-4

This
option
is ignored in

LABORATORY PERIPHERAL ACCELERATOR DRIVER
+1024

Time stamp with Clock B (Multirequest mode only).

+2048

Event marking (Multirequest mode only)~
LAMSKS must be
called
to specify an event mark channel and event mark
mask.

+4096

Start method.
If set, digital input start.
If clear,
immediate start.
LAMSKS must be called to specify a
digital
start
channel
and
digital
start
mask
(multirequest mode only).

+8192

Dual A/D converter (dedicated mode only).

+16384 Data overrun NON-FATAL/FATAL.
If
selected,
data
overrun
is
considered
nonfatal.
The
LPAll-K
automatically defaults to fill buffer O.
(See Section
21.4 for a discussion of buffer management.)

idwell
The number of clock overflows
(pulses)
between data
sample
sequences.
As an example,
if idwell is 20 and nchn is 3, the
following occurs: after 20 pulses, one channel
is sampled on
each of the next three pulses.
Then, no sampling takes place for
the next 20 pulses.
In multirequest mode, this facility permits
different sample rates for
the same hardware clock rate and
preset.
In dedicated mode,
the clock hardware
rate controls
sampling and this idwell argument is ignored.
If compatibility with K-series support routines is desired,
user
task must first establish the clock preset by calling
CLOCKA routine.
The default idwell value of 1 is used
in
sweep start command.
For the K-series, this procedure sets
rate as desired.

the
the
the
the

NOTE
This parameter is called iprset in the K-series support
routines described
in Chapter
22.
Its function
is
different from the idwell parameter described here.

iefn
The event flag (1 to 28, 30 to 96),
the name of a completion
routine, or O.
If 0 or defaulted, event flag 30 will be used for
internal synchronization.
If iefn is an event flag, the selected
event flag is set as each buffer is filled.
Note that event flag
29 is reserved for
use by the
LPAll-K support
routines for
internal
synchronization.
If
iefn
is greater than 96, it is
considered to be a completion routine that will be called with a
JSR PC.
Such routines must return with an RTS PC (or a FORTRAN
RETURN statement).

21-5

LABORATORY PERIPHERAL ACCELERATOR DRIVER
FORTRAN completion
following:

routines

must

not

contain

any

•

Any I/O through the FORTRAN run-time system

•

Any use of virtual arrays

•

Any use of floating-point operations

•

Any errors, since error reporting is done through the
run-time system

•

Anything else that may change the FORTRAN impure area

the

FORTRAN

Any of the above may result in fatal task errors or unpredictable
results.
If multiple sweeps are
different event
flags.
enforced by the software.

initiated,
the
user should
specify
Adherence to this limitation cannot be

ldelay
The delay from the start event (DRll-K) until the first sample in
IRATE units.
This
feature
is supported in multirequest mode
only.
Default or 0 indicates no delay.

ichn
The number of the first channel to be sampled.
The default of 0
applies only if ichn was not established in a prior call to the
SETADC routine.

nchn
The number of channels to sample.
The default is l.
nchn may be
set up with the SETADC routine.
The number of channels specified
are sampled at a rate of 1 per clock interrupt.
If nchn equals
1,
the single channel bit is set in the mode word of the start
RDA.

ind
Receives a success or failure code as follows:
1

indicates that the sweep was successfully initialized.

indicates an illegal
argument
called prior to this call.

list,

-1 indicates a QIO directive
failure.
code is placed in IOSB(l) in IBUF.

The

SETIBF

was

di~ective

not

error

NOTE
The ind parameter is not supported by the K-series
support routines.
If compatibility with K-series
support routines is desired, this parameter must be
ignored.

21-6

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.3.1.2 CLOCKA: Set Clock A Rate - The CLOCKA routine sets the
for Clock A.
This routine is called as follows:

rate

CALL CLOCKA (irate,iprset, [ind], [lun])
irate
The clock rate.

One of the following must be specified:

-1 Direct-coupled Schmitt Trigger 1 {used only for A/D sweeps
in Dedicated Mode +512;
not supported by K-series support
routines)
0 Clock B overflow or no rate
1
1 MHz
2 100 KHz
3 10 KHz
4 1 KHz
5 100 Hz
6 Schmitt Trigger l
7 Line frequency
iprset
The two's complement value for clock preset.
The clock rate
divided by the negative clock preset value yields the clock
overflow rate.
For example, to obtain a clock overflow rate of
10 Khz with a clock rate of lMhz, iprset = -100 (minus 100
decimal).
The XRATE routine can be used
to calculate a clock
preset value.
ind
Receives a success or failure code as follows:
0

indicates an illegal argument list or I/O error.
Possible
causes are:
microcode not loaded;
driver not loaded;
device off line or not in system.

indicates Clock A set to start when sweep requested.

lun
The logical unit number.

The default is 7.

21.3.1.3 CLOCKB: Control Clock B - The CLOCKB routine gives the
control over the KWll-K Clock B.
The CLOCKB call is as follows:
CALL CLOCKB ([irate] ,iprset,mode, [ind], [lun])

21-7

user

LABORATORY PERIPHERAL ACCELERATOR DRIVER
irate
The clock rate. When irate is nonzero, the clock is set running
at the selected rate after the preset value specified by iprset
is loaded. A 0 irate stops the clock.
When irate is 0 or
default, the iprset and mode parameters are ignored.
The following values are acceptable for irate:
0
1

2
3

5
~

Stop clock B
lMHz
100 KHz
10 KHz
1 KHz
100 Hz
Schmitt Trigger 3
Line frequency

iprset
The count by which to divide clock rate to yield overflow rate.
Overflow events can be used to drive clock A. The preset
parameter must be specified as 0 or as a negative number in the
range -1 to -255. The value in iprset can be established by use
of the XRATE routine.
mode
The options. The mode bit values listed below that are preceded
by a plus sign
(+)
are independent and can be added or ORed
together. Those values not preceded by a plus sign are mutually
exclusive and only one such value can be used at a time. All bit
values not listed below are reserved.
1

indicates Clock B operates in noninterrupt mode.
The
lh-bit clock is not incremented or altered. This allows a
greater than lOKHz pulse to be sent to Clock A.

+/. indicates the feed B to A bit will be set in

the

Clock

status register.
ind
Receives a success or failure code as follows:

indicates an illegal argument list or I/O error.
Possible
causes are:
microcode not loaded;
driver not loaded;
device off line or not in system.

indicates Clock B started.

lun
The logical unit number (LUN).

21-8

The default LUN is 7.

LABORATORY PERIPHERAL ACCELERATOR DRIVER
CVADF
21.3.1.4 CVADF: Convert A/D Input to Floating Point - The
routine converts an A/D input value to a floating-point number. The
routine can be invoked as a subroutine or a function as follows:
CALL CVADF (ival,val)
or
val

CVADF(ival)

ival
A value obtained from A/D input.
represent the value.

Bits 12-15 are

Bi ts

0-11

val
(REAL*4) receives the converted value.
calculated with the following formula:
val

The

converted

value

= (n4*ival)/gain

21.3.1.5 DASWP: Initiate Synchronous D/A Sweep - The
initiates synchronous D/A output to an AAll-K.

DASWP

routine

The DASWP call is as follows:
CALL DASWP ( ibuf, lbuf, [nbuf] , (mode] , ( idwel 1] , [ iefn] , ldelay,
[ichn], [nchn], [ind])
ibuf
A 40-word array initialized by the SETIBF routine. The first two
words of the array are the I/O status block (IOSB).
lbuf
The size in words of each data buffer. All data buffers must be
equal in size and lbuf must be greater than 5.
In dedicated
mode, lbuf must be at least 257 words.
nbuf
The number of buffers to be emptied.
If nbuf is omitted or set
equal to O, indefinite sweeping occurs.
The STPSWP routine
terminates indefinite sweeping.
mode
The start criteria.
Except where noted, the plus sign (+)
preceding mode bit values listed below indicates that they are
independent and can be added or ORed together.
All bit values
not listed below are reserved.

21-9

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The following values can be specified:
0

indicates immediate start.

This is the default.

+64

Multirequest mode.
If this value is not specified, the
request
is
for dedicated mode.
If the request mode
does not match the mode of the hardware
(that
is,
different microcode
in master microprocessor),
the
LPAll-K rejects the request with an appropriate error
code.

+4096

Start method.
If set, digital input start.
If clear,
immediate start.
LAMSKS must be called to specify a
digital
start channel
and
a digital
start
mask
(multirequest mode only).

+16384 Data overrun NON-FATAL/FATAL.
If
selected,
data
overrun
is
considered
nonfatal.
The
LPAll-K
automatically empties buffer 0.
(See Section 21.4
for
a discussion of buffer management.)

idwell
The number of clock overflows
{pulses)
between data
sample
sequences.
For example,
if
idwell
is
20 and nchn is 3, the
following occurs:
After 20 pulses, one channel
is emptied on
each of the next three pulses.
Then, no emptying takes place for
the next 20 pulses.
In multirequest mode, this facility permits
different
rates for the same hardware clock rate and preset.
In
dedicated mode, the clock hardware
rate controls sampling
and
idwell in the sweep start command is ignored.
If compatibility with K-series support routines is desired,
the
user
task must
first establish the clock preset by calling the
CLOCKA routine.
The default value (1) for the
idwell
parameter
in
the sweep start command must be used.
For the K-series, this
procedure sets the
rate as desired.
For
the
LPAll-K,
this
procedure
results
in
idwell in the sweep call defaulting to 1,
thus yielding the same clock rate.

NOTE
This parameter is called iprset in the
K-series support
routines described
in Chapter
22.
Its function
is
different from the idwell parameter described here.

iefn
An event flag number (1 to 28, 30 to
96),
or
the name of a
completion routine, or O.
If 0 or default, event flag 30 is used
for internal synchronization.
If iefn
is an event flag,
the
selected
event flag is set as each buffer is filled.
Note that
event flag 29 is reserved for use by the LPAll-K support routines
for
internal synchronization.
If iefn is greater than 96, it is
considered to be a completion routine that will be called with a
JSR PC.
Such routines must return with an RTS PC instruction (or
a FORTRAN RETURN statement) •

21-iO

LABORATORY PERIPHERAL ACCELERATOR DRIVER
FORTRAN completion
following:

routines

must

not

contain

any

•

Any I/O through the FORTRAN run-time system

•

Any use of virtual arrays

•

Any use of floating-point operations

•

Any errors, since error reporting is done through the
run-time system

•

Anything else that may change the FORTRAN impure area

the

FORTRAN

Any of the above may result in fatal task errors or unpredictable
results.
If multiple sweeps are initiated, the user task should specify
different event flags. This limitation cannot be enforced by the
LPAll driver.
ldelay
The delay from start event (DRll-K) until the first sample in
irate units.
A minimum delay of 150 microseconds is required
(not verified by the LPAll driver). This feature is supported in
multirequest mode only.
ichn
The first channel number.

Default is channel number O.

nchn
The number of channels.

Default is one channel.

ind
Receives a success or failure code as follows:
1

indicates that the sweep was successfully initialized.

indicates an illegal argument
called prior to this call.

-1 indicates a QIO directive

list,

failure.
code is placed in IOSB(l) in IBUF.

SETIBF

was

The

directive

not
error

NOTE
The ind parameter is not supported by the K-series
support routines.
If compat1bility with K-series
routines is desired, this parameter
must
be
ignored.

21-11

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.3.1.6 DISWP: Initiate Synchronous Digital Input Sweep - The DISWP
routine initiates a synchronous digital input sweep through a DRll-K.
It can be called in multirequest mode only.
The DISWP call is as follows:
CALL DISWP (ibuf,lbuf,[nbuf] ,[mode] ,[idwell] ,[iefn] ,[ldelay],
[ iuni t], [nchn], [ind])
ibuf
A 40-word array initialized by the SETIBF routine. The first two
words of the array are the I/O status block (IOSB).
lbuf
The size in words of each data buffer. All data buffers must
equal in size and lbuf must be greater than 5.

nbuf
The number of buffers to be filled.
indefinite sampling occurs.
The
terminate indefinite sampling.

If nbuf is 0 or defaulted,
STPSWP routine is used to

mode
The sampling options. The default is O.
The plus signs (+)
preceding the mode bit values listed below indicate that they are
independent and can be added or ORed together.
All bit values
not listed below are reserved.
The following values can be specified:
O

Immediate start.

This is the default mode.

+512

External trigger. The input sampling will be triggered
by
interrupts generated by the DRll-K's external
control lines, or its input bits if they are interrupt
enabled.

+1024

Time stamped sampling with Clock B.
The double word
consists of one data word followed by the value of the
16-bit clock at the time of the sample.
IOSB(2)
contains the number of 2-word samples in the buffer.

+2048

Event marking. LAMSKS must be called to
event mark word and an event mark mask.

+4096

Start method.
If specified, digital input start.
If
clear, immediate start.
LAMSKS must be called to
specify a digital start channel and a digital start
mask.
The digital start channel need not differ from
the input channel (iunit).

specify

+16384 Data overrun NON-FATAL/FATAL.
If
selected,
data
overrun
is
considered
nonfatal.
1ne
LPAll-K
automatically fills buffer O.
(See Section 21.4 for a
discussion of buffer management.)

21-12

LABORATORY PERIPHERAL ACCELERATOR DRIVER
idwell
The number of clock overflows
(pulses)
between data sample
sequences.
As an example,
if idwell is 20 and nchn is 3, the
following occurs: After 20 pulses, one channel
is sampled on
each of the next three pulses.
Then, no sampling takes place for
the next 20 pulses.
In multirequest mode, this facility permits
different sample rates for
the same hardware clock rate and
preset.
If compatibility with K-series support routines is desired,
the
user
task must first establish the clock preset by calling the
CLOCKA routine.
The default value (1) for the
idwell parameter
in the sweep start command must be used.
For the K-series, this
procedure sets the
rate as desired;
For the
LPAll-K,
this
procedure results in
idwell in the sweep call defaulting to 1,
thus yielding the same clock rate.
NOTE
This parameter is called iprset in the
K-series support
routines described
in Chapter
22.
Its function
is
different from the idwell parameter described here.

iefn
An event flag number (1 to 28, 30 to 96),
or the name of a
completion routine, or 0.
If default or a value of 0 is
specified
for
iefn,
event flag
30 is used
for
internal
synchronization.
If
iefn
is a valid event flag, the selected
event flag is set as each buffer is filled.
Note that event flag
29 is reserved
for
use by the
LPAll-K support routines for
internal synchronization. -If iefn is greater than 96,
it is
considered to be a completion routine that will be called with a
JSR PC.
Such routines must return with an RTS PC instruction (or
a FORTRAN RETURN statement) •
FORTRAN completion
following:

routines

must

not

contain

any

•

Any I/O through the FORTRAN run-time system

•

Any use of virtual arrays

•

Any use of floating-point operations

•

Any errors, since error reporting is done through the
run-time system

•

Anything else that may change the FORTRAN impure area

the

FORTRAN

ldelay
The delay from start event (DRll-K) until
the
irate units.
Default or 0 indicates no delay.

21-13

first

sample

LABORATORY PERIPHERAL ACCELERATOR DRIVER
iunit
The DRll-K unit number.
are valid.

Default is unit number

Values

0-4

nchn
The number of channels. The LPAll-K treats each' DRll-K
configuration as one channel. Default is 1 channel.

its

ind
Receives a success or failure code as follows:
1

indicates that the sweep was successfully initialized.

indicates an illegal argument
called prior to this call.

-1 indicates a QIO directive

list,

failure.
code is placed in IOSB ( 1) in IBUF.

SETIBF

was

The

directive

not
error

NOTE
The nchn and ind parameters are not supported by
the K-series support routines.
If compatibility
with K-series support routines is desired, these
last two parameters must be ignored.

21.3.1.7 DOSWP: Initiate Synchronous Digital Output Sweep - The DOSWP
routine initiates a synchronous digital output sweep through a DRll-K.
It can be called in multirequest mode only.

The DOSWP call is as follows:
CALL DOSWP (ibuf ,lbuf, (nbuf], (mode], (idwell], (iefn] ,ldelay,
(iunit], (nchn], (ind])
ibuf
A 40-word array initialized by the SETIBF routine. The first two
words of the array are the I/O status block (IOSB).
lbuf
The size in words of each data buffer. All data buffers must
equal in size and lbuf must be greater than 5.

nbuf
The number of buffers to be emptied.
if nbuf is 0 or default,
indefinite emptying occurs.
The STPSWP routine is used to
terminate indefinite emptying.

21-14

LABORATORY PERIPHERAL ACCELERATOR DRIVER
mode
The start criteria.
The following values can be specified in the high-order
mode:

byte

Immediate start.

+512

will
be
External trigger.
The output
sampling
triggered by interrupts generated by the DRll-K's
external control lines or its input bits
if they are
interrupt enabled.

+4096

Start method.
If set, digital input start.
If clear,
immediate start.
LAMSKS must be called to specify a
digital start channel and a digital
start mask.
The
digital
start channel need not differ from the output
channel (iunit) e

This is the default mode.

+16384 Data overrun NON-FATAL/FATAL.
If
selected,
data
overrun
is
considered
nonfatal.
The
LPAll-K
automatically fills buffer O.
(See Section 21.4 for
a
discussion of buffer management.)
idwell
The number of clock overflows
{pulses)
between data sample
sequences.
For example,
if
idwell
is
20 and nchn is 3, the
following occurs: After 20 pulses, one channel is activated on
each of the next three pulses.
Then, no output takes place for
the next 20 pulses.
In multirequest mode, this facility permits
different output rates for
the same hardware clock rate and
preset.
If compatibility with K-series support routines is desired,
the
user
task must first establish the clock preset by calling the
CLOCKA routine.
The default value (1) for the
idwell parameter
in the sweep start command must be used.
For the K-series, this
procedure sets the rate as desired.
For the
LPAll-K,
this
procedure results in
idwell in the sweep call defaulting to 1,
thus yielding the same clock rate.
NOTE
This parameter is called iprset in the K-series support
routines described
in Chapter
22.
Its function
is
different from the idwell parameter described here.

iefn
An event flag number (1 to 28, 30 to 96), or the name of a
completion routine, or O.
If default or a value of 0 is
specified for
iefn,
event flag
30 is used
for
internal
synchronization.
If
iefn
is a valid event flag, the selected
event flag is set as each burrer is emptied.
Note that event
flag
29 is reserved for use by the LPAll-K support routines for
internal synchronization.
If iefn is greater than 96,
it is
considered
to be a completion routine that will be called with a
JSR PC.
Such routines must return with an RTS PC instruction (or
a FORTRAN RETURN statement) •

21-15

LABORATORY PERIPHERAL ACCELERATOR DRIVER

FORTRAN completion
following:

routines

must

not

contain

any

•

Any I/O through the FORTRAN run-time system

•

Any use of virtual arrays

•

Any use of floating-point operations

•

Any errors, since error reporting is done through the
run-time system

•

Anything else that may change the FORTRAN impure area

the

FORTRAN

The delay from start event (DRll-K) until the first sample in
irate units.
A minimum delay of 150 microseconds is required
(not verified by the LPAll driver).
iunit
The DRll-K unit number.
are valid.

Default is unit number

Values

0-4

nchn
The number of channels. The LPAll-K treats each DRll-K
configuration as one channel. Default is one channel.

its

was

not

ind
Receives a success or failure code as follows:
1

indicates that the sweep was successfully initiated.

indicates an illegal argument
called prior to this call.

list,

-1 indicates a QIO directive failure.
code is placed in IOSB(l) in IBUF.

SETIBF

The

directive

error

NOTE
The nchn and ind parameters are not supported by
the K-series support routines. If compatibility
with K-series support routines is desired, these
last two parameters must be ignored.

21-16

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.3.1.8 FLT16: Convert Unsigned Integer to a Real Constant - The
FLT16 routine converts an unsigned 16-bit integer to a real constant
(REAL*4). It can be invoked as a subroutine or a function as follows:
CALL FLT16 (ival,val)

or
val=FLT16(ival[,val])
ival
An unsigned 16-bit integer.
val
The converted (REAL*4) value.

21.3.1.9 IBFSTS: Get Buffer Status - The
IBFSTS
information on buffers being used in a sweep.

routine

returns

The IBFSTS call is as follows:
CALL IBFSTS (ibuf ,istat)
ibuf
The 40-word array specified in the call that initiated a sweep.
is tat
An array with as many elements as there are buffers involved in
the sweep.
The maximum is 8.
IBFSTS fills each element in the
array with the status of the corresponding buffer. The possible
status codes are as follows:
+2

indicates that the buffer is in the device queue.
is, RLSBUF has been called for this buffer.

indicates that the buffer is in the user task queue.
That is, it is full of data (for input sweeps) or is
available to be filled (for output sweeps).

indicates that the status of the buffer is unknown.
That is, it is not the current buffer nor is it in
either the device or the user queue.

-1

indicates that the buffer is currently in use.

That

21.3.1.10 IGTBUF: Return Buffer Number - The IGTBUF routine returns
the number of the next buffer to use. This routine should be called
by user-task completion routines to determine which is the next buffer
to access.
It should not be used if an event flag was specified in
the sweep-initiating call; if an event flag was specified, use the
IWTBUF routine.

21-17

LABORATORY PERIPHERAL ACCELERATOR DRIVER
IGTBUF can be invoked as a subroutine or a function as follows:
CALL IGTBUF (ibuf ,ibufno)
or
ibufno=IGTBUF(ibuf[,ibufno])
ibuf
The 40-word array specified in the call that initiated a sweep.
ibufno
Receives the number of the next buffer to access.
buffer in the queue, ibufno contains -1.
On the return from a call to IGTBUF, the following
combinations of ibufno and IOSB contents:

If there is no

are

the

possible

ibufno

IOSB(l)

IOSB(2)

400(8)

(Word count)

Normal

{Word count)

complete.
Sweep
Buffer
terminated.
There may be
additional buffers in the
queue filled and ready for
processing.

-1

No
buffers
in
queue.
Request still active.

-1

No buffers in queue.
terminated.

-1

RSX-llM
LPAll-K
error code(lO) error code(8)

Explanation
buffer

complete.

Sweep

No
buffers
in
queue.
Sweep terminated due
to
error condition.
(Refer to
Section 21.3.3 for error
code summary.) Note that
the error is not returned
until there are no more
buffers in the user queue.

21.3.1.11 INXTBF: Set Next Buffer - The INXTBF routine alters the
normal buffer selection algorithm. It allows the user task to specify
the number of the next buffer to be filled or emptied.

INXTBF can be invoked as a subroutine or a function as follows:
CALL INXTBF (ibuf,ibufno(,ind])
or
ind=INXTBF(ibuf,ibufno(,ind]}

21-18

LABORATORY PERIPHERAL ACCELERATOR DRIVER
ibuf

The 40-word array specified in the call that initiated a sweep.
ibufno

The number of the next buffer the user wants filled
The buffer must already be in the device queue.

emptied.

ind

Receives an indication of the result of the operation:
0

indicates that the specified buffer was not in
queue.

the

indicates that the next buffer was successfully set.

device

21.3.1.12 IWTBUF: Wait for Buffer - The IWTBUF routine allows a user
task to wait for the next buffer to fill or empty. It should be used
in conjunction with the specification of an event flag in the
sweep-initiating
call.
This routine should not be used if a
completion routine was specified in the call to initiate a sweep;
when event flags are specified, use the IGTBUF routine.
IWTBUF can be invoked as a subroutine or a function as follows:
CALL IWTBUF (ibuf,[iefn] ,ibufno)
or
ibufno=IWTBUF(ibuf,[iefn] ,[ibufno])
ibuf

The 40-word array specified in the call that initiated a sweep.
iefn

The event flag on which the task will wait. This should be the
same event flag as that specified in the sweep-initiating call.
If iefn equals 0 or default, event flag 30 is used.
ibufno

Receives the number of the next buffer to be filled or emptied by
the user task.

21-19

LABORATORY PERIPHERAL ACCELERATOR DRIVER
On the return from a call to IWTBUF, the following
combinations of ibufno and IOSB contents:

are

the

possible

Explanation

ibufno

IOSB(l)

IOSB(2)

400(8)

(word count)

Normal

(word count)

Buffer complete.
Sweep
terminated.
There may be
additional buffers in the
queue filled and ready for
processing.

-1

RSX-llM
LPAll-K
error code(lO) error code(8)

buffer

No
buffers
in
Sweep terminated.

complete.

queue.

No
buffers
in
queue.
Sweep terminated due to
error condition.
(Refer
to Section
21.3.3
for
error code summary.) Note
that the error is
not
returned until there are
no more buffers in the
user queue.

21.3.1.13 LAMSKS: Set Masks Buffer - The LAMSKS routine initializes a
user buffer containing a LUN, a digital start mask and event mark
mask, and channel numbers for the two masks. The routine then assigns
the LUN.
Each DRll-K is considered to be one channel. Each channel
has both input and output capabilities.
LAMSKS must be called if digital input starting or event marking is to
be utilized, or if a LUN other than the default LUN 7 will be assigned
to LAO. LAMSKS must also be called if multiple LPAll-Ks are being
used.
If LAMSKS is to be called, it must be called prior to calling
SETIBF. Unlike SETIBF, LAMSKS does not have to be called before each
sweep initiation unless one or more parameters are to be changed.
The LAMSKS call is as follows:
CALL LAMSKS (lamskb, [lun], [iunit], [idsc], [iemc], [idsw],
[ iemw], [ind])
lamskb
A 4-word array.
lun
A logical unit number.

Default LUN is 7.

21-20

LABORATORY PERIPHERAL ACCELERATOR DRIVER
iunit

The physical unit number of the LPAll-K.
number is LAO.

Default

physical

unit

idsc

The digital start word channel.

Default is channel 0.

iemc

The event mark word channel.

Default is channel O.

The digital start word mask.
starting).

Default is O (disable digital input

idsw

iemw

The event mark word mask.

Default is 0 (disable event marking).

ind

Receives a success or failure code as follows:
1

indicates successful initialization.

indicates an illegal argument list.

-n indicates a LUN assignment failure.
error code.

the

directive

NOTE
If compatibility with K-series support routines
desired, ignore this parameter.
For a discussion of event marking and digital starting,
LPAll-K Laboratory Peripheral Accelerator User's Guide.

see

the

21.3.1.14 RLSBUF: Release Data Buffer - The RLSBUF routine declares
one or more buffers free for use by the interrupt service routine.
The RLSBUF routine must be called to release buffer(s) to the device
queue before the sweep is initiated. The device queue must always
contain at least one buffer to maintain
continuous
sampling.
Otherwise, buffer overrun occurs (see Section 21.4 for a discussion of
buffer management). Note that RLSBUF does not verify whether the
specified buffers are already in a queue.

21-21

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The RLSBUF call is as follows:
CALL RLSBUF (ibuf,[ind],n0[,nl. •. ,n7])

ibuf
The 40-word array specified in the call that initiated a sweep.
ind
Receives a success or failure code as follows:
0

indicates illegal buffer number specified, illegal number
of buffers specified, or a double buffer overrun has been
detected.

indicates buffer(s) successfully released.

nO,nl,etc.
The numbers (0-7) of the buffers to be released.
eight can be specified.

21.3.1.15 RMVBUF: Remove Buffer from Device Queue
tine removes a buffer from the device queue.

~The

maximum

RMVBUF

rou-

The RMVBUF call is as follows:
CALL RMVBUF (ibuf,n[,ind])
ibuf
The 40-word array specified in the call that initiated a sweep.
n

The number of the buffer to remove.
ind
Receives a success or failure code as follows:
0

indicates that the specified buffer was not in
queue.

indicates that the specified buffer was
queue.

removed

the

device

from

the

21.3.1.16 SETADC: Set Channel Information - The
SETADC
routine
establishes channel start and increment information for all sweeps.
The SET!BF routine must be called to initialize the 40-word array
(ibuf) before SETADC is called.

21-22

LABORATORY PERIPHERAL ACCELERATOR DRIVER
If, in the call to SETADC, nchn is 1 or inc is O, the single channel
bit will be set in the mode word of the start RDA when the sweep start
routine is called.
SETADC can be invoked as a subroutine or a function as follows:
CALL SETADC (ibuf, [iflag], [ichn], [nchn], [inc], [ind])
or
ind

ISTADC ( ibuf, [ i flag], [ ichn] , [nchn], [inc] , [ind])

ibuf
A 40-word array initialized by the SETIBF routine.
iflag
Ignored. It is included for compatibility with K-series
routines.

support

ichn
The first channel number. Default is O. If inc equals 0 (or
default), ichn is the address of a random channel list. A random
channel list is an array of n elements, where each element is a
channel number.
The final element must have bit 15 set to
indicate the end of the list.
nchn
The number of samples to be taken per sequence.
sample.

Default

one

inc
The channel increment. Default is 1. The user should specify an
increment of 2 for differential A/D input. If inc equals O, ichn
is an array of random channels to receive input.
ind
Receives a success or failure code as follows:
0

indicates an illegal channel number
called prior to the SETADC call.

indicates successful recording of channel
the sweep call.

SETIBF

was

not

information

for

21.3.1.17 SETIBF: Set Array for Buffered Sweep - The SETIBF routine
initializes an array required by buffered sweep routines. The SETIBF
routine must be called before every call to a buffered sweep routine.

21-23

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The SETIBF call is as follows:
CALL SETIBF (ibuf,[ind] ,[lamskb] ,buf0[,bufl ••• buf7])
ibuf
A 40-word array.
ind
Receives a success or failure code as follows:
0

indicates a parameter or buffer error.

indicates the array was successfully initialized.

lams kb
The name of a 4-word array.
This array allows the use of
multiple LPAll-Ks within the same program, since the LUN is
specified in the first word of the array.
Refer to the
description of the LAMSKS routine.
If compatibility with K-series software is desired, the default
(LUN 7) lamskb parameter should be used, and LUN 7 will be
assigned to LAO: in the task-build command file for the user
task.
bufO, etc.
The name of a buffer.
A maximum of eight buffers can be
specified.
Any buffer names in excess of eight are ignored. At
least two buffers must be specified to maintain continuous
sampling.
Each buffer specified in the call
ranging from 0 to 7.

SETIBF

assigned

number

The assignment of these numbers is based on the order in which buffer
names appear in the argument list.
The first buffer whose name
appears in the list is assigned number 0, the second is assigned
number 1, and so forth.
In all subsequent calls to other routines
involving the set of buffers specified in a call to SETIBF, these
numbers, rather than names, are used to refer to particular buffers.

21.3.1.18 STPSWP: Stop Sweep - The STPSWP routine stops a sweep
is in progress.
The STPSWP call is as follows:
CALL STPSWP ( ibuf [, iwhen], [ind])

21-24

that

LABORATORY PERIPHERAL ACCELERATOR DRIVER
ibuf

The 40-word array specified in the call that initiated a sweep.
iwhen

Specifies when to stop the sweep:
0

stops the sweep, immediately aborting the sweep.
This is
the default stop method.
The sweep will be stopped
asynchronously by the LPAll-K hardware.
When IOSB(l)
equals
1, the sweep has been stopped.
Call IWTBUF
continously after calling STPSWP until the sweep has
actually been stopped. When stopping (aborting) a sweep in
this manner, the data contents of the current data buffer
cannot be guaranteed.

+n {any positive value) stops the sweep at the end of the
current buffer. This is considered to be the normal means
for stopping a sweep.
-n (any negative value) is reserved.

(Do not use.)

ind

Receives a success or failure code as follows:
1

indicates that the sweep
indicated by iwhen).

will

indicates an illegal argument list.

stopped

-n is a directive error code indicating that
QIO failed.

(at

lhe

the

time

stop

sweep

21.3.1.19 XRATE: Compute Clock Rate and Preset - The XRATE
routine
allows the user task to compute a clock rate and preset. The clock
rate divided by the clock preset yields the desired dwell (intersample
interval).
NOTE
The XRATE routine can be used only on
systems
that
have
a
FORTRAN
or
BASIC-PLUS-2 compiler. This module is
not included with the other LPAll-K
support routines
in
object
module
format.
Rather, it is included in
source code format with the K-series
source modules in [45,10] on the system
disk.

21-25

LABORATORY PERIPHERAL ACCELERATOR DRIVER
XRATE can be invoked as a subroutine or a function as follows:
CALL XRATE (dwell,irate,iprset,iflag)
or
ad well

XRATE(dwell,irate,iprset,iflag)

dwell
The intersample time desired by the user.
in decimal seconds (REAL*4).

The time is

expressed

irate
Receives the computed clock rate as a value from 1 to 5.
iprset
Receives the clock preset.
iflag
Specifies whether the computation is
Clock B:
0

intended

for

Clock

indicates the computation is for Clock A.

nonzero indicates the computation is for Clock B.
adwell
The actual dwell rate for the clock based on the irate and iprset
parameters.

21.3.2

MACR0-11 Interface

The MACR0-11 interface to the LPAll-K consists of either the callable
routines described in Section 21.3.1 or a set of device-specific QIO
functions.

21.3.2.1 Accessing
Callable
LPAll-K Support Routines - MACR0-11
programmers access the LPAll-K support routines through either of two
techniques:
1.

The standard subroutine linkage mechanism
code

and

the

CALL

Special-purpose macros that generate
invoke a subroutine

argument

list

and

These techniques are described in the following subsections.

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.3.2.2 Standard Subroutine Linkage and CALL Op Code - LPAll-K
routines can be accessed through use of the standard subroutine
linkage mechanism and the CALL op code.
The format of this procedure
is:

arglist:

.PSECT
MOV
CALL

code
#arglist,R5
lsubr

;ARGUMENT ADDRESS TO RS
;CALL LPAll-K ROUTINE

• PSECT
.BYTE
.WORD

data
narg,O
addrl

;NUMBER OF ARGUMENTS
;FIRST ARGUMENT ADDRESS

.WORD

addrn

;LAST ARGUMENT ADDRESS

In this sample, the two PSECT directives are shown only to
indicate
the noncontiguity of the code and data portions of the linkage
mechanism. Within the argument list, any argument that is to be
defaulted must be represented by a -1 address (that is, 177777(8)).

21.3.2.3 Special-Purpose Macros - To facilitate
the
calling
of
LPAll-K support routines from a MACR0-11 program, two macros are
provided in file [45,lO]LABMAC.MAC.
These macros are:
1.

!NITS

CALLS

INITS is an initialization macro.
of the MACR0-11 source module.

It must be invoked at the beginning

CALLS invokes an LPAll-K support routine.
call is as follows:

The format

this

macro

CALLS lsubr,<argl, ••• ,argn>
lsubr
The name of an LPAll-K support routine.
argl, and so forth
Arguments to be formatted into an argument list and passed to the
routine.
Each argument can be either a symbolic name or a
constant (interpreted as a positive decimal number)
or can be
defaulted.

21-27

LABORATORY PERIPHERAL ACCELERATOR DRIVER
An example showing the use of these macros is as follows:

IBUF:
ISTAT:

.TITLE
• IDENT
• BLKW
.BLKW
IN ITS

EXAMPLE
/01.00/
40 •
5
INITIALIZATION

START:

FIND STATUS OF 5 SWEEP BUFFERS
BEING USED IN CURRENT SWEEP
CALLS

IBFSTS(IBUF,ISTAT)

.END

START

/l.3.2.4 Device-Specific QIO Functions - Table
21-2
lists
the
device-specific functions of the QIO system directive macro that are
available for the LPAll-K.
Programmers using these functions are
entirely responsible for buffer management (refer to Section 21.4) as
well as all other interfaces
(for example,
the request descriptor
array).
Little
(if any)
performance improvement over the use of
FORTRAN support routines can be expected by using QIOs.
Therefore, it
is recommended that routines described in Section 21.3.1 be used.
Table 21-2
Device-Specific QIO Functions for the LPAll-K
QIO Function

Purpose

IO.CLK

Start clock

IO. INI

Initialize LPAll-K

IO. LOD

Load ·microcode

IO. STA

Start data transfer

IO. STP

Stop request

21-28

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The MACR0-11 programmer must set up the appropriate Request Descriptor
Array
(RDA)
before the corresponding QIO request is issued.
In the
case of the IO.STA function (start data transfer), the RDA is set up
with buffer virtual addresses.
The LPAll-K driver address checks and
relocates these buffers, changing them from single-word to double-word
addresses.
The RDA is fully described
in the source code of the
driver.

21.3.2.5 IO.CLK - The
IO.CLK function writes an
image
into
the
LPAll-K real-time clock control
register and issues a clock star~
command.
The format of the QIO request is:
QIO$C IO.CLK, ••• ,<mode,ckcsr,preset>
mode
The mode.
ckcsr
The image to be written into
the clock control
register.
To
achieve the function of clock rate -1 (see Section 21.3.1.2) for
Clock A only, set a clock rate of O and set the Schmitt Trigger 1
Interrupt Enable bit in the Clock A Status Register.
preset
The clock preset.

21.3.2.6 IO.IN! - The IO.IN! function initializes the
LPAll-K.
The
task
issuing the QIO request must be privileged.
The format of the
request is as follows:
QIO$C IO.INI, ••• ,<irbuf,278.>
irbuf
A buffer containing an LPAll-K initialize RDA.
must be at least 278 (10) bytes.

The

buffer

size

21.3.2.7 IO.LOO - The IO.LOO function loads a buffer of LPAll-K
microcode.
The
issuing task must be privileged.
The
function
verifies that there are no active users for the LPAll-K and resets the
hardware.
It then loads and verifies the microcode, starts the
LPAll-K, and enables interrupts.
The function returns to the
issuing
task when the Ready Interrupt is posted.

21-29

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The format of the QIO request for the IO.LOO function is as follows:
QIO$C IO.LOD, ••• ,<mbuf,2048.>
mbuf
A buffer containing microcode to be loaded.
be 2048(10) bytes.

The buffer size must

21.3.2.8 IO.STA - The IO.STA function issues an LPAll-K data transfer
start command.
The format of the QIO request is:
QIO$C IO.STA, ••. ,<bufptr,40.>
bufptr
A pointer to a buffer containing an LPAll-K sample
The buffer size must be at least 40(10) bytes.

start

RDA.

indicates that an AST is to be generated
buffer (if an AST is specified).

for

every

indicates that an AST is to
exception conditions.

only

The subfunction codes defined for the IO.STA function are:
Bit 0

= 0

Bit 0

generated

for

21.3.2.9 IO.STP - The IO.STP function stops a data transfer request.
The
issuing task must be the same task that initiated the data
transfer.
The format of the QIO request is as follows:
QI0$C IO.STP, ••• ,<userid>
user id
The index number associated with the user whose request is to
stopped.

21.3.3

The I/O Status Block (IOSB)

Each active sweep must have its own I/O status block.
The I/O status
block
(IOSB)
is a 2-word array allocated in the user program.
It is
used to receive the status of a call to an LPAll-K support routine.
When a data sweep routine is called, the IOSB is always the first two
words of the 40-word array specified as the first argument of the
call.
The first word of the IOSB contains the status code, and the
second word contains the buffer size in words.

21-30

LABORATORY PERIPHERAL ACCELERATOR DRIVER
NOTE
The 2-word IOSB is not directly used by
the LPAll-K driver.
Instead, the driver
uses a
4-word
IOSB
for
internal
communications with support routines;
this
4-word
IOSB
is
completely
transparent to FORTRAN support routine
users.
However, when issuing QIOs,
it
is
the
4-word
IOSB that must be
referenced.
The first two words of the 4-word IOSB
function as a
2-word overall IOSB for
returning QIO completion status.
The
driver returns status such as sweep
done,
system
errors,
and
LPAll-K
hardware errors with this 2-word portion
of the IOSB ..
The remaining two words function as an
intermediate IOSB for passing status
information during the data
sweeps.
MACR0-11 programs using QIO calls always
receive the correct 2-word portion of
the IOSB in the AST generated by the
LPAll-K driver.
The codes that can appear in the first word of an I/O status block are
in ISA-compatible format
(with the exception of the I/O pending
condition).
Table 21-3 lists all
return codes
(except 351;
see
Section 21.5).
Table 21-3
Contents of First Word of IOSB
IOSB ( 1)

Meaning

FORTRAN

MACRO

IO.PND

Operation pending;

rs.sue

Successful completion

301

IE.BAD

Invalid arguments

302

IE.IFC

Invalid function code

303

IE.DNR

Device not ready (See Section 21. 7)

304

IE.VER

Unrecoverable
power-fail

305

IE.ULN

LUN not assigned to LPAll-K

I/O in progress

hardware

error

caused

(continued on next page)

21-31

LABORATORY PERIPHERAL ACCELERATOR DRIVER

Table 21-3
(Cont.)
Contents of First Word of IOSB
IOSB ( 1)

Meaning

FORTRAN

MACRO

306

IE.SPC

Illegal buffer specification

309

IE.DUN

Insufficient UM Rs available for request

3131

IE.DAO

Data overrun

3151

IE.ABO

Request
IOSB(2)

316

IIE.

3171

IEeRSU

Resource in use (load microcode only)

320

IE. BLK

Executive blocked driver waiting for UM Rs

323

IE. NOD

System dynamic memory exhausted

3591

IE. FHE

Fatal hardware error on device

366

IE. BCC

LPAll-K load microcode error

397

IE. IEF

Invalid event flag specified

PRI

terminated;

LPAll-K

status

Privilege violation

1. IOSB(2) contains an LPAll-K status code. Refer to the
User's Manual for explanation of status code.

21.4

code

LPAll-K

BUFFER MANAGEMENT

The management of buffers for data transfers by LPAll-K support
routines involves the use of two FIFO (First-In, First-Out) queues:
1.

The device queue (DVQ)

The user queue (USQ)

The device queue (DVQ) contains the numbers of all buffers that the
user task has released to the support routines in a call to RLSBUF.
The buffers represented by these numbers are ready to be filled with
data
(input sweeps) or to be emptied of data (output sweeps). Any
buffer specified in a call to INXTBF must already be in DVQ.
The user queue (USQ) contains the numbers of buffers available to the
user task.
For output sweeps, this queue contains the numbers of
buffers that have already been emptied by the driver.
For input
sweeps, the buffers represented by USQ are those which are filled with
data.
In both instances, the user task determines the next buffer to
use
(that is, it extracts the first element of USQ) by calling IGTBUF
or IWTBUF.

LABORATORY PERIPHERAL ACCELERATOR DRIVER
Both the DVQ and
USQ are
initialized to
-1 -- indicating
no
buffers -- when the user task calls the SETIBF routine.
The user task
must call RLSBUF before initiating any sweep,
since at least one
buffer must be present in DVQ for the first input or output to occur.
For input sweeps, it is recommended that the user task call RLSBUF,
specifying the numbers associated with all the buffers to be used in
the sweep.
For output sweeps,
the user task can specify two buffers
(for
continuous sweeps) in the call to RLSBUF.
The first action then taken
either in a completion routine or after a call to IWTBUF is to release
the next buffer.
However, note that this approach does not represent
true multiple buffering since data overrun occurs if the second buffer
is not released in time.
If a buffer overrun occurs, the LPAll-K normally aborts
the affected
sweep and
returns an appropriate error code.
However, the option of
having buffer overruns treated as nonfatal
error conditions can be
selected by specifying the appropriate mode argument in any of the
sweep calls.
Then, when a
buffer overrun occurs,
the
LPAll-K
automatically defaults to buffer 0 for its next data buffer.
In this
case, the following special considerations regarding buffer management
must be observed.
Call RLSBur before calling any of the sweep control calls.
However,
if buffer overruns are to be treated as nonfatal conditions, the task
should not specify buffer 0 in the initial call
to RLSBUF.
(It
is
assumed at the outset that buffer 0 is available for use in this
manner and, therefore, should not be released.)
Once a buffer overrun has occurred,- buffer O is used by the
LPAll-K
and placed on the user queue just like any other data buffer.
At this
point, buffer 0 is no longer available for buffer overruns.
The task
then removes buffer 0 from the user queue by IWTBUF or IGTBUF for
possible processing.
It is the task's
responsibility to
release
buffer 0 for future buffer overruns by specifying buffer 0 in a call
to RLSBUF.
Note that the task cannot determine that buffer overrun
occurred until it receives buffer 0 from IWTBUF or IGTBUF.
The LPAll-K always uses buffer 0 following a buffer overrun
if that
condition was specified as nonfatal.
Thus, when a second buffer
overrun occurs before buffer 0 has been processed and made available
for
that purpose, a condition called "double buffer overrun" occurs.
In this case, buffer 0 is not put on the user queue since the actual
contents of buffer 0 cannot be determined at this time, and buffer 0
may actually still be on that queue.
The double buffer overrun
condition is detected when the
task attempts to make buffer 0
available for future buffer overruns with the call
to RLSBUF.
Note
that this
is the
first time that the task is notified of the
condition.
If a double buffer overrun condition is detected during
the call
to RLSBUF,
the task must be notified of the condition
indicating that the previous processing of buffer 0 contents may have
been of no value (the LPAll-K probably changed the buffer's contents
while it was being processed).

21-33

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.5

LOADING THE LPA-11 MICROCODE

LAINIT is a privileged task that is used
to load all versions of
LPAll-K microcode.
When called, LAINIT issues an IO.LOO function in a
QIO request, followed -by IO.IN! and
IO.CLK function
requests.
The
IO.CLK function starts the clock with a default clock rate of 1 MHz.
During SYSGEN Phase 1, a command
file
is generated with LPAll-K
support selected
through operator response to SYSGEN questions.
During SYSGEN Phase 2, the command file builds LAINIT using additional
information obtained
through operator response to SYSGEN questions.
This information further defines the LPAll-Ks system environment and
characteristics for the specific user application.
Separate tasks are built during SYSGEN that
invoke LAINIT to load
appropriate LPAll-K microcode.
These tasks are named LAINn, where n
corresponds to unit number (starting with unit number 0)
for each
LPAll-K unit in the system.
Thus, LAINIT is never directly invoked by
the user.
SYSGEN automatically generates command lines in SYSVMR.CMD that will
install
LAINIT and LAINO;
LAINl and subsequent LPAll-K unit-numbered
tasks are not automatically included in the command file.
Thus,
the
user must install these tasks (if they are required) with VMR or MCR.
Once LAINIT and LAINn tasks have been installed, a particular version
of LPAll-K microcode for a specific unit can be loaded by running the
corresponding LAINn task.
For example:
>RUN LAIN2
executes LAIN2, loading microcode for LPAll-K unit 2.
When a power-fail recovery occurs, the LPAll-K driver terminates all
outstanding activity and
requests execution of initiating task(s)
(LAINn)
for
each unit.
This automatically provides
power-fail
recovery for the LPAll-K microprocessor, provided the LAINIT and LAINn
tasks are installed.
Note that when either
the RSX-llM system is
bootstrapped or the LPAll-K driver is loaded, a simulated power-fail
(resulting in driver power-fail recovery)
occurs,
loading microcode
for each LPAll-K unit.
In addition,
when the LPAll-K is brought
online on an RSX-llM-PLUS system, a simulated power-fail occurs.
If the request for the initiating task (LAINn)
fails or the loader
fails
to
load
the driver,
the
LPAll-K unit does not become
initialized.
Any further attempt to use the LPAll-K will
fail,
with
the device not ready (IE.DNR) code returned to the requesting task.
If there is no LPA-llK present at the default address,
LAINx
returns
error code 351 in IOSB(l).
This failure occurs if there is more than
one LPA-llK and the one at the default address is removed.
There must
always be an LPA-llK at the default address.

21-34

LABORATORY PERIPHERAL ACCELERATOR DRIVER
All versions of LAINn set the real-time clock frequency to lMHz by
default.
The UCB device characteristics word 4 (U.CW4) contains a
16-bit buffer preset value that controls the rate of ticks
(that is,
the rate at which the clock interrupts).
This value can be set
dynamically or during SYSGEN.
The quotient resulting when this value
is divided
into 1 MHz is the rate of ticks.
For example, if U.CW4
contains 2, the tick rate is 500kHZ.
The user can issue a Get LUN
Information system directive to examine the preset value and the MCR
SET /BUF command can be used to modify it while the system is running.
This modification will take effect the next time the LPAll-K is
reloaded with micro-code by LAINx.

21.6

UNLOADING THE DRIVER

In order to attain maximum LPAll-K performance, the LPAll-K driver is
designed to appear not busy to the RSX-llM/M-PLUS Executive. As a
result, the potential problem exists that any privileged user can
unload the driver while the LPAll-K is servicing other users.
Therefore, the user must first determine that the LPAll-K is not being
used prior to unloading the driver.

21.7

TIME-OUT OF THE LPAll-K

The error code IO.DNR means that the LPAll-K timed out while
processing a user request~
In dedicated mode, this condition can have
special meaning.
The LPAll-K driver (LADRV) disables the time-out countdown following
LPAll-K acknowledgement of the user-task request.
In all cases in
multirequest mode, and in most cases in dedicated mode,
this
acknowledgement is received almost immediately after the user-task
request is passed to the LPAll-K.
The only case when this is not true
is when the user task requests that a data sweep be started while in
dedicated mode.
In this case, the LPAll-K waits to transfer the first
256 words of data before acknowledging the sweep request.
If a task is sampling at extremely slow data rates in dedicated mode,
the time to transfer that first 256 words may exceed the time-out
count for the device.
This can be avoided by using the multirequest
mode.
If a task must use dedicated mode for high sampling rates, and the
start of the sweep will be delayed for an extended period of time, the
time-out count for the LPAll-K must be disabled.
(Refer to the note
in LADRV describing this time-out problem and showing where the
time-out can be safely disabled for sweep calls.)
NOTE
This
procedure
will
disable
the
detection of real
time-outs for sweep
calls in dedicated mode.

21-35

LABORATORY PERIPHERAL ACCELERATOR DRIVER
21.S

22-BIT ADDRESSING SUPPORT

The LPAll-K driver supports 22-bit addressing on systems having that
capability.
When the system employs 22-bit addressing, certain
restrictions are imposed. As a result, tasks written for use with
earlier LPAll-K driver versions may not run without user task
modifications. These restrictions are discussed in the remainder of
this section.
When the LPAll-K driver is executed on 22-bit systems, a certain
contiguity of user-task data structures must be established. The task
data transfer buffers and the IBUF array must be contiguous.
In
addition, the task random channel list (if present) and the last data
transfer buffer must be contiguous. Thus, the correct sequence for
user-task data is the IBUF array, followed by the task data transfer
buffers, followed by the task random channel list.
Failure to
structure the user-task data in this manner can result in illegal
buffer specification errors (IE.SPC) being returned or possible
corruption of task address space by data sweeps.
Since the LPAll-K user task can potentially request more buffer space
than there is UMR mapping space, a limit on the total number of UMRs
that can be used by the LPAll-K driver at any time must be specified.
This limit is specified during SYSGEN part 1, along with the interrupt
vector and CSR address for the LPAll-K.
If a task's UMR requirements will cause the total number of UMRs
currently in use by the LPAll-K to exceed the SYSGEN-specified limit,
the task will receive an Insufficient UMRs Available For Request
(IE.DUN) error code in IOSB(l} of the IBUF array.
This condition can be avoided by setting the UMR limit to the expected
minimum number required for smooth LPAll-K operation for all expected
users. Since each UMR maps SK bytes, each user's requirements can be
calculated as follows:
•

Each IBUF array requires 76(10) bytes of UMR mapping.

•

Add this result to the byte length of all
transfer buffers to be used in the sweep.

•

Add this result to the byte length of the random channel
(if it exists).

•

The number of UMRs the user task needs is the total byte count
divided by Sl92 (SK) and rounded up to the next 8K (if not an
exact multiple of Sl92}.

the

contiguous
list

Because there are only 31 UMRs available for the entire system, it is
not
desirable
to
allow
the
LPAll-K
driver
(through
the
SYSGEN-specified limit) to have_ access to all or nearly all UMRs at
any given time.
Since other device drivers may also require UMR
mapping, the total allocation of UMRs by LADRV can slowly choke a
system, and for that reason allocation of UMRs must be carefully
considered.

21-3~

LABORATORY PERIPHERAL ACCELERATOR DRIVER
The UMR allocation limit for the LPAll-K can be changed by directly
modifying the value in the
LPAll-K's UCB word U.LAUB;
it is not
necessary to do another SYSGEN.
Use the OPEN command to access and
change the limit to the new value.
Possible values can range from
0-31.
Then, make the required change,
UNLOAD,
and
then
LOAD the
LPAll-K driver.
If the
LPAll-K driver
is resident, the value in
U.LAUB+2 must also be changed to the new value.
NOTE
Be sure the
LPAll-K is idle
attempting to access the UCB.

before

It is possible for a condition to exist where there may not be enough
UMRs available for the Executive to allocate to the driver at the time
the request is made, even if the number of UMRs necessary to map the
user task's request are within the SYSGEN-defined limit. When this
happens, the Executive blocks the driver until its UMR request can be
granted.
Since this condition can introduce sweep timing errors, the
current sweep is unconditionally aborted and an appropriate error code
(IE.BLK) is returned to the task in IOSB(l).

SAMPLE PROGRAMS

21.9

LPAll-K SAMPLE PROGRAM

C SAMPLE SHOWS THE BASIC FLOW FOR PROGRAMMING THE LPAll-K IN A HIGHER
C LEVEL LANGUAGE.
IT IS EXPECTED THE USER WILL TEST IOSB RETURNS AND
C ERROR INDICATORS (IND) AS NECESSARY.
SYNCHRONOUS PROGRAM TERMINATION
C IS SUGGESTED. NOTE: THIS SAMPLE PROGRAM WILL NOT EXECUTE CORRECTLY IN
C 22-BIT MODE

c
C

D/A DEDICATED MODE WITH CONTINUOUS SAMPLING

c
C
C
C
C
C

PROGRAM RUNS 3 LOOPS (BASED ON NCNT).
ON FIRST LOOP,
STOPS SYNCHRONOUSLY AT END OF PRESENT BUFFER WHICH HAPPENS
TO BE BUFFER #3 BEING FILLED FOR THE 2ND TIME.
THE 2ND LOOP TERMINATES ASYNCHRONOUSLY (IWHEN=O).
THE 3RD LOOP TERMINATES ASYNCHRONOUSLY ALSO.

c
c

DIMENSION IBUF(40) ,IOSB(2) ,NB(l024,8)
EQUIVALENCE (IBUF(l) ,IOSB(l))
EQUIVALENCE (NO,NB(l,l)) '(Nl,NB(l,2)) I (N2,NB(l,3)) '(N3,NB(l,4))
EQUIVALENCE (N4,NB(l,5)), (N5,NB(l,6)), (N6,NB(l,7)), (N7,NB(l,8))
CALL CLOCKA (4,-1)
IWHEN=l
NCNT=O
ICNT=l
CALL SETIBF(IBUF,IND,,NO,Nl,N2,N3)

C INITIALIZE BUFFERS TO ALL -2'S

('\
.LV

DO 10 J=l,8
DO 10 K=l,1024
NB(K,J)=-2
CALL RLSBUF(IBUF,IND,1,2,3)
CALL DASWP(IBUF,1024,,,,20)
CALL IWTBUF(IBUF,20,IBUFNO)
CALL RLSBUF (IBUF,IND,IBUFNO)
WRITE (1,300) IBUFNO,IOSB(l) ,IOSB(2) ,ICNT
IF (NCNT.EQ.3) GOTO 40
21-37

LABORATORY PERIPHERAL ACCELERATOR DRIVER

40
300

IF (ICNT.EQ.n) GOTO 2
ICNT=ICNT+l
IF (ICNT.NE.4) GOTO 20
CALL STPSWP (IBUF,IBUFNO)
IWHEN=O
NCNT=NCNT+l
GOTO 20
CALL IGTBUF(IBUF,IBUFNO)
WRITE ( 1 , 3 0 0 ) IB UF N0 , IO SB ( 1 ) , IO SB ( 2 ) , IC NT
FORMAT (3X,Il0,208,Il0)
STOP
END

The following sample program will test the digital I/O
the LPAll-K. It will execute correctly in 22-bit mode.

interface

c
C PROGRAM TO TEST DIGITAL INPUT AND OUTPUT FOR LPAll-K
C DIGITAL EQUIPMENT CORPORATION

c
C THIS PROGRAM IS DESIGNED TO OUTPUT A DATA BUFFER TO THE LPAll-K
C DIGITAL I/O INTERFACE AND AT THE SAME INSTANT FOR EACH SAMPLE
C WORD READ THE RESULTS BACK. THE DATA BUFFERS ARE COMPARED TO
C MAKE SURE THE TRANSFER IS COMPLETED SUCCESSFULLY.

C ****** NOTE! ******
C
THIS PROGRAM WILL WORK IF AND ONLY IF THE DIGITAL I/O
MODULE
C
UNIT SPECIFIED HAS THE MAINTENANCE JUMPER "WRAP-AROUND"
CABLE
C
INSTALLED!!!!

C RESERVE STORAGE FOR LPAll-K ROUTINES

c
C

THIS PROGRAM WILL WORK IN 22-BIT MODE

c
C DATA BUFFERS

INTEGER*2 IBUFI(40) ,INBUF(300,4)
INTEGER*2 COMMI(l240)
EQUIVALENCE(IBUFI(l) ,COMMI(l))
EQUIVALENCE(INBUF(l,l) ,COMMI(41))
INTEGER*2 IBUF0(40) ,OUTBUF(300,4)
INTEGER*2 COMMO(l240)
EQUIVALENCE(IBUFO{l) ,COMMO(l))
EQUIVALENCE(OUTBUF(l,l) ,COMM0(41))
C RESERVE STORAGE AND EQUIVALENCE FOR RSX I/O STATUS BLOCKS
LOGICAL*l INIOS(4) ,OUTIOS(4)
EQUIVALENCE ( IBUFO ( 1) , OUTIOS ( 1)) , ( IBUFI ( 1) , INIOS ( 1))

c
C SET BUFFER SIZE TO USE FOR THIS REQUEST - MAXIMUM OF 300
WITHOUT
C CHANGING THE DIMENSION STATEMENTS. MUST BE EVEN!
ISIZE=300

C INITIALIZE THE PASS COUNTER FOR THE LOOP
IPASS=l

C SET LPAll-K LOGICAL UNIT NUMBER AND ASSIGN IT TO LAO:
ILUN=7
CALL ASSIGN(ILUN,'LA:' ,O,ISTAT)
IF(ISTAT .LT. O)GO TO 100

21-38

LABORATORY PERIPHERAL ACCELERATOR DRIVER
C INITIALIZE THE OUTPUT DATA BUFFER
DO 2 J=l,4
DO 2 I=l,ISIZE,2
OUTBUF(I,J)="l25252
OUTBUF(I+l,J)="052525
2
CONTINUE

c
C STOP LPAll-K REAL TIME CLOCK "A" THIS WILL MAKE SURE THAT
C NOTHING HAPPENS WHEN WE INITIALIZE THE TWO SWEEPS.
5
CALL CLOCKA(O,O,ISTAT,ILUN)
IF(ISTAT .NE. l)GO TO 110

C INITIALIZE THE INPUT DATA BUFFER. ASSUME THE LPAll-K DIGITAL
C I/O INTERFACE IS CONFIGURED IN THE DATA LATCH MODE (AS OPPOSED
C TO SENSE). THUS THE OUTPUT DATA BUFFER MUST CONTAIN A BIT
CHANGE
C FOR EVERY BIT POSITION IN SUCCEEDING DATA WORDS.
DO 10 J=l,4
DO 10 I=l,ISIZE
INBUF(I,J)=O
10
CONTINUE

C INITIALIZE DIGITAL OUTPUT SWEEP.
THIS MUST BE DONE BEFORE INIT
C OF DIGITAL INPUT SWEEP! THE LPAll-K PROCESSES THE TRANSFER OF
C DATA IN THE ORDER OF THE SPECIFICATION OF THE SWEEPS.
THUS WE
C WANT TO OUTPUT BEFORE WE INPUT.
CALL
SETIBF(IBUFO,ISTAT,,OUTBUF(l,l) ,OUTBUF(l,2) ,OUTBUF(l,3) I
1
OUTBUF(l,4))
IF(ISTAT .NE. l)GO TO 120

c
C RELEASE BUFFER FOR OUTPUT SWEEP
C ALL FOUR BUFFERS -- INDEXES 0,1,2,3
ARE RELEASED
CALL RLSBUF(IBUFO,ISTAT,0,1,2,3}
IF(ISTAT .NE. l)GO TO 130

C "START" DIGITAL OUTPUT SWEEP. REMEMBER NOTHING WILL HAPPEN
UNTIL
C WE START THE REAL TIME CLOCK. THE LPAll-K WILL PROCESS THE
REQUEST
C AND BE ALREADY TO TRANSFER DATA WHEN WE RESUME THE CLOCK.
C EVENT FLAG 14 IS SPECIFIED. A DIFFERENT EVENT FLAG MUST BE
C SPECIFIED FOR THE DIGITAL INPUT SWEEP SO THE FORTRAN PROGRAM
C CAN SYNCHRONIZE WITH TWO INDEPENDENT, ASYNCHRONOUS PROCESSES.
CALL DOSWP(IBUFO,ISIZE,4,0,1,14,30,0)

c
c

C NOW INITIALIZE FOR DIGITAL INPUT SWEEP.
THE SAMPLING
PARAMETERS
C MUST BE THE SAME FOR BOTH THE INPUT AND OUTPUT SWEEP. WE WANT
C TO WRITE AND READ THE SAME DATA WORD AT THE SAME TIME.
CALL
SETIBF(IBUFI,ISTAT,,INBUF(l,l) ,INBUF(l,2) ,INBUF(l,3),
1
INBUF(l,4))
IF(ISTAT .NE. l)GO TO 140

C RELEASE THE INPUT BUFFERS
CALL RLSBUF(IBUFI,ISTAT,0,1,2,3)
IF(ISTAT .NE. l)GO TO 150

C "START DIGITAL OUTPUT SWEEP. AGAIN, NOTHING WILL HAPPEN UNTIL
C WE RESUME THE LPAll-K REAL TIME CLOCK.
C EVENT FLAG 15 IS SPECIFIED TO SEPARATE THE INPUT AND OUTPUT
SWEEPS.
CALL DISWP(IBUFI,ISIZE,4,0,1,15,30,0)

21-39

LABORATORY PERIPHERAL ACCELERATOR DRIVER
C NOW FOR THE BIG EVENT! WE START THE CLOCK AND SEE WHAT HAPPENS.
CALL CLOCKA(l,-150,ISTAT,ILUN)
IF(ISTAT .NE. l)GO TO 150

c
c

C THE LPAll-K SHOULD NOW BEGIN TO TRANSFER DATA
C FIRST WE WAIT FOR THE DIGITAL OUTPUT SWEEP TO FINISH.
IT WAS
C STARTED FIRST AND SHOULD FINISH FIRST. WE VERIFY THAT IT
C FINISHES CORRECTLY OR CHECK FOR ERRORS.
15
CALL IWTBUF(IBUF0,14,IBUFNO)

c
C IF BUFFER NUMBER IS -1, THEN ERROR
C IF BUFFER NUMBER IS 0,1, OR 2, THEN CONTINUE
C IF BUFFER NUMBER IS 3, THEN FINISHED
IF(IBUFNO .LT. 0) GO TO 160

C NOW WAIT FOR THE DIGITAL INPUT SWEEP TO FINISH.
C CONDITIONS APPLY.
CALL IWTBUF(IBUFI,15,IBUFNO)
IF(IBUFNO .LT. O)GO TO 170
IF(IBUFNO .LE. 2}GO TO 15

THE SAME ERROR

C THE FACT THAT WE HAVE GOTTEN HERE SAYS THE LPAll-K HAS DONE ITS
C THING.
C CHECK THE INPUT DATA BUFFERS AGAINST THE OUTPUT DATA BUFFERS
DO 20 J=l,4
DO 20 I=l, ISIZE
IF(INBUF(I,J) .NE. OUTBUF(I,J))GO TO 180
20
CONTINUE

c
C SUCCESSFUL COMPLETION, LET EVERYONE KNOW. THEN GO BACK AND DO
IT
C AGAIN.
WRITE(5,1000)IPASS
1000
FORMAT('
REQUEST COMPLETE!' ,2X,I6)
IPASS=IPASS+l
GO TO 5

c
C REPORT ANY ERRORS THAT HAVE BEEN UNCOVERED IN THE EXAMPLE.

c
100
1010
110
1020

120
1030
130

1040
140
1050
150
1060
160
1070

WRITE(5,1010)ISTAT
I , I 6)
FORMAT(//,' ERROR ASSIGNING LUN TO LPAll-K
CALL EXIT
WRITE(5,1020)ISTAT
FORMAT(//,' ERROR STOPPING LPAll-K CLOCKA
I 'I 6)
CALL EXIT
WRITE(5,1030)ISTAT
I , I 6)
FORMAT(//,' ERROR FROM SETIBF - OUTPUT BUFFER
CALL EXIT
WRITE(5,1040)ISTAT
I , I 6)
FORMAT(//,' ERROR FROM RLSBUF - OUTPUT BUFFER
CALL EXIT
WRITE(5,1050)ISTAT
I , I 6)
FORMAT(//,' ERROR FROM SETIBF - INPUT BUFFER
CALL EXIT
WRITE(5,1060)ISTAT
I , I 6)
FORMAT(//,' ERROR FROM RLSBUF - INPUT BUFFER
CALL EXIT
WRITE(5,1070)IBUFNO,(OUTIOS(I} ,I=l,4)
FORMAT(//,' ERROR FROM DOSWP
',I2,4(3X,04))

C *** WARNING

170
1080

*** DISWP MIGHT STILL BE ACTIVE WHEN YOU EXIT

CALL EXIT
WRITE ( 5 , 108 0 ) IB UF N0 , ( IN IO S ( I ) , I= 1 , 4 )
FORMAT(//,' ERROR FROM DISWP
',I2,4(3X,04))
21-40

LABORATORY PERIPHERAL ACCELERATOR DRIVER

c
C *** WARNING *** DOSWP MIGHT STILL BE ACTIVE WHEN YOU EXIT

180
1090

CALL EXIT
WRITE(5,1090)I,J,OUTBUF(I,J) ,INBUF(I,J)
FORMAT(//,' *DATA ERROR* - WORD# ',I4,2X,I4,4X,06,2X,06)
CALL EXIT
END

21-41

CHAPTER 22
K-SERIES PERIPHERAL SUPPORT ROUTINES

22.l

INTRODUCTION

K-series laboratory peripheral modules are supported through a set of
program-callable routines that are linked with the user's task at
task-build time. These routines are highly modular.
Therefore, a
particular task contains only that code necessary for the facilities
actually used. Additionally, the support routines perform input and
output operations through the Connect to Interrupt Vector (CINT$)
Executive directive. This directive allows the user's task to bypass
normal QIO processing and perform I/O almost completely independent of
the Executive.
The following subsections briefly describe the K-series laboratory
peripherals, the features provided by the K-series support routines,
and the generation and use of these routines.

22.1.1

K-Series Laboratory Peripherals

The K-series peripheral support
routines
provide
single-user,
task-level support for the following laboratory peripheral modules:

• AAll-K D/A converter
• ADll-K A/D converter
• AMll-K multiple gain multiplexer
• DRll-K digital I/O interface
• KWll-K dual programmable real-time clock
• AAVll-A D/A converter (LSI-11-bus-compatible)
• ADVll-A A/D converter (LSI-11-bus-compatible)
• DRVll parallel line unit (LSI-11-bus-compatible)
• KWVll-A programmable real-time clock (LSI-11-bus-compatible)

22-1

K-SERIES PERIPHERAL SUPPORT ROUTINES
The maximum supported hardware configuration consists of one KWll-K
and sixteen of each of the AAll-K, ADll-K (with optional AMll-K), and
DRll-K modules.
The minimum configuration, if synchronous sweeps are
desired, would be one KWll-K and any one of the three other modules.
A single DRll-K supports nonclocked, interrupt-driven I/O sweeps or
single digital input or output. A single ADll-K supports single-word
A/D input and nonclocked, overflow-driven sampling (provided that the
A/D conversion is started with the EXT start input on the ADll-K). An
AAll-K supports burst mode output and scope control.

22.1.1.1 AAll-K D/A Converter - The AAll-K includes
four
12-bit
digital-to-analog converters (DACs) and an associated display control.
The display control permits the user to display data in the form of a
4096 x 4096 dot array.
Under program control, a dot may be produced
at any point in this array, and a series of these dots may be
programmed sequentially to produce graphical output.
The display
control may output to chart or X/Y recorder or CRT display unit.
The AAVll-A is
an
LSI-ii-bus-compatible
D/A
characteristics similar to those of the AAll-K.

converter

with

22.1.1.2 ADll-K A/D Converter - The ADll-K is a
12-bit successive
approximation converter that enables the user to sample analog data at
specified rates and to store the equivalent digital value for
subsequent processing.
The basic subsystem consists of an input
multiplexer
(switch-selectable between 16-channel single-ended or
8-channel differential), sample-and-hold circuitry, and a 12-bit A/D
converter.
By changing jumpers, the analog inputs can be made bipolar
or unipolar.
The ADVll-A is
an
LSI-11-bus-compatible
D/A
characteristics similar to those of the ADll-K.

converter

with

22.1.1.3 AMll-K Multiple Gain Multiplexer - The
AMll-K
is
a
multiplexer expander that supplements the 16-channel single-ended (8
differential) analog input multiplexer in the ADll-K.
The expansion
is done in three independent groups on the AMll-K.
Each group can be
set to 16 single-ended or pseudo-differential or 8 differential
input
channels;
each group can have a gain of 1, 4, 16, or 64 assigned to
it by a switch in the amplifier.

22.1.1.4 DRll-K Digital I/O Interface - The
DRll-K
is
a
general-purpose digital input/output interface capable of the parallel
transfer of up to 16 bits of data, under program control, between a
PDP-11 UNIBUS computer and an external device (or another DRll-K).
The DRVll is an LSI-11-bus-compatible, general-purpose input/output
interface with characteristics similar to those of the DRll-K~

22-2

K-SERIES PERIPHERAL SUPPORT ROUTINES

22.1.1.5 KWll-K Dual Programmable Real-Time Clock - The KWll-K is a
dual programmable real-time clock option used in PDP-11 UNIBUS
computers. Features include:
Clock A
•

16-bit counter

•

16-bit programmable preset/buffer register

•

Four modes of operation

•

Two external inputs (Schmitt triggers)

•

Eight clock rates, program selectable

•

Five clock frequencies, crystal controlled for accuracy

•

Processor actions synchronized to external events

Clock B
•

8-bit counter

•

8-bit programmable preset register

•

Repeated interval mode of operation

•

One external input (Schmitt trigger)

•

Seven clock rates, program selectable

•

Five clock frequencies, crystal controlled for accuracy

The KWVll-A is an LSI-11-bus-compatible
real-time
characteristics similar to those of the KWll-K.

22.1.2

clock

with

provide

the

Support Routine Features

The RSX-llM program-callable K-series
following features:

support

routines

• Clock overflow or trigger-driven A/D sweep
• Clock overflow or interrupt-driven digital input sweep
• Clock overflow or interrupt-driven digital output sweep
• Clock overflow or burst mode D/A sweep
• Single digital input
• Single digital output
• Single A/D input

22-3

K-SERIES PERIPHERAL SUPPORT ROUTINES
•

Scope control

•

Histogram sampling

•

Schmitt Trigger simulation

•

Clock control

•

16-bit software clock

•

A/D input to real number conversion

•

Buffer control

Immediate digital input or output can be performed at any time.
Multiple clock-driven sweeps can be initiated if this optional feature
was selected during the K-series generation dialog
(see Section
22.1.3.1).
Such sweeps, however, are subject to the following
restrictions:
1.

Regardless of the number of controllers present, there can be
only one active A/D sweep at any point in time.
The same
restriction holds true for D/A sweeps.
It is possible,
however,
to perform digital input and digital output sweeps
simultaneously, using the same DRll-K, so long as this
feature is selected during the generation dialog.

There can be no conflict in clock rates among the sweeps.

Only the first sweep can use the delay from start event.

The interevent time data-gathering routine
parallel with any other clock-driven sweeps.

22.1.3

cannot

run

Generation and Use of K-Series Routines

To use K-series support routines, the user must do the following three
things during SYSGEN:
•

Reserve necessary vector space.

•

Specify that the CINT$ Executive directive is to
in the system.

•

Specify that AST support is required.

At a point in time subsequent to SYSGEN, the user
procedures for the following:
1.

Generation of K-series support routines

Program use of K-series routines

follows

included

particular

These two procedures are detailed in the following subsections.

22-4

K-SERIES PERIPHERAL SUPPORT ROUTINES
22.1.3.1 Generation of K-series Support Routines - An indirect command file,
similar to those used for
SYSGEN itself, is used to
generate the K-series support routine library and other necessary
facilities.
This command file is invoked by typing the following:
>@[200,200]SGNKLAB
The dialog
initiated by this
command
determines
.the
device
configuration of the subsystem,
the maximum number of buffers that
will be used on a per-sweep basis, and the inclusion or omission of
optional features such as multiple clock-driven sweeps and duplex
digital I/O sweeps.
After this information has been obtained, the command file creates the

following:
1.

A prefix file, [45,lO]KPRE.MAC, for use
K-series support routines.

A data base file, [45,lO]KIODT.MAC, containing control blocks
needed to support the devices.

A common block file, [45,lO]KCOM.MAC, that allows user tasks
to access the
I/O page.
This file is used only on mapped
systems.

On mapped systems only, two indirect command files:
a.

[45,24]KCOMBLD.CMD, which is a TKB
common block

[l,54]INSKCOM.CMD that is
block

used

during

build

assembly

file

install

the

for

the

common

At the user's option, the K-series routines themselves can then be
assembled and an object library created.
The user can specify the
name of this library or accept
the
following
default
file
specification:
LB: [l,l]KLABLIB.OLB

22.1.3.2 Program Use of K-series Routines - The steps required
routine program use of K-series support routines are as follows:
1.

Compile or assemble the program.
If
overlaid,
it is required that both the
K-series support routines and the support
reside in the root section of the overlay

22-5

for

the task will be
buffers used by the
routines themselves
structure.

K-SERIES PERIPHERAL SUPPORT ROUTINES
2.

Invoke TKB:
a.

On mapped systems only, use the IPR:O switch to
that the task is privileged.

Include the following
indirect
responses to the TKB prompt:

command

indicate

among

the

TKB>@[l,5x]LNK2KLAB
where x is 0
systems.
c.

for

unmapped

systems

and

for

On mapped systems only, enter the following
command in response to the prompt for options:

mapped
indirect

ENTER OPTIONS
@[l,54]LNK2KCOM

II
3.

On mapped systems only, enter the following indirect command
from a privileged terminal before executing the program:
>@[l,54]INSKCOM

The following is a complete example of the steps previously described:
>F4P KTEST,KTESTl-SP=KTEST
>TKB
TKB>KTESTIPR:O,KTESTl-SP=KTEST,[l,l]F4POTSILB
TKB>@[l,54]LNK2KLAB
TKB>I
ENTER OPTIONS
TKB>@[l,54]LNK2KCOM

TBK>//

22.2

THE PROGRAM INTERFACE

A collection of program-callable subroutines provides access to the
K-series laboratory peripherals.
The formats of these calls are fully
documented here for FORTRAN programs.
MACR0-11 programmers access
these same subroutines either through the standard subroutine linkage
or through the use of two special-purpose macros.
Both techniques are
described
in Section 22.2.2.
Both FORTRAN and MACRO programs must
contain at least one IIO Status Block
(IOSB), described
in Section
22.2.3, for retrieval of status information.

22-6

K-SERIES PERIPHERAL SUPPORT ROUTINES
22.2.1

FORTRAN Interface

Table 22-1 lists the FORTRAN interface
K-series laboratory peripherals.

subroutines

for

accessing

Table 22-1
FORTRAN Subroutines for K-series Laboratory Peripherals
Function

Subroutine

ADINP

Initiate single analog input

ADS WP

Initiate synchronous A/D sweep

CLOCKA

Set Clock A rate

CLOCKB

Control Clock B

CVADF

Convert A/D input to floating point

DASWP

Initiate synchronous D/A sweep

DIGO

Digital start event

DINP

Digital input

DISWP

Initiate synchronous digital input sweep

DOSWP

Initiate synchronous digital output sweep

DOUT

Digital output

FLT16

Convert unsigned integer to a real constant

GTHIST

Gather interevent time data

IBFSTS

Get buff er status

ICLOKB

Read 16-bit clock

IGTBUF

Return buff er number

INXTBF

Set next buffer

IWTBUF

Wait for buffer

RCLOKB

Read 16-bit clock

RLSBUF

Release data buff er

RMVBUF

Remove buffer from device queue

SCOPE

Control scope

SET ADC

Set channel information

SETI BF

Set array for buffered sweep

STPSWP

Stop sweep

XRATE

Compute clock rate and preset

22-7

K-SERIES PERIPHERAL SUPPORT ROUTINES
The calling sequences of the routines listed
in Table 22-1 are
compatible with the routines for the LPA-11, described in Chapter 21.
The following subsections briefly describe the function and format of
each FORTRAN subroutine call. ·

22.2.1.1 ADINP: Initiate Single Analog Input - The
ADINP
obtains a single word as input from the A/D converter.

routine

ADINP can be invoked as a subroutine or a function as follows:
CALL ADINP ( ( i flag] , [ ichan] , i val)
or
ival=IADINP ( (iflag], [ichan], (ival])
iflag
The gain options:
0

Absolute channel addressing (default).
mode supported on the ADVll (Q-bus).

This is the only

Sample at a gain of 1.
In modes 1, 2, 3, 4, and 5 each
ADll-K/AMll-K is treated as 16 channels with channels
17-63 strapped to gains 4,
ln,
and 64.
The
48
multiplexer
channels are selected by the software
according to the gain specification. Mode values 1,
2,
3,
4,
and 5 are not supported on the ADVll (Q-bus
version) •

Sample at a gain of 4.

Sample at a gain of 16.

Sample at a gain of 64.

Perform auto gain ranging.

ichan
Selects the channel to be sampled.

The default is O.

ival
Receives the sample.
nonzero.

The gain bits will be inserted if iflag

22.2.1.2 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP
routine
initiates a
synchronous A/D input sweep through an ADll-K (and, if
present, the AMll-K).
The analog input word placed in the user buffer
consists of the 12 bits read from the A/D converter and (except when
the mode parameter equals 0) the 2 gain bits read from the A/D status
register.
A value of 177776(8) is returned for A/D time-out.
A value
of 177777(8) is returned on an A/D conversion error.
Such errors are
typically caused by conversions occurring too fast.

22-8

K-SERIES PERIPHERAL SUPPORT ROUTINES
If differential input is desired, the channel increment must be set to
2 by calling the SETADC routine.
The default channel increment is 1
(single-ended input).
NOTE
This routine will expect to have the STl
OUT from the KWll-K or similar trigger
jumpered to EXT START on the ADll-K if
mode 512 is desired.
This also requires
the A EVENT OUT from the KWll-K clock
trigger jumpered to the KW overflow on
the ADll-K if clock driven sweeps are
desired.
The format of the ADSWP call is as follows:
CALL ADSWP (ibuf ,lbuf, [nbuf], [mode], [iprset], [iefn], [ldelay],
[ ichn] , [nchn])
ibuf
A 40-word array initialized by the SETIBF routine.
The first two
words of the array are the I/O status block (IOSB).
lbuf
The size in words of each data buffer.
All data buffers must
equal in size and lbuf must be greater than O.

nbuf
The number of buffers to be filled.
equal to O,
indefinite sampling
terminates indefinite sampling.

If nbuf is omitted or set
occurs.
The STPSWP routine

mode
Sampling options.
The default is O.
The mode bit values listed
below that are preceded by a plus sign (+) are independent and
can be ADDed or ORed together.
Those values not preceded by a
plus sign are mutually exclusive and only one such value can be
used at a time.
All bit values not listed below are reserved.
The following values can be specified:

Absolute channel addressing (default).
This mode allows
the user to directly access all 63 channels of an
ADll-K/AMll-K combination.
This is the only mode that
is LPA-11 compatible.

22-9

K-SERIES PERIPHERAL SUPPORT ROUTINES
1

Sample with a gain of 1. In modes 1, 2, 3, 4, and 5
each ADll-K/AMll-K is treated as 16 channels with
channels 17-63 strapped to gains 4, 16, and 64. The 48
multiplexer
channels are selected by the software
according to the gain specification. Mode values 1, 2,
3,
4, and 5 are not supported on the ADVll (Q-bus
version).

Gain of 4.