Digital PDFs

AA-H269A-TC

May 1979

510 pages

Original

21MB

Document:	RSX-11M/M-PLUS I/0 Drivers Reference Manual
Order Number:	AA-H269A-TC
Revision:	0
Pages:	510
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/5A_FileMgmt_IO/AA-H269A-TC_RSX-11M_IO_Drivers_Ref_Man_197905.pdf

OCR Text

RSX-11 M/M-PLUS
1/0 Drivers
Reference Manual
Order No. AA-H269A-TC

RSX-11M Version 3.2
RSX-11M-PLUS Version 1.0

r-:;::rder additional copies of this document, contact the Software Distribution
L.:::er, Digital Equipment Corporation, Maynard, Massachusetts 01754

digitcll equipment corporation · maynard, massachusetts

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

1979 by Digital Equipment Company

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

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATATRIEVE

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

7/80-14

MAS SB US
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

CONTENTS
Page
SUMMARY OF TECHNICAL CHANGES

xx iii

PREFACE

xxv

CHAPTER

RSX-llM/M-PLUS INPUT/OUTPUT

1-1

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

OVERVIEW OF RSX-llM I/O
PHYSICAL, LOGICAL, AND VIRTUAL I/O
RSX-llM DEVICES
LOGICAL UNITS
Logical Unit Number
Logical Unit Table
Changing LUN Assignments
ISSUING AN I/O 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
The .MCALL Directive: Retrieving System
Macros
The ALUN$ Macro: Assigning a LUN
Physical Device Names
Pseudo-Device Names
The GLUN$ Macro: Retrieving LUN
Information
The ASTX$S Macro: Terminating AST Service
The WTSE$ Macro: Waiting for an Event Flag
STANDARD I/O FUNCTIONS
IO.ATT: Attaching to an I/O Device
IO.DET: Detaching from an I/O Device
IO.KIL: Canceling I/O Requests
IO.RLB: Reading a Logical Block
IO.RVB: Reading a Virtual Block
IO.WLB: Writing a Logical Block
IO.WVB: Writing a Virtual Block
I/O COMPLETION
RETURN CODES
Directive Conditions
I/O Status Conditions
POWERFAIL RECOVERY PROCEDURES FOR DISKS
AND DECTAPE

1-1
1-2
1-2
1-5
1-5
1-6
1-6
1-7
1-8
1-ll
1-ll
1-12
1-13
1-15

1. 7. 3
1. 7. 4
1. 7. 5
1.7.5.1
1.7.5.2
1. 7. 6
1. 7. 7
1. 7. 8
1. 8
1. 8 .1
1. 8. 2
1. 8. 3
1. 8. 4
1. 8. 5
1. 8. 6
1. 8. 7
1. 9
1.10
1.10 .1
1. 10. 2
1.11

CHAPTER

1-15
1-15
1-15
1-16
1-17
1-19
1-20
1-22
1-23
1-24
1-24
1-25
1-25
1-26
1-26
1-27
1-27
1-28
1-·20
1-29
1-31
1-35

FULL-DUPLEX TERMINAL DRIVER

2-1

2.1
2 .1.1
2 .1. 2

INTRODUCTION
ASR-33/35 Teletypes
KSR-33/35 Teletypes

2-1
2-3
2-3

iii

CONTEN~~S

Page
2 .1. 3
2 .1. 4
2 .1. 5
2 .1. 6
2 .1. 7
2 .1. 8
2 .1. 9

2. 1. 10
2.1.11
2 .1.12
2.1.13
2. 1. 14
2.2
2.3
2.3.1
2.3.2
2.3.2.1
2.3.2.2
2.3.2.3
2.3.2.4
2.3.2.5
2.3.2.6
2.3.2.7
2.3.2.8
2.3.2.9
2.3.2.10
2.3.2.11
2.3.2.12
2.3.2.13
2.3.2.14
2.3.2.15
2.4
2.5
2.5.1
2.5.2
2.6
2.6.1
2.6.2
2.6.3
2.6.4
2.6.4.1
2.6.4.2
2.6.4.3
2.6.5
2.7
2.8
2.9
2.9.1
2.9.2
2.10
2 .11
2.12
2.13
2.14
2.15
2.16

LA30 DECwriters
LA36 DECwriter
LA120 DECwriter
LA180S DECprinter
RT02 Alphanumeric Display Terminal and
RT02-C Badge Reader/Alphanumeric Display
Terminal
VT05B Alphanumeric Display Terminal
VT50 Alphanumeric Display Terminal
VT50H Alphanumeric Display Terminal
VT52 Alphanumeric Display Terminal
VT5~ Graphics Display Terminal
VT61 Alphanumeric Display Terminal
VTlOO DECscope
GET LUN INFORMATION MACRO
QIO MACRO
Subfunction Bi t:s
Device-Specific QIO Functions
IO.ATA
IO.ATT!TF.ESQ
IO.CCC
SF.GMC
IO.GTS
IO.RAL
IO.RNE
IO.RPR
IO.RPR!TF.BIN
IO.RPR!TF.XOF
IO.RST
SF.SMC
IO.RTT
IO.WAL
IO.WBT
STATUS RETURNS
CONTROL CHARACTERS AND SPECIAL KEYS
Control Characters
Special Keys
ESCAPE SEQUENCES
Definition
Prerequisites
Characteristics
Escape Sequence Syntax Violations
DEL or RUBOUT (177)
Control Characters (0-037)
Full Buffer
Exceptions to Escape-Sequence Syntax
VERTICAL FORMAT CONTROL
AUTOMATIC CARRIAGE RETURN
FEATURES AVAILABLE BY RSX-llM SYSGEN OPTION
Private Buffer Pool Size
Hard Receive Error Detection
TASK BUFFERING OF RECEIVED CHARACTERS
TYPEAHEAD BUFFERING
FULL-DUPLEX OPERATION
PRIVATE BUFFER POOL
INTERMEDIATE INPUT AND OUTPUT BUFFERING
TERMINAL-INDEPENDENT CURSOR CONTROL
TERMINAL INTERFACES

2-3
2-3
2-4
2-4
2-4
2-4
2-4
2-4
2-5
2-5
2-5
2-5
2-5
2-6
2-9
2-9
2-10
2-11
2-12
2-12
2-16
2-17
2-17
2-17
2-18
2-18
2-18
2-19
2-19
2-19
2-20
2-20
2-24
2-25
2-27
2-28
2-29
2-29
2-30
2-30
2-30
2-30
2-31
2-31
2-31
2-31
2-33
2-33
2-33
2-34
2-35
2-36
2-36
2-36
2-37
2-37

~
! 1

CONTENTS
Page

CHll1.PTER

2.16.l
2.16.2
2.16.3
2.16.4
2.17
2.17.1
2.17.2
2.17.3
2.17.4
2.17.5
2.17.6

DHll Asynchronous Serial Line Multiplexer
DJll Asynchronous Serial Line Multiplexer
DLll Asynchronous Serial Line Interface
DZll Asynchronous Serial Line Multiplexer
PROGRAMMING HINTS
ESCape Code Conversion
RT02-C Control Function
Use of IO.WVB Instead of IO.WLB
Remote DLll-E, DHll, and DZll Lines
Side Effects of Setting Characteristics
Modem Support

2-37
2-38
2-38
2-38
2-38
2-38
2-38
2-38
2-39
2-39
2-39

HALF-DUPLEX TERMINAL DRIVER

3-1

3.1

INTRODUCTION
ASR-33/35 Teletypes
KSR-33/35 Teletypes
LA30 DECwriters
LA36 DECwriter
LA120 DECwriter
LA180S DECprinter
RT02 Alphanumeric Display Terminal and
RT02-C Badge Reader/Alphanumeric Display
Terminal
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 DECscope
GET LUN INFORMATION MACRO
QIO MACRO
Subfunction Bits
Details on Device-Specific QIO Functions
IO.ATA
IO.ATT!TF.ESQ
IO.CCC
SF.GMC
IO.GTS
IO.RAL
IO.RNE
IO.RPR
IO.RPR!TF.BIN
IO.RPR!TF.XOF
IO.RST
SF.SMC
IO.WAL
IO.WBT
STATUS RETURNS
CONTROL CHARACTERS AND SPECIAL KEYS
Control Characters
Special Keys
ESCAPE SEQUENCES
Definition
Prerequisites
Characteristics
Escape Sequence Syntax Violations

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

3. l . l
3. l. 2
3. l. 3
3. l . 4
3 .1. 5
3. l . 6
3. l . 7

3 .1. 8
3 .1. 9
3. 1. 10
3.l.11
3 .1.12
3. l.13
3. l.14
3.2
3.3
3.3.1
3.3.2
3.3.2.1
3.3.2.2
3.3.2.3
3.3.2.4
3.3.2.5
3.3.2.6
3.3.2.7
3.3.2.8
3.3.2.9
3.3.2.10
3.3.2.11
3.3.2.12
3.3.2.13
3.3.2.14
3.4
3.5
3.5.1
3.5.2
3.6
3.6.1
3.6.2
3.6.3
3.6.4

3-3
3-3
3-4
3-4
3-4
3-4
3-4
3-4
3-4
3-5
3-7
3-8
3-9
3-9
3-10
3-10
3-11
3-12
3-12
3-13
3-13
3-13
3-13
3-14
3-14
3-14
3-15
3-19
3-19
3-21
3-22
3-22
3-23
3-23
3-23

CONTEN'TS

·~.
Page
3.6.4.1
3.6.4.2
3.6.4.3
3.6.5
3.7
3.8
3.8.1
3.8.2
3.8.3
3.8.4
3.9
3.9.1
3.9.2
3.9.3
3.9.4
3.10
3.10.l
3.10.2
3.10.3
3.10.4
3.10.5
3.10.6
3.10.7
3.10.8
3.10.9
3.10.10

CHAPTER

3-24
3-24
3-25
3-25
3-25
3-26
3-27
3-27
3-28
3-28
3-28
3-28
3-29
3-29
3-29
3-29
3-29
3-29
3-30
3-30
3-30
3-30
3-30
3-31
3-31

3.10.11
3.10.12
3.10.13

DEL or RUBOUT (177 Octal)
Control Characters (0-37 Octal)
Full Buffer
Exceptions to Escape-Sequence Syntax
VERTICAL FORMAT CONTROL
FEATURES AVAILABLE BY SYSGEN OPTION
Automatic Carriage Return
Variable-Length Buffering
Task Buffering of Received Characters
LA30-P Support
TERMINAL INTERFACES
DHll Asynchronous Serial Line Multiplexer
DJll Asynchronous Serial Line Multiplexer
DLll Asynchronous Serial Line Interface
DZll Asynchronous Serial Line Multiplexer
PROGRAMMING HINTS
Terminal Line Truncation
ESCape Code Conversion
RT02-C Control Function
Checkpointing During Terminal Input
Time Required for IO.KIL
Use of IO.WVB
Remote DHll and DZll Lines
High-Order Bit on Output
Side Effects of Setting Characteristics
Unsolicited-Input-Character AST's for
Tasks Attaching Several Terminals
Direct Cursor Control
DLll Receiver Interrupt Enable
Loadable Driver Restrictions

VIRTUAL TERMINAL DRIVER

4-1

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

INTRODUCTION
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
IO.ATT
IO.DET
IO.KIL
IO.RLB, IO.RVB, IO.WLB, IO.WVB
Device-Specific QIO Function (IO.STC)
STATUS RETURNS

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

DISK DRIVERS

5-1

INTRODUCTION
RFll/RSll Fixed-Head Disk
RS03 Fixed-Head Disk
RS04 Fixed-Head Disk
RP11/RP02 or RP03 Pack Disks
RM02/RM03 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
RXlO/RXOl Flexible Disk
RX211/RX02 Flexible Disk

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

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

3-32
3-32
3-32
3-33

! 1

CONTENTS
Page

CHAPTER

5.2
5.3
5.3.1
5.3.2
5 .. 4
5.5

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

5-4
5-5
5-5
5-6
5-7
5-10

DECTAPE DRIVER

6-1

6 .. 1

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-3
6-6
6-7
6-7
6-7
6-7

DECTAPE II DRIVER

7-1

7.1

7.3.2
7.3.2.1
7 .. 3.2.2
7.3.2.3
7.3.2.4
7.4

INTRODUCTION
TU58 Hardware
TU58 Driver
GET LUN 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

8-1

8.1

INTRODUCTION
TE10/TU10/TS03 Magnetic Tape
TE16/TU16/TU45/TU77 Magnetic Tape
TS04 Magnetic Tape
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
Device-Specific QIO Functions
IO.RLV
IO.RWD
IO.RWU
IO.ERS
IO.SEC
IO.SMC
STATUS RETURNS
Se.lect Recovery
Retry Procedures for Reads and Writes

8-1
8-1
8-2
8-2
8-2
8-3
8-3
8-4
8-4
8-4
8-4
8-5
8-5

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

CHAPTER

7 .1.1
7 .. 1.2

7.2
7.3
7 .. 3 .1

CHAPTER

8 .1.1
8 .1. 2
8 .1. 3

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.4
8.4.1
8.4.2

"-"''
vii

6-7
6-8

8-8
8-8

8-12
8-12

CONTENTS
Page

B-12

8.5.3
8.5.4
8.5.5

Powerf ail Recovery for Magnetic Tapes
PROGRAMMING HINTS
Block Size
Importance of Resetting Tape
Characteristics
Aborting a Task
Writing an Even-J?arity Zero-NRZI
Density Selection

CASSETTE DRIVER

9-1

9.1
9.2
9.3
9.3.1
9.3.2
9.4
9.4.1
9.5
9.6
9.6.1
9.6.2
9.6.3
9.6.4
9.6.5
9.6.6

INTRODUCTION
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
Device-Specific QIO Functions
STATUS RETURNS
Cassette Recovery Procedures
STRUCTURE OF CASSE 1rTE TAPE
PROGRAMMING HINTS
Importance of Rewinding
End-of-File and IO.SPF
The Space Functions, IO.SPB and IO.SPF
Verification of Write Operations
Block Length
Logical End-of-Tape

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

LINE PRINTER DRIVER

10-1

10.l
10. 1.1
10. 1. 2
10 .1. 3
10 .1. 4
10.2
10.3
10.4
10.4.1
10.5
10.6
10.6.1
10.6.2
10.6.3

INTRODUCTION
LPll Line Printer
LSll Line Printer
LVll Line Printer
LA180 DECprinter
GET LUN INFORMATION MACRO
QIO MACRO
STATUS RETURNS
Ready Recovery
VERTICAL FORMAT CONTROL
PROGRAMMING HINTS
RUBOUT Character
Print Line Truncation
Aborting a Task

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

CARD READER DRIVER

11-1

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

INTRODUCTION
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
Device-Specific QIO Function
STATUS RETURNS
Card Input Errors and Recovery
Ready and Card Reader Check Recovery
I/O Status Conditions
FUNCTIONAL CAPABILITIES
Control Characters
CARD READER DATA F'ORMATS

11-1
11-1
11-2
11-2
11-2
11-3
11-3
11-6
11-6
11-8
11-8
11-9

8.4.3
8.5
8.5.1
8.5.2

CHAPTER

viii

~I
i'

8-13
8-13
8-13
8-13
B-13

H-13

CONTENTS
Page
11. 6 .1
11. 6. 2
11. 7
11. 7.
11. 7. 2

Alphanumeric Format (026 and 0211)
Binary Format
PROGRAMMING HINTS
Input Card Limitation
Aborting a Task

11-9
11-9
11-9
11-9
11-9

MESSAGE-ORIENTED COMMUNICATION DRIVERS

12-1

12.1
12 .1.1
12 .1. 2
12 .. 1. 3
12 .1. 4
12 .. 1. 5
12 .1. 6
12.1.7
12 .. 2
12.3
12.3.1
12.3.2
12.3.2.1
12 .. 3. 2. 2
12 .. 3. 2. 3
12.3.2.4
12 .. 3. 2. 5
12 .. 3. 2. 6
12.4
12 .. 5
12 .. 5 .1
12.5.2
12 .. 5. 3
12 .. 5. 4
12 .. 5. 5
12.5.6
12 .. 5. 7
12 .. 6

INTRODUCTION
DAll-B Parallel Interface
DLll-E Asynchronous Line Interface
DMCll Synchronous Line Interface
DPll Synchronous Line Interface
DQll Synchronous Line Interface
DUll Synchronous Line Interface
DUPll Synchronous Line Interface
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
Device-Specific QIO Functions
IO.FOX
IO.HDX
IO.INL and IO.TRM
IO.RNS
IO.SYN
IO.WNS
STATUS RETURNS
PROGRAMMING HINTS
Transmission Validation
Redundancy Checking
Half-Duplex and Full-Duplex Considerations
Low-Traffic Sync Character Considerations
Vertical Parity Support
Powerfail with DMCll
Importance of IO.INL
PROGRAMMING EXAMPLE

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-6
12-7
12-7
12-7
12-7
12-8
12-8
12-10
12-10
12-10
12-11
12-11
12-11
12-11
12-12
12-12

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

13-1

13 .. l
13 .. 1.1
13 .. 1.2
13.1.3
13 .. 2
13 .. 3

INTRODUCTION
PCLll-B Hardware
PCLll Transmitter Driver
PCLll Receiver Driver
GET LUN INFORMATION MACRO
QIO MACRO -- PCLll TRANSMITTER DRIVER
FUNCTIONS
Standard QIO Functions
Device-Specific QIO Functions
IO.ATX
IO.SEC
IO.STC
PCLll TRANSMITTER DRIVER STATUS RETURNS
QIO MACRO -- PCLll RECEIVER DRIVER FUNCTIONS
Standard QIO Functions
Device-Specific QIO Functions
IO.CRX
IO.RTF
IO.ATF

13-1
13-1
13-1
13-1
13-2

CHAPTER

13 .. 3.1
13 .. 3. 2
13.3.2.1
13 .. 3.2.2
13 .. 3.2.3
13 .. 4
13. 5
13.5.1
13.5.2
13.5.2.1
13.5.2.2
13.5.2.3

13-3
13-3
13-3
13-5
13-5
13-5
13-6
13-9
13-9
13-9
13-10
13-10
13-10

CONTEN'l~S

Page

CHAPTER

13.5.2.4
13.6

IO.DRX
PCLll RECEIVER DRIVER STATUS RETURNS

13-11
13-11

ANALOG-TO-DIGITAL CONVERTER DRIVERS

14-1

14.1
14 .1.1
14 .1. 2
14.2
14.3
14.3.1
14.3.2
14.4
14.4.1

INTRODUCTION
AFCll Analog-to--Digital Converter
ADOl-D Analog-to-Digital Converter
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Function
Device-Specific QIO Function
FORTRAN INTERFACE
Synchronous and Asynchronous Process
Control I/O
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 LUN to the ADOl-D
ASAFLN: Assigning a LUN to the AFCll
STATUS RETURNS
FORTRAN Interface Values
FUNCTIONAL CAPABILITIES
Control and Data Buffers
PROGRAMMING HINTS
Use of A/D Gain Ranges
Identical Chanrn~l Numbers on the AFCll
AFCll Sampling Rate
Restricting the Number of ADOl-D
Conversions

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

UNIVERSAL DIGITAL CONTROLLER DRIVER

15-1

15.1
15. 1. 1
15 .1. 2
15.1.2.1
15.1.2.2
15.2
15.3
15.3.1
15.3.2
15.3.2.1

INTRODUCTION
Creating the UDCll Driver
Accessing UDCll Modules
Driver Services
Direct Access
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Function
Device-Specific QIO Functions
Contact Interrupt Digital Input (W733
Modules)
Timer (W734 I/O Counter Modules)
Latching Digital Output (M685, M803, and
M805 Modules)
Analog-to-Digital Converter (ADUOl
Module)
ICSll Analog-to-Digital Converter
(IAD-IA Module)
DIRECT ACCESS
Defining the UDCll Configuration
Assembly Procedure for UDCOM.MAC
Symbols Defined by UDCOM.MAC

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

14.4.2
14.4.3
14.4.4
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.3.2.2
15.3.2.3
15.3.2.4
15.3.2.5
15.4
15.4.1
15.4.1.1
15. 4 .1. 2

14-3
14-3
14-4
14-5
14-5
14-6
14-6
14-6
14-8
14-9
14-9
14-9
14-9
14-9
14-10
14-10

15~3

15-3
15-5
15-7
15-7
15-7
15-8
15-8
15-9
15-9
15-10

CONTENTS
Page

l!).5.20
1!5.5.21
1!5. 6
l!).6.1
15.7
l!).7.1
1!5.7.2

Including UDCll Symbolic Definitions in the
System Object Module Library
Referencing the UDCll through a Global
Common Block
Creating a Global Common Block
Making the Common Block Resident
Linking a Task to the UDCll Common Block
FORTRAN INTERFACE
Synchronous and Asynchronous Process
Control I/O
The isb Status Array
FORTRAN Subroutine Summary
AIRD/AIRDW: Performing Input of Analog
Data in Random Sequence
AISQ/AISQW: Reading Sequential Analog
Input Channels
AO/AOW: Performing Analog Output
ASUDLN: Assigning a LUN to the UDCll
CTDI: Connecting to Contact Interrupts
CTTI: Connecting to Timer Interrupts
DFDI: Disconnecting from Contact Interrupts
DFTI: Disconnecting from Timer Interrupts
DI/DIW: Reading Several Contact Sense
Fields
DOL/DOLW: Latching or Unlatching Several
Fields
DOM/DOMW: Pulsing Several Fields
RCIPT: Reading a Contact Interrupt Point
RDCS: Reading Contact Interrupt Change-ofState Data from a Circular Buffer
RDDI: Reading Contact Interrupt Data from
a Circular Buff er
RDTI: Reading Timer Interrupt Data from a
Circular Buff er
RDWD: Reading a Full Word of Contact
Interrupt Data from the Circular Buffer
RSTI: Reading a Timer Module
SCTI: Initializing a Timer Module
STATUS RETURNS
FORTRAN Interface Values
PROGRAMMING HINTS
Numbering Conventions
Processing Circular Buffer Entries

LABORATORY PERIPHERAL SYSTEMS DRIVERS

16-1

16.1
16. 1.1
16. 1. 2
16.2
16.3
16.3.1
16.3.2
16.3.2.1
16.3.2.2
16.3.2.3
16.3.2.4

INTRODUCTION
ARll Laboratory Peripheral System
LPSll Laboratory Peripheral System
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Function
Device-Specific QIO Functions (Immediate)
IO.LED
IO.REL
IO.SDI
IO.SDO

16-1
16-2
16-2
16-2
16-2
16-2
16-3
16-3
16-4
16-4
16-4

15.4.2
l!).4.3
l!).4.3.1
15.4.3.2
l!).4.3.3
l!). 5
l!).5.1
l!>.5.2
l!).5.3
l!i.5.4
15.5.5
15.5.6
l!).5.7
l!).5.8
15.5.9
l!i.5.10
15.5.11
15.5.12
15.5.13
l!i.5.14
15.5.15
1!5.5.16
1!5.5.17
1!5.5.18
15.5.19

CHAPTER

15-11
15-11
15-11
15-13
15-13
15-13
15-14
15-14
15-15
15-17
15-17
15-18
15-18
15-19
15-19
15-20
15-20
15-21
15-21
15-22
15-22
15-23
15-24
15-25
15-25
15-26
15-26
15-27
15-29
15-29
15-29
15-30

CONTEN'.rS
Page
16.3.3

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

Device-Specific QIO Functions
(Synchronous)
IO.ADS
IO.HIS
IO.MDA
IO.MDI
IO.MOO
Device-Specific QIO Function (IO.STP)
IO.STP
FORTRAN INTERFACE
The isb Status Array
Synchronous Subroutines
FORTRAN Subroutine Summary
ADC: Reading a Single A/D Channel
ADJLPS: Adjusting Buffer Pointers
ASLSLN: Assigning a LUN to LSO:
ASARLN: Assigning a LUN to ARO:
CVSWG: Converting a Switch Gain A/D Value
to Floating-Point
DRS: Initiating Synchronous Digital Input
Sampling
HIST: Ini tiatiwJ Histogram Sampling
(LPSll only)
!DIR: Reading Digital Input
!DOR: Writing Digital Output
IRDB: Reading Data from an Input Buffer
LED: Displaying in LED Lights (LPSll only)
LPSTP: Stopping an In-Progress Synchronous
Function
PUTD: Putting a Data Item into an Output
Buffer
RELAY: Latching an Output Relay
(LPSll only)
RTS: Initiating Synchronous A/D Sampling
SDAC: Initiating Synchronous D/A Output
SDO: Initiating Synchronous Digital Output
STATUS RETURNS
IE .RSU
Second I/O Status Word
IO.ADS and ADC Errors
FORTRAN Interface Values
PROGRAMMING HINTS
The LPSll/ARll Clock and Sampling Rates
Importance of the I/O Status Block
Buffer Management
Use of ADJLPS for Input and Output

PAPER TAPE READER/PUNCH DRIVERS

17-1

17.1
17.2
17.3
17.4
17.4.1
17.4.2
17.5
17.5.1

INTRODUCTION
GET LUN INFORMATION MACRO
QIO MACRO
STATUS RETURNS
Error Conditions
Ready Recovery
PROGRAMMING HINTS
Special Action Resulting from Attach and

17-1
17-1
17-2
17-2
17-4
17-4
17-5

16.3.3.1
16.3.3.2
16.3.3.3
16.3.3.4
16.3.3.5
16.3.4
16.3.4.1
16.4
16.4.1
16.4.2
16.4.3
16.4.4
16.4.5
16.4.6
16.4.7
16.4.8
16.4.9
16.4.10
16.4.11
16.4.12
16.4.13
16.4.14
16.4.15
16.4.16
16.4.17

CHAPTER

D~tach

17.5.2

Reading Past End-of-Tape

xii

16-4
16-5
16-6
16-7
16-7
16-7
16-8
16-8
16-8
16-8
16-9
16-10
16-11
16-11
16-12
16-13
16-13
16-14
16-15
16-17
16-17
16-18
16-18
16-19
16-19
16-19
16-20
16-22
16-23
16-25
16-27
16-28
16-29
16-29
16-30
16-30
16-31
16-31
16-32

17-5
17-5

CONTENTS
Page
CHAPTER

INDUSTRIAL CONTROL SUBSYSTEMS

18-1

18.1
INTRODUCTION
18-1
18 .1.1
Hardware Configuration
18-1
18.1.1.1
ICS/ICR Address Assignments
18-1
DSS/DRS.Address Assignments
18 .1.1. 2
18-2
18.1.1.3Supported ICS/ICR I/O Modules
18-3
18 .1. 2
Alternate ICSll Support
18-3
18 .1. 3
Software Support
18-4
18 .1. 4
UDCll Software Compatibility
18-6
18. 1. 5
Module Addressing Conventions
18-7
LUN INFORMATION
18.2
18-8
18.3
ASSEMBLY LANGUAGE INTERFACE
18-8
18.3.l
General Error Status Returns
18-11
18. 3. 1. 1
Directive Conditions
18-12
18.3.1..2
18-12
I/O Conditions
18.3.2
A/D Input - Read Multiple A/D Channels
18-13
18.3.3
Analog Output
18-14
18.3.4
Momentary Digital Output - Multi-Point
18-15
18.3.5
Bistable Digital Output - Multi-Point
18-15
18.3.6
Unsolicited Interrupt Processing
18-16
18.3.6 . .l
Connect to Digital Interrupts
18-18
18.3.6.2
Disconnect from Digital Interrupts
18-19
18·.3.6.3
Connect to Counter Module Interrupts
18-19
18.3.6.4
Set Counter Initial Value
18-20
18.3.6.5
18-21
Disconnect from Counter Interrupts
18.3.6.6
Connect to Terminal Interrupts
18-21
18.3.6.7
Disconnect from Terminal Input
18-22
18.3.7
Activating a Task by Unsolicited Interrupts 18-22
18.3.7.1
Link a Task to Digital Interrupts
18-23
18.3.7.2
18-24
Link a Task to Counter Interrupts
18.3.7.3
Link a Task to Terminal Interrupts
18-24
18.3.7.4
Link a Task to Error Interrupts
18-25
Read Activating Data
18.3.7.5
18-25
18.3.7.6
Unlink a Task from Interrupts
18-27
18.3.8
Terminal Output
18-29
Maintenance Functions
18.3.9
18-29
18.3.9.l
Disable Hardware Error Reporting
18-29
18.3.9.2
Enable Hardware Error Reporting
18-30
18.3.10
Special Functions
18-30
18.3.10 .. 1
I/O Rundown
18-30
18.3.10.2
Kill I/O
18-31
18-31 .
18.4
FORTRAN INTERFACE
Synchronous and Asynchronous Process
18.4.1
18-32
Control I/O
18.4.2
Return Status Reporting
18-33
18.4.3
Optional Arguments
18-35
18.4.4
Assigning Default Logical and Physical
Units for Input and Output - ASICLN/ASUDLN
(ICS/ICR) and ASISLN (DSS/DRS)
18-35
Analog Input
18.4.5
18-37
18.4.5.l
AIRD/AIRDW: Analog Input - Specified
Channel Sequence
18-37
18.4.5.2
AISQ/AISQW: Analog Input - Sequential
Channel Sequence
18-39
18.4.6
AO/AOW: Analog Output - Multichannel
18-41
18.4.7
DOL/DOLW: Digital Output - Bistable Multiple
Fields
18-42

xiii

CONTENTS
Page
Digital Input
18-44
DI/DIW: Digital Input - Digital Sense
Multiple Fields
18-44
18.4.8.2
RCIPT: Digital Input - Digital Interrupt
Single-Point
18-45
18.4.9
DOM/DOMW: Digital Output Momentary Multiple Fields
18-46
18.4.10
RTO/RTOW: Remote~ Terminal Output
18-47
18. 4 .11
Unsolicited Interrupt Data - Continual
Monitoring
18-47
18. 4 .11.1
CTDI: Connect a Buffer for Receiving
Digital Interrupt Data
18-48
18. 4 .11. 2
Reading Digital Interrupt Data
18-49
18.4.11.3
DFDI: Disconnect a Buffer from Digital
Interrupts
18-52
18. 4 .11. 4
CTTI: Connect a Buffer for Receiving
Counter Data
18-53
18. 4 .11. 5
RDTI: Read Counter Data from the Circular
Buffer
18-54
18. 4 .11. 6
Miscellaneous Counter Routines
18-55
18.4.11.7
DFTI: Disconnect a Buffer from Counter
Interrupts
18-56
18. 4.11. 8
CTTY: Connect a Circular Buffer to Terminal
Interrupts
18-56
RDTY: Read a Character from the Terminal
18. 4 .11. 9
Buffer
18-57
18. 4 .11.10 DFTY: Disconnect a Circular Buffer from
Terminal Input
18-58
18.4.11.11 Progranuning Example
18-58
18.4.12
Unsolicited Interrupt Processing - Task
Activation
18-60
18.4.12.1
LNK: Link a Task to Interrupts
18-60
18.4.12.2
RDACT: Read Activation Data
18-62
18.4.12.3
UNLNK: Remove Interrupt Linkage. to a Task
18-64
18.4.13
Maintenance Functions
18-65
18.4.13.1
OFLIN: Place Selected Unit in Offline
Status
18-65
18.4.13.2
ONLIN: Return a Device to Online Status
18-65
18.5
ERROR DETECTION AND RECOVERY
18-66
18.5.1
Serial Line Errors
18-66
18.5.2
Power-Fail at a Remote Site
18-67
18.5.3
Power Recovery at the Processor
18-67
18.5.4
Unit in Offline Status
18-67
18.5.5
Error Data - !CSR and !CAR Registers
18-68
18.6
DIRECT ACCESS
18-69
Linking a Task to the ICS/ICR Conunon Block 18-71
18.6.l
18.6.2
Accessing the I/O Page
18-71
18.6.2.1
Mapping Table Format
18-71
18.6.2.2
I/O Page Global Definitions
18-72
18.6.2.3
Sample Subroutine
18-73
18.7
CONVERSION OF EXISTING SOFTWARE
18-75
18.7.1
Features
18-75
18.7.2
Module Support
18-75
18.7.2.1
IAD-IA A/D Converter and IMX-IA Multiplexer 18-75
16-Bit Binary Counter
18-76
18.7.2.2
18.7.2.3
Bistable Digital Output
18-76
18.7.2.4
Momentary Digital Output
18-76
18.7.2.5
Noninterrupting Digital Input
18-76
18.7.2.6
Analog Output
18-77
18.7.2.7
Interrupting Digital Input
18-77
18.4.8
18.4.8.1

xiv

CONTENTS

""'-"'

Page
CHll~PTER

NULL DEVICE DRIVER

19-1

CHP..PTER

GRAPHICS DISPLAY DRIVER

20-1

20.l
20.1.1
20.1.2
20.2
20.3
20.4
20.5

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-2
20-3

LABORATORY PERIPHERAL ACCELERATOR DRIVER

21-1

CHl\PTER

21.1
21.1.1
21.1. 2
21.2
21. 3
21. 3 .1
21.3.1.1
21.3.1.2
21.3.1.3
21.3.1.4
21.3.1.5
21.3.1.6

CHA.PTER

INTRODUCTION
LPAll-K Dedicated Mode of Operation
LPAll-K Multirequest Mode of Operation
GET LUN INFORMATION MACRO
THE PROGRAM INTERFACE
FORTRAN Interface
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
DipWP: Initiate Synchronous Digital Input
Sweep
21.3.1.7
DOSWP: Initiate Synchronous Digital Output
Sweep
21.3.1.8
FLT16: Convert Unsigned Integer to a Real
Constant
21.3.1.9
IBFSTS: Get Buffer Status
21.3.1.10
IGTBUF: Return Buffer Number
21.3.1.11
INXTBF: Set Next Buffer
IWTBUF: Wait for Buffer
21.3.1.12
21.3.1.13
LAMSKS: Set Masks Buffer
21.3.1.14
RLSBUF: Release Data Buffer
21.3.1.15
RMVBUF: Remove Buffer from Device Queue
21.3.1.16
SETADC: Set Channel Information
21.3.1.17
SETIBF: Set Array for Buffered Sweep
21. 3 .1.18
STPSWP: Stop Sweep
21.3.1.19
XRATE: Compute Clock Rate and Preset
21. 3. 2
MACR0-11 Interface
21.3.2.1
Accessing Callable LPAll-K Support Routines
21.3.2.2
Device-Specific QIO Functions
21.3.3
The I/O Status Block (IOSB)
21. 4
BUFFER MANAGEMENT
21. 5
LOADING THE LPA-11 MICROCODE
UNLOADING THE DRIVER
21. 6
21. 7
TIMEOUT OF THE LPAll-K
21. 8
22-BIT ADDRESSING SUPPORT
21. 9
SAMPLE PROGRAMS

21-14
21-14
21-15
21-16
21-16
21-17
21-18
21-19
21-19
21-20
21-20
21-21
21-22
21-22
21-23
21-25
21-27
21-28
21-29
21-29
21-30
21-32

K-SERIES PERIPHERAL SUPPORT ROUTINES

22-1

22.1
22 .1.1
22.1.1.1

INTRODUCTION
K-Series Laboratory Peripherals
AAll-K D/A Converter

22-1
22-1
22-1

21-1
21-1
21-1
21-1
21-2
21-2
21-3
21-6
21-7
21-8
21-8
21-10
21-12

CONTENTS

~'
Page
ADll-K A/D Converter
AMll-K Multiple~ Gain Multiplexer
DRll-K Digital I/O Interface
KWll-K Dual Programmable Real-Time Clock
Support Routine Features
·
Generation and Use of K-series Routines
Generation of K-series Support Routines
Program Use of K-series Routines
THE PROGRAM INTERFACE
FORTRAN Interface
ADINP: Initiate Single Analog Input
ADSWP: Initiab9 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
22.2.1.10
DOSWP: Initiate Synchronous Digital Output
Sweep
22.2.1.11
DOUT: Digital Output
FLT16: Convert Unsigned Integer to a Real
22.2.1.12
Constant
22.2.1.13
GTHIST: Gather Inter-event Time Data
22.2.1.14
IBFSTS: Get Buffer Status
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
22.2.1.20
RLSBUF: Release Data Buffer
22.2.1.21
RMVBUF: Remove Buffer from Device Queue
SCOPE: Control Scope
22.2.1.22
22.2.1.23
SETADC: Set Channel Information
22.2.1.24
SETIBF: Set Array for Buffered Sweep
22.2.1.25
STPSWP: Stop Sweep
22.2.1.26
XRATE: Compute Clock Rate and Preset
22.2.2
MACR0-11 Interface
22.2.2.1
Standard Subroutine Linkage and CALL Op
Code
22.2.2.2
Special-Purpose Macros
22.2.3
The I/O Status Block (IOSB)
22.3
BUFFER MANAGEMENT
22.4
SAMPLE FORTRAN PROGRAMS
22.4.1
Sample Program Using Event Flag
Sample Program Using Completion Routine
22.4.2

22.1.1.2
22.1.1.3
22.1.1.4
22.1.1.5
22.1.2
22 .1. 3
22.1.3.l
22.1.3.2
22.2
22.2.1
22.2.1.1
22.2.1.2
22.2.1.3
22.2.1.4
22.2.1.5
22.2.1.6
22.2.1.7
22.2.1.8
22.2.1.9

CHAPTER

22-2
22-2
22-2
22-2
22-2
22-3
22-3
22-4
22-5
22-5
22-6
22-7
22-9
22-9
22-11
22-11
22-12
22-13
22-13
22-15
22-16
22-16
22-17
22-18
22-18
22-19
22-19
22-20
22-20
22-21
22-21
22-21
22-22
22-23
22-23
22-24
22-25
22-25
22-25
22-26
22-26
22...;.27
22-27
22-28

UNIBUS SWITCH DRIVER

23-1

23.1
23 .1.1
23.1.2
23.2
23.3
23.3.1
23.3.1.l

INTRODUCTION
DT07 UNIBUS Switches
UNIBUS Switch Driver
GET LUN INFORMATION MACRO
QIO MACRO
Standard QIO Functions
IO.ATT

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

xvi

___

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

CONTENTS
Page
23 .. 3.1.2
23.3.1.3
23.3.2
23.3.2.1
23.3.2.2
23.3.2.3
23.3.2.4
23.3.2.5
23.4
23.4.1
23.4.2
23.5
23.6
APPENDIX A
A.1
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.1
A.15.2
A.16
A.17
A.18
A.19
APPENDIX B
B.l
B.1.1
B. l . 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
B.3.6
B.3.7
B.3.8
B.3.9
B.3.10

IO.DET
IO.KIL
Device-Specific QIO Functions
IO.CON
IO.DIS
IO.DPT
IO.SWI
IO.CSR
POWERFAIL RECOVERY
System Powerfail Recovery
UNIBUS Powerfail Recovery
STATUS RETURNS
FORTRAN USAGE

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

A-1

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

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

I/O FUNCTION AND STATUS CODES

B-1

I/O STATUS CODES
I/O Status Error Codes
I/O Status Success Codes
DIRECTIVES CODES
Directive Error Codes
Directive Success Codes
I/O FUNCTION CODES
Standard I/O Function Codes
Specific A/D Converter I/O Function Codes
Specific Card Reader I/O Function Codes
Specific Cassette I/O Function Codes
Specific Communication (Message-Oriented)
I/O Function Codes
Specific DECtape I/O Function Codes
Specific DECtape II I/O Function Codes
Specific Disk I/O Function Codes
Specific Graphics Display I/O Function
Codes
Specific ICS/ICR, DSS/DR I/O Function
Codes

B-1
B-1
B-3
B-3
B-4
B-4
B-4
B-4
B-4
B-5
B-5

xvii

B-5
B-6
B-6
B-6
B-7
B-7

CONTENTS

41111'.
Page
B. 3 .11
B.3.12
B. 3 .13
B.3.14

B.3.14.1
B.3.14.2
B.3.15
B.3.16
B.3.17
B.3.18
APPENDIX C

Specific LPAll-K I/O Function Codes
Specific LPS I/O Function Codes
Specific Magtape I/O Function Codes
Specific Parallel Communications Link
I/O Function Codes
Transmitter Driver Functions
Receiver Driver Functions
Specific Terminal I/O Function Codes
Specific UDC I/O Function Codes
Specific UNIBUS Switch I/O Function Codes
Specific Virtual Terminal I/O Function
Codes
RSX-llM PROGRAMMING EXAMPLE

INDEX

B-8
B-9
B-9
B-10
B-10
B-10
B-10
B-11

B-12
B-12
C-1

Index-!
FIGUHES

FIGURE

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

9-1
18-1
18-2
19-1

Logical Unit Table
QIO Directive Parameter Block
Determination of Tape Characteristics for
the TE10/TU10
Determination of Tape Characteristics for
the TE16/TU16/TU45/TU77
Structure of Cassette Tape
Mapping Table Format
Mapping Table Entry Format
Indirect TKB Command File TESTBLD.CMD

1-6
1-13
8-7
8-8
9-6
18-72
18-73
19-1

TABL.ES
TABLE

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

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

Get LUN Information
Directive Conditions
I/O Status Conditions
Supported Terminal Devices
Standard Terminal Interfaces
Standard and Device-Specific QIO Functions
for Terminals
Subfunction Bits
Full-Duplex Terminal Driver-Terminal
Characteristics for SF.GMC and SF.SMC
Functions
Bit TC.TTP (Terminal Type) Values Set by
SF.SMC and Returned by SF.GMC
Information Returned by Get Terminal
Support (IO.GTS) QIO
Terminal Status Returns
Terminal Control Characters
Special Terminal Keys
Vertical Format Control Characteristics
Supported Terminal Devices
Standard Terminal Interfaces
Standard and Device-Specific QIO Functions
for Terminals
Subfunction Bits

xviii.

1-20
1-30
1-32
2-2
2-3
2-6
2-10

2-13
2-15
2-16
2-21
2-25
2-27
2-32
3-1
3-2
3-6
3-8

CONTENTS
Page
TABLES (Cont.)
TABLE

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

4-2
4-3
5-1
5-2
5-3
5-4
6-1
6-2
6-3
7-1
7-2
7-3
8-1
8-2
8-3
8-4
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·-l
12·-2
12·-3
12-4
13-1
13·-2

13·-3
13·-4
13-5

Terminal Characteristics for SF.GMC and
SF.SMC Requests
Bit TC.TTP (Terminal Type): Values Set by
SF.SMC and Returned by SF.GMC
Information Returned by Get Terminal Support
(IO.GTS) QIO
Terminal Status Returns
Terminal Control Characters
Special Terminal Keys
Vertical Format Control Characters
Standard and Device-Specific QIO Functions
for Virtual Terminals
Virtual Terminal Status Returns for Off spring
Task Requests
Virtual Terminal Status Returns for Parent
Task Requests
Standard Disk Devices
Standard QIO Functions for Disks
Device-Specific Functions for the. RXOl,
RX02, RLOl, and RL02 Disk Drivers
Disk Status Returns
Standard QIO Functions for DECtape
Device-Specific Functions for DECtape
DECtape Status Returns
Standard QIO Functions for the TU58
Device-Specific QIO Functions for the TU58
TU58 Driver Status Returns
Standard Magtape Devices
Standard QIO Functions for Magtape
Device-Specific QIO Functions for Magtape
Magtape Status Returns
Standard QIO Functions for Cassette
Device-Specific QIO Functions for Cassette
Cassette Status Returns
Standard Line Printer Devices
Standard QIO Functions for Line Printers
Line Printer Status Returns
Vertical Format Control Characters
Standard QIO Functions for the Card Reader
Device-Specific QIO Function for the Card
Reader
Card Reader Switches and Indicators
Card Reader Status Returns
Card Reader Control Characters
Translation from DEC026 or DEC029 to ASCII
Message-Oriented Communication Interfaces
Standard QIO Functions for Communication
Interfaces
Device-Specific QIO Functions for
Communication Interfaces
Communication Status Returns
Standard QIO Functions for PCLll Transmitters
Device-Specific QIO Functions for PCLll
Transmitters
PCLll Transmitter Driver Status Returns
Standard QIO Functions for PCLll Receivers
Device-Specific QIO Functions for PCLll
Receivers

xix

3-10
3-11
3-11
3-16
3-19
3-21

3-:26
4-2

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

12-6
12-8
13-3
13-4
13-7
13-9

13-9

CONTENTS
Page
TABLES (Cont.)
TABLE

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

PCLll Receiver Driver Status Returns
Standard Analog-to-Digital Converters
Standard QIO Function for the A/D Converters
Device-Specific QIO Function for the A/D
Converters
A/D Conversion Control Word
Contents of First Word of isb
FORTRAN Interface Subroutines for the AFCll
and ADOl-D
A/D Converter Status Returns
FORTRAN Interface Values
Standard QIO Function for the UDCll
Device-Specific QIO Functions for the UDCll
A/D Conversion Control Word
Contents of First Word of isb
FORTRAN Interface Subroutines for the UDCll
UDCll Status Returns
FORTRAN Interface Values
Laboratory Peripheral Systems
Standard QIO Function for Laboratory
Peripheral Systems
Device-Specific QIO Functions for the
Laboratory Peripheral Systems (Immediate)
Device-Specific QIO Functions for the
Laboratory Peripheral Systems (Synchronous)
Device-Specific QIO Function for the
Laboratory Peripheral Systems (IO.STP)
Contents of First Word of isb
FORTRAN Interface Subroutines for Laboratory
Peripheral Systems
Laboratory Peripheral Systems Status Returns
Returns to Second Word of I/O Status Block
FORTRAN Interface Values
Standard QIO Functions for the Paper Tape
Reader/Punch
Paper Tape Reader/Punch Status Returns
ICS/ICR Address Assignments
Sample ICS/ICR Configuration
Sample DSS/DRS Configuration
Summary of Industrial Control QIO Functions
A/D Conversion Control Word
FORTRAN Interface
Return Status Summary
!CSR Contents
!CAR Contents
Standard and Device-Specific QIO Functions
for Graphics Displays
Graphics Display Status Returns
FORTRAN Subroutines for the LAPll-K
Device-Specific QIO Functions for the
LPAll-K
Contents of First Word of IOSB
FORTRAN Subroutines for K-series Laboratory
Peripherals
Scope Control Word Values

13-11
14-1
14-2
14-2
14-3
14-4
14-4
14-7
14-8
15-3
15-4
15-5
15-15
15-16
15-27
15-29
16-1
16-2
16-3
16-4
16-8
16-9
16-10
16-25
16-28
16-29
17-2
17-3
18-2
18-7
18-8
18-8
18-14
18-31
18-34
18-68
18-69
20-2
20-3
21-2
21-24
21-26
22-5
22-22

CONTENTS
Page
TABLES (Cont.)
TABLE

22-3
23-1
23-2
23-3

Contents of First Word of IOSB
Standard QIO Functions for UNIBUS Switches
Device-Specific QIO Functions for UNIBUS
Switches
UNIBUS Switch Driver Status Returns

~··

xxi

22-26
23-2
23-4
23-7

SUMMARY OF TECHNICAL CHANGES
This revision of the I/O Drivers Reference Manual contains changes and
additions to document two operating systems:
RSX-llM V3.2 and
RSX·-llM-PLUS Vl .o. The following list contains a
brief summary of
technical changes for both operating systems:
•

A new full-duplex terminal driver ,is available for RSX-llM
systems.
During SYSGEN,
the RSX-llM user can select either
the half-duplex terminal driver (available in previous RSX-llM
systems)
or the full-duplex terminal driver.
Only the
full-duplex terminal driver
is available
in RSX-llM-PLUS
systems.
Terminal driver support
terminal devices:

has

been

added

for

the

following

VTlOO
LA120
•

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

disk

RHXX/RM02
RL11/RL02
RK6 ll/RK07
RX211/RX02
•

DECtape II

(TU58) driver support has been added •.

•

Magnetic tape driver support has been added for the
TS04.

•

LPAll-K driver support has been expanded to accommodate
systems with 22-bit addressing.
While this allows the driver
to run on any system in which RSX-llM/M-PLUS
is
installed,
user tasks previously written to run on earlier versions of
RSX-llM may not run with the current LPAll-K driver without
modification (see Section 21.7).

•

PCLll Parallel Communication Link transmitter and
receiver
driver support has been added for RSX-llM-PLUS systems.
(PCLll driver support is not available in RSX-llM systems.)

•

UNIBUS switch
(DT03/DT07)
driver support
is provided for
RSX-llM-PLUS systems.
(UNIBUS switch driver support is not
available in RSX-llM systems.)

•

Virtual terminal driver support is provided for RSX-llM-PLUS
systems.
(Virtual terminals are not supported in RSX-llM
systems.)

xx i i i

TU77

and

NOTE
The following devices are not
in RSX-llM-PLUS systems:
Synchronous and
interfaces:
DAll-B
DLll-E

supported

asynchronous

line

(modem support is
provided in the
full-duplex terminal
driver)

DPll
DQll
DUll
Analog-to-digital converters:
AFCll
ADOl-D
UDCll universal digital controller
Laboratory peripheral systems:
ARll
LPSll
Industrial control subsystems:
ICS/ICR
DSS/DRS

local
and
remote
subsystems
digital
input
and
output subsystems

Graphics subsystems:
VTll
VS60
Terminal support is provided via
the
full-duplex terminal driver
only;
the half-duplex
terminal
driver is not supported

xxiv

PREFACE

MANUAL OBJEC'l'IVES

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:
Device Drivers
2

Full-duplex terminal communications
line interface

Half-duplex terminal communications
line interface

Virtual terminal driver

Disks

DECtape

xxv

Chapter

Device Drivers

DECtape II

Magnetic tape

Cassette

Line printers

Card reader

Message-oriented
line interfaces

PCLll parallel communications
transmitter and receiver

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
accelerator

K-seri~s

UNIBUS switch

communications
link

peripheral

laboratory peripherals

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

xxvi

the

acceptance

Appendixes A through C provide quick
reference material on I/O
functions and status codes and an example of RSX-llM I/O operations.
These include the following:

'-"

~ppendix

Contents

Summary of I/O
by device

functions

I/O function
codes

Programming example

status

and

ASSOCIATED DOCUMENTS

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

document are
Directory and
Documentation
manual in the
synopsis of

CONV:E:NTIONS 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

the

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:
IO.RLV, ••• ,<stadd,size>
null

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

one

DOM }
<inm, icont, idata, [idx], [isb], [lun] >
{ DOMW

QIO$C
4 ..

[err]

IO.ATT,6,,,,ASTOl

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

IO.KIL,9.

xxvii

optional

arguments

may

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 both 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
(i.e.,
INTEGER*2) and all real
arrays and variables are assumed to occupy two storage words
per variable (i.e., REAL*4).

xxviii

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 a~ I/O
Driv~, including update No 1, or the RSX-llM-PLUS Guide to Writing an
I/O Driver, depending upon the system you are using.)
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 which 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/O requests are queued as issued;
they
are subsequently processed according to the relative priority of the
tasks which
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/O
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 directives.
A function code included
in the QIO directive
indicates the particular
input or output
operation to be performed.
I/O 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

•

canceling a task's I/O requests

task's

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

1-1

RSX-llM/M-PLUS INPUT/OUTPUT

1.2

PHYSICAL, LOGICAL, AND VIRTUAL I/O

There are three possible modes in which an I/O
place.
These are physical, logical, and virtual.

transfer

can

take

Physical I/O concerns reading and writing data in the actual physical
units accepted by the hardware {e.g., sectors on a disk).
For most
devices, physical I/O is identical to logical I/O.
For example,
the
RK05 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.
F'or 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
{e.g., disks), logical blocks are numbered beginning at zero (0).
For
nonblock-structured devices {e.g., 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
nonf ile-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/O operations for them are described in detail in
subsequent chapters of this manual.

A variety of terminals,

including the following:

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

•

LA30 DECwriters {serial and parallel)

•

LA36 DECwriter II

•

LA120 DECwriter III

•

LA180S DECprinter

•

VTOSB Alphanumeric Display Terminal

•

VTSO Alphanumeric Display Terminal

•

VTSOH Alphanumeric Display Terminal

•

VT52 Alphanumeric Display Terminal

1 Teletype is a registered trademark of the Teletype Corporation.

1-2

RSX-llM/M~PLUS

INPUT/OUTPUT

•

VTSS Graphics Display Terminal

•

VT61 Alphanumeric Display Terminal

•

VTlOO 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

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

•

DZll Asynchronous Communication Line Interface Multiplexer

Asynchronous

Communication

Line
DLll-W

and

A variety of disks, including the following:
e

RFll/RSll Fixed-Head Disk

•

RS03 Fixed-Head Disk

•

RS04 Fixed-Head Disk

•

RP11/RP02 or RP03 Pack Disks

•

RM02, RM03 Pack Disk

•

RP04, RPOS, RP06 Pack Disks

RKll/RKOS or RKOSF Cartridge Disks

RLll/RLOl or RL02 Cartridge Disk

•

RK611/RK06 or RK07 Cartridge Disk

•

RXll/RXOl Flexible Disk

•

RX211/RX02 Flexible Disk

~·

TC11/TU56 DECtape

TU58 DECtape II

Three types of magnetic tape:

RHll or RH70/TM02 or TM03/TE16, TU16,
Magnetic Tape Controller/Formatter/Drive

•

TMll/TElO, TUlO or TS03 Magnetic Tape Controller/Drive

•

TS11/TS04 Magnetic Tape Controller/Drive

TAll Tape Cassette

1-3

TU45

TU77

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

A variety of line printers:

• LPll Line Printers
• LSll Line Printer
• LVll Line Printer
• LA180 Line Printer
8.

CRll Card Reader

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

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

10.

Synchronous
• DQll
support only)

Communication

Line

Interface

(RSX-llM

•

DUll Synchronous
support only)

Communication

Line

Interface

(RSX-:-llM

•

DUPll Synchronous Communication Line Interface

Two analog-to-digital converters:
•

AFCll Analog-to-Digital Converter

•

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

11.

UDCll Universal Digital Controller

12.

Laboratory peripheral systems:

13.

14.

15.

(RSX-llM

(RSX-llM support only)

•

ARll Laboratory Peripheral System (RSX-llM support only)

•

LPSll Laboratory Peripherc1l 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

The "Null Device," a software
eliminating unwanted output

1-4

Output

Subsystems

construct

that

(RSX-llM

facilitates

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

17.

Two graphics subsystems:
•

VTll Graphics Display System (RSX-llM support only)

•

VS60 Graphics Display System (RSX-llM support only)

Laboratory Peripheral Accelerator:
e

18.

LPAll-K

K-series laboratory peripherals:

• AAll-K Digital-to-analog Converter and Display
• ADll-K Analog-to-Digial Converter
• AMll-K Multiple Gain Multiplexer
• DRll-K Digital I/O Interface
Clock
• KWll-K Programmable Real
~rime

19.

PCLll
only)

20.

UNIBUS switch:
e

21.

1.4

DT07

Parallel

Communications

Link

(RSX-llM-PLUS

support

(RSX-llM-PLUS support only)

Virtual Terminals (RSX-llM-PLUS support only)

LOGICAL UNITS

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

1.4.1

and

Logic~! Unit Number

A logical unit number or LUN is a number which is 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-5

RSX-llM/M-PLUS INPUT/OUTPUT
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 logical unit table
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 zero 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.

1
LON 1

Number of LUNs
UCB

UCB

LON 2

t--

UCB

LON 3

1---

UCB
1---

LON 4

Figure 1-1

Logical Unit Table

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 via 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 significs1nce until they are associated
with a physical device unit by means of one of the methods described
below:
1.

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.

1-6

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

1.5

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/O 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 Executi~e 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 pass a battery of acceptance tests
administered by the Executive.
If the request fails it is rejected;
this rejection is signalled by the setting of the C-bit when the
statement following the QIO is executed.
It is good programming
practice to check
for directive
rejection by following the QIO
directive with a BCS instruction.
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 which issued the
QIO request cannot proceed until the I/O operation has completed,
it
should specify an event flag (see sections 1.5.l and 1.5.2) in the QIO
request and should issue a Waitfor system directive which specifies
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.
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

1-7

synchronizing

I/O

device

unit

completion

RSX-llM/M-PLUS INPUT/OUTPUT
•

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

A set of system macros which 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 ~he QIO directive are
optional, but space for these parameters must be reserved.
During expansion of a QIO macro, a value of zero 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:
QIO$C

IO.ATT,6,,,,ASTOX

where IO.ATT is the I/O function code for attach, 6 is the LUN, ASTOX
is the AST address, and commas indicate null arguments for the event
flag number, the request priority, and the address of the I/O status
block.
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
fol lows:
QI 0$ C

f nc, 1 u n, [ e f n] , [ p ri ] , [is b] , [as t] [ , <p 1 , 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
where xxx identifies the particular I/O operation.
For example, a QIO
request to attach the physical device unit associated with a LUN
specifies the function code:
IO.ATT

1-8

RSX-llM/M-PLUS INPUT/OUTPUT
A QIO request to cancel (or kill) all I/O requests for a specified LUN
begins in the following way:
QIO$C

!OoKIL, •••

The fnc parameter specified in the QIO request is stored internally as
a
function
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
zero 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
system object module library, which is automatically searched by the
Task Builder.
Local symbolic definitions may also be obtained via the
FILIO$ and SPCIO$ 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
is
specific to the task which
issues the I/O
request, and the LUN
refe~rence is usually device-independent.
An attach
request to the
physical devic~ unit associated with LUN 14 begins in the following
way:
QIO$C

IO.ATT,14., •••

Because each task has its own logical unit table (LUT)
in which the
physical device unit-LUN correspondences are established, the legality
of a lun parameter
is specific to the task which
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 logical unit table of a particular
task cannot exceed 255.
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 96.
If an event flag specification is not desire~, efn can be
omitted or can be supplied with a
value of zero.
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 tci synchronize I/O completion and
task execution.
Section 1.5.2 provides a more detailed explanation of
event flags and significant events.

1-9

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 zero (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, !OST, to determine if a bad parameter has been detected.
QIO$C
BCS
WTSE$C

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

CMPB
BNE

#IS .sue ,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 via 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 asynchronous system trap occurs.
Section 1.5.3
discusses the use of asynchronous system traps, and Section 2.2.5 of
the RSX-llM/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 zero
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,
etc.
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-10

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 revi~w 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
dync:1mi cally.
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 l 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 E~xample 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 is 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, tasks with priorities lower than that of the blocked
task 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 which 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 the initiation or completion of 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/a-related activity, they
cannot be controlled directly by the task which receives them.
However, the task may, under certain circumstances, block recognition
of ASTs to prevent simultaneous access to a critical data region.
When access to the critical data region has been completed, the queued

1-11

RSX-llM/M-PLUS INPUT/OUTPUT
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 E!xecuted as soon as possible,
consistent with the task's priority.
The use of the AST routine to
service I/O
related events provides a
response time which
is
considerably better than a polling mE!Chanism, 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
(i.e.,
the event which 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 routine 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 which 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 which 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 the expansion of 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 generates 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 which issued the
requests.
The I/O drivers examine their respective queues for the I/0
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-12

~.
I

.,;j

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

size of DPB -

f nc

priority

Byte
-DIC for QIO
directive

modif1ers

-r/o function

lun

-logical unit number

efn

-event flag number

pri
isb

ast

-address of
asynchronous trap
service routine

device-

address of I/O
status block

dependent
parameters

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

RSX-llM/M-PLUS INPUT/OUTPUT
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.

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, sharable 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 $DPB$$.
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.>

'QI0$S

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

Only the QIO$S form of the macro produces the DPB dynamically.
The
The
other
two
forms
generate
the
DPB
at assembly time.
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 QIO$ 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.

ALUN$, 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 exe~ution
issuing task until a specified event flag is set.

the

1-14

operation

described
and

supply

with

RSX-llM/M-PLUS INPUT/OUTPUT
1.7.1

The 010$ 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/0 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
dirE~ctive parameter block at address QIOREF by supplying this label as
an argument.
IO.RLB,6,2,,,ASTOl,<BUFFER,80.>
CREATE Q IO DPB

QIOHEF:

Q IO$

READl:

DIR$

#QIOREF

ISSUE I/O REQUEST

READ2:

DIR$

#QIOREF

ISSUE I/O REQUEST

1.7.2

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 implemented to allow a
task to reference a previously defined directive parameter block.
It
is issued in the form:
DIR$
where:

1.7.4

[addr] [,err]

addr

is 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

is an optional argument which specifies the address of
an error routine to which control branches if the
directive is rejected.
The branch occurs via a JSR PC,
err if the C-bit is set, indicating rejection of the
QIO directive.

The .MCALL Directive:

Retrieving system Macros

.MCALL is a MACR0-11 assembler directive which is used to
retrieve
macros from the System Macro Library (LB:[l,l]RSXMAC.SML) for use
during assembly.
It must be included in every user task which invokes

1-15

RSX-llM/M-PLUS INPUT/OUTPUT
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 which must be made available from the library.
The following example illustrates the use of this directive:
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

READ!:

#QIOREF ,DIRERR

ISSUE I/O REQUEST

.MCALL

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/0 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$
where:

lun,dev,unt

lun

is the logical unit number to be
specified physical device unit.

associated

dev

is the device name of the physical device or a
logical
device name assigned to a physical device (see MCR ASN
command).

unt

is the unit number of that device specified above.

For example, to associate LUN 10 with terminal unit 2,
macro call could be issued by the task:
ALUN$C

the

with

the

following

10.,TT,2

A unit number of 0 represents unit 0 for multi-unit 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.

1-16

RSX-llM/M-PLUS INPUT/OUTPUT
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 includE~d 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
RSX-llM-PLUS systems)

(not

supported

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

(not

supported

ARll Laboratory Peripheral
RSX-llM-PLUS systems)

System

(not

supported

DT03/DT07 UNIBUS
systems, only)

(supported

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, RP05, RP06 Pack Disk

TU58 DECtape I I

Converter

Switch

~·

1-17

RSX-llM-PLUS

RSX-llM/M-PLUS INPUT/OUTPUT
Name

Device

RFll/RSll Fixed-Head Disk

RK 11/RKOS Cartridge Disk

RL11/RL01/RL02 Cartridge Disk

RK6 ll/RK06 and RK7 11/R.KO 7 Cartridge Disk

RP11/RP02/RP03 Pack Disk

RM02/RM03 Pack Disk

RS03 and RS04 Fixed-Head Disks

TC11/TU56 DECtape

RXll/RXOl Flexible Disk

RX211/RX02 Flexible Disk

VT11/VS60
Graphics
RSX-llM-PLUS systems)

ICS/ICR Industrial Control Local and Remote
(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 Line Printers

LPSll Laboratory Peripheral System
RSX-llM-PLUS systems)

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

TS11/TS04 Magnetic Tape

TMll/TUlO/TUll or TSG3 Magnetic Tape

The N ul 1 Device

PCll Paper Tape Punch

PCll or PRll Paper Tape Reader

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

Terminals

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

UDCll Universal Digital Controller
RSX-llM-PLUS systems)

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

Systems

(not

supported

Subsystems

(not

Port

supported

(not

(supported

(regardless 1:>f interface)

1-18

Link

Port

(not
(not

supported

RSX-llM/M-PLUS INPUT/OUTPUT
Name

Device

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

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 Asynchronous Communications Line 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

'-'

........,.

Interface

(not

(not used by DIGITAL)

logical device
1.7.5.2 Pseudo-Device Names - A pseudo-device is a
which can normally be redirected by the operator to another physical
device unit at any time, without requiring changes in programs which
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:
Device

Code
CL

Console listing, normally the line printer.

Console output, normally the main operator's console.

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

Null device.

Network.

Online reconfiguration pseudo device.

Spooling scratch disk device.

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

1-19

RSX-llM/M-PLUS INPUT/OUTPUT

Code

Device

Pseudo-input terminal;
was requested.

the terminal from which a

task

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 (i.e., 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.
(Support,ed in
RSX-llM-PLUS systems, only).

The GLUN$ Macro:

Retrieving LUN 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$
where:

lun, buf

lun

is the logical unit number associated with the physical
device unit for which information is requested.

buf

is the 6-word buffer to which information is returned.

For example, to request information on the disk unit
LUN 8, the following call is issued:
GLUN$C

associated

with

8. ,IOBUF
Table 1-1
Get LUN Information

Numerical Offset
Word Byte Bit

Symbolic Offset
Byte
Bit

Contents
Name of device associated
LUN (ASCII bytes)

G.LUNA

Word

with

G.LUNU

Unit number of associated device

G.LUFB

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

(continued on next page)
1-20

RSX-llM/M-PLUS INPUT/OUTPUT

Table 1-1 (Cont.)
Get LUN Information

Numerical Offset
Symbolic Offset
Word Byte BT·.,-t-+-~W.,-o_r_d...........__---.--=s-y....,.t-e--.--__,B,,_..,..1_t_--1
G.Lucwl

First
word:

characteristics

Unit
record-oriented
device
(e.g., card reader, line printer)
(1 = yes)

(DV.CCL)

Cariage-control
device
(e.g.,
line printer, terminal) (1 = yes)

(DV.TTY)

Terminal device (1 = yes)

fDV.DIR)

Directory device (e.g.,
disk) (1 = yes)

(DV.SDI)

Single directory device
(e.g.,
ANSI-standard magtape) ( 1 = yes)

'DV .SQD)

Sequential
device
ANSI-standard magtape)

DECtape,

(e.g.'
(1 = yes)

Reserved

device

(DV.REC)

(U.CWl)

Contents

(DV.UMD)

User-mode
(1 = yes)

(DV.MBC)

Massbus device (1 = yes)

(DV.SWL)

Unit
software
(1 = yes)

(DV.ISP)

Input spooled device (1 =yes)

'DV.OSP)

Output spooled device (1 = yes)

(DV.PSE)

Pseudo-device (1 =yes)

(DV.COM)

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

(DV .Fll)

Device mountable as
device
(e.g., disk
'l = yes)

tDV.MNT)

Device mountable (logical
bits 13 and 14) (1 = yes)

G.LUCW+02
(U.CW2)

Second
word:
(U2.xxx)

diagnostics

device

supported

write-locked

a FILES-11
or DECtape)
OR

characteristics

Device-specific information

(continued on next page)

1-21

RSX-llM/M-PLUS INPUT/OUTPUT
Table 1-1 (Cont.)
Get LUN Information

Numerical Offset
Word Byte Bit
4

Word

S_ymbol ic Off set
Byte
Bit

G.LUCW+04

Contents
Third
word:

(U.CW3)

(U3 .x:<x)

device

characteristics

Device-spec i f ic information2

G.LUCW+06

Fourth
word:

(U.CW4)

Default buffer size
disks,
and
line
terminals).

device

characteristics
(e.g.'
length

for
for

1 The following word and bit symbols shown in parenthesis are symbols
used in defining and referencing corresponding items in the device
Unit Control Block (UCB)
2. For mass storage devices,

such as disks, DECtape,
and DECtape II,
this
is the maximum logical block number.
For the proper use of the
RX211/RX02 flexible disk, it is important to be able to test the
fourth device characteristics word to determine media density mode~.
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
asynchronous system trap
(AST)
service routine.
All forms of the
macro are provided.
However,
the S-form is preferred because
it

1-22

.......

RSX-llM/M-PLUS INPUT/OUTPUT

requires less space and
ASTX$C forms of the macro.
AS'l'X$S
wheI'e:

err

executes at least as fast as the ASTX$ or
The macro is issued in the following way:

[err]

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

Wai ting 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/O operation.
All three forms of the
macro call may be used.
It is issued as follows:
WTSE$
where:

efn

efn
is 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
tas~c blocking until the setting of the specified
event flag occurs.
This example also illustrates the use of the three forms of the macro
call.
Dl\TA DEFINITIONS

wArr:
IOSB:

WTSE!?
.BLKW

5
2

GENERATE DPB
I/O STATUS BLOCK

EXECUTABLE SECTION
ALUN$S
QIO$C
DIR$

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

QIO$S

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

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

1-23

RSX-llM/M-PLUS INPUT/OUTPUT
#2

QIO$C

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

WTSE$C

WAIT FOR WRITE TO COMPLETE

IO.DET,14.

DETACH DEVICE

QIO$C

1~8

WAIT FOR READ TO COMPLETE

WTSE$S

STANDARD I/O 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
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.l

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 C1IO macro call in the following
way:
QIO$C

IO.ATT, •••
1-24

RSX-llM/M-PLUS INPUT/OUTPUT
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,
nonfile-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 LUN directive except when at least· one LUN
is still
assigned to the attached device.
If the task which 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
which 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

I 0 .D ET, •••

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:

.MCALL
ALUN$S

AL UN$ S , Q IO$ S
#14.,#"CR

ASSOCIATE CARD READER WITH LUN 14

QIO$S

#IO.ATT,#14.

ATTACH CARD READER

QIO$S

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

1.8.3

READ CARD

QIO$S

# IO • D ET , # 14 •

IO.KIL:

Canceling I/O Requests

DETACH CARD READER

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 asynchronous system trap
(AST) service routine that may have been specified is not initiated.

1-25

RSX-llM/M-PLUS INPUT/OUTPUT
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, etc.) 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 {e.g., a read
on a paper-tape reader).

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

stadd

is the starting address of the data buffer.

size

is the data buffer size in bytes.

1.8.5

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

IO.RVB:

represents one to four optional parameters,
used to
specify such additional
information as block numbers
for certain devices.

Reading a Virtual Block

The function code IO.RVB 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.l and
3.3.1)
are
stripped
off
in
this
conversion.

~.
I:
I

1-26

RSX-llM/M-PLUS INPUT/OUTPUT

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:
IO.RVB, ••• ,<stadd,size,pn>

QIO$C
where:

stadd

is the starting address of the data buffer.

size

is the data buffer size in bytes.

1.8.6

represents one to four optional parameters,
used to
specify such additional
information as block numbers
for certain devices.

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

stadd

is the starting address of the data buffer.

size

is the data buff er in bytes.

1.8. 7

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

IO.WVB:

represents one to four optional parameters,
used to
specify such additional information as block numbers or
for.mat control characters for certain devices.

Writing a Virtual Block

The function code IO.WVB is used to write a virtual block of data to a
physical device unit.
A "virtualH 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, ••• ,<stad9 1 size,pn>

1-27

RSX-llM/M-PLUS INPUT/OUTPUT
where:

stadd

is the starting address of the data buffer.

size

is the data buffer size in bytes.

1.9

represents one to four optional parameters,
used to
specify such additional information as block numbers or
format control characters for certain devi~es.

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.

1.10

If an ast parameter was specified in the QIO macro call,
a
branch to the asynchronous system trap (AST) service routine
which· 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

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

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

1-28

the

and

failure

RSX-llM/M-PLUS INPUT/OUTPUT
Directive conditions relevant to I/O operations may
the followin9:
•

directive acceptance

•

invalid buffer specification

•

invalid efn parameter

•

invalid lun parameter

•

invalid DIC number or DPB size

•

unassigned LUN

•

insufficient memory

indicate

any

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 which corresponds 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 via 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 meaning:
Meaning

Code
Positive

(greater than zero)

Successful completion

Zero

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 which may be encountered
in QIO directives.
The acceptance condition is first, followed by
error codes indicating various reasons for rejection, in alphabetical
order.

1-29

RSX-llM/M-PLUS INPUT/OUTPUT

Table l·- 2
Directive Conditions
Code

rs.sue

Reason
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
The efn specification in a QIO directive
than zero or greater than 96.

IE. I LU

was

less

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

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 (e.g., Mark Time).

1-30

RSX-llM/M-PLUS INPUT/OUTPUT
1.10.2

I/O Status Conditions

The following list summarizes status codes which 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.

•

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

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

Word 0
1

~mber

I/O

status

block

Byte

-10
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 sequende 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 which must be read in this manner are
listed in Appendix B, Section B.1.2.)
Note that both of the following comparisons will test equal since
low-order byte in both cases is +l.
CMP

# IS • CR, I OSB

CMPB

#IS .sue ,IOSB

1-31

the

RSX-llM/M-PLUS INPUT/OUTPUT
In the case of a successful completion where the carriage return is
the terminal
indicator (IS.CR), the folLowing illustrates the status
block:
1
Word 0
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 which .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.
Table l·- 3
I/O Status Conditions
Code

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

IE .ABO

Operation aborted
The specified I/O operation was cancelled via
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.
(continued on next page)

1-32

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

Reason
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
a
An
illegal block
number was specified for
This code is
file-structured physical device unit.
returned, for example, if block 4800
is specified
for an RK05 disk,
on which legal block numbers
extend from zero 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.

IE~ .DAA

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.

H:.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.
(continued on next page)

1-33

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

Reason
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 timeout,
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. I FC

Illegal function
A function code was specified in . an I/O
request
that was illeg~l 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 se~ondary 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.

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)

1-34

~
I .

RSX-llM/M-PLUS INPUT/OUTPUT

Table 1-3 (Cont.)
I/O Status Conditions
Code

Reason

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

rn .WLK

check

(read)

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

1.11

the

write

write-locked

POWERFAIL RECOVERY PROCEDURES FOR DISKS AND DECTAPE

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.

PowE~rfail

1-35

RSX-llM/M-PLUS INPUT/OUTPUT

If QIOs are being used for disk or DECtape I/O operations during
powerfail 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-36

CHAPTEH 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
av~ilable
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 operati~n

•

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

•

Hedisplay 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

•

Added hardware support

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

NotE~

Throughout the remainder of this chapter, references made to MCR can
gen4~rally
be applied to other command line intepreters (for example,
DCL). In addition, the prompt displayed on a terminal in response to

2-1

FULL-DUPLEX TERMINAL DRIVER
invoking a command line interprett~r 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-· l
Supported Terminal Devices
Model

Columns

Lines/
screenl

CharactE~r

set

Baud
range

Upper
Send

lower cc1se?
Receive

ASR-33/35

110

KSR-33/35

110

LA30-P

300

LA30-S

64 .

110-300

LA36

132

64-96

110-300

yes

yes2

LA120

132

50-9600

yes

LA180S

132

300-9600

RT02

110-1200

RT02-C

110-1200

VT05B

110-2400

VT50

110-9600

VT50H

110-9600

VT52

110-9600

yes

VT55

110-9600

yes

VT61

110-9600

yes

VTlOO

80-132

50-9600

yes

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

2-2

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

Type

DHll

16-line multiplexer 1

DHll-DMll-BB

16-line multiplexer with modem control

DJ'll

16-line multiplexer

DLl 1-A/B/C/D/E/W

Single-line interfaces 3

02:11

8-line multiplexer with modem control 2

1
Direct memory access
terminal driver only.
2
Full-duplex control
l 031\-type modem.

(OMA)

only.

is
For

supported
example,

3
DLVll support with modem control is provided
terminal driver only.

the
th~

in
in

the

full-duplex
USA,

Bell

full-duplex

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.

2.1.l

ASR-33/35 Teletypes 4

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 4

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

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

2.1.4

LA36 OECwriter

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 upper-case and lower-case characters.

4 Teletype is a registered trademark of the Teletype Corporation.

2-3

FULL-DUPLEX TERMINAL DRIVER
2.1.5

LA120 DECwriter

The LA120 DECwriter is a hard-copy upper- and lower-case 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 driveru
Hardware features
allow
bidirectional
printing
for maximum printing speed,
and
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.6

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 upper-case and lower-case letters.

2.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 upper-case
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.1.8

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

2.1.10

VTSOB Alphanumeric Display Terminal

The VTSOH 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
VTOSB.)

2-4

FULL.-DUPLEX TERMINAL DRIVER

VT52 Alphanumeric Display Terminal

2.1.11

The VT52 is an upper-and-lower-case alphanumeric terminal with numeric
pad
and
direct cursor addressing.
(The VT52's direct cursor
addrE~ssing is compatible with that of the VTSOH, not with that of
the
VTOSB.) The VT52 6an be configured with a built-in thermal printer.

VT55 Graphics Display Terminal

2.1.12

The VT55 is similar to the VT52 in its operation as an alphanumeric
terminal.
The VTSS 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.

VT61 Alphanumeric Display Terminal

2.1.13

The VT61
is an "intelligent"
upper-and-lower-case
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.)

VTlOO DECscope

2.1.14

.._...,.

The VTlOO DECscope is an upperand
lower-case
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, etc.
These functions can also
be set-up by the system by issuing appropriate ANSI-standard escape
sequences.

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

2-5

FULL-DUPLEX TERMINAL DRIVER
Bit

Setting

Sequential device

Reserved

User-mode diagnostics supported

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Pseudo

Device mountable as a communications
channel

Device mountable as a FILES-11 volume

Device mountable

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

2.3

d1~vi ce

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
function
names.
These names are
retained for compatibility with
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 I 0 .D ET, •••

Detach device.

QIO$C IO.KIL, •••

Cancel I/O requests.
(continued on next page)

2-6

FULL-DUPLEX TERMINAL DRIVER
Table 2-3 (Cont.)
Standard and Device-Specific QIO Functions for Terminals
Format
ST.7\NDARD FUNCTIONS:

Function

(Cont.)

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

Read logical block
(read typed input into
buffer).

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

Read virtual block
(read typed input into
buffer).

QIO$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) •

.DE:VICE-SPECIFIC FUNCTIONS:
1QIO$C IO .. ATA, ••• ,<ast, [parameter2] [,ast2]>

Attach device, specify
unsolicited-inputcharacter AST.

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

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

loro$c SFeGMC, ••• ,<stadd,size>

Get multiple
characteristics.

loro$c IO.GTS, ••• ,<stadd,size>

Get terminal support.

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

Read logical block,
pass all bits.

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

Read logical block, do
not echo.

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

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.

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

Set multiple
characteristics.

1 SYSGEN options in RSX-llM.
(continued on next page)

2-7

FULL-DUPLEX TERMINAL DRIVER
Table 2-3 (Cont.)
Standard and Device-Specific QIO Functions for Terminals
Format
DEVICE-SPEC! FIC FUNCTIONS:

Function
(Cont.)

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

Write logical block,
pass all bits.

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

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

where:

ast

is the
entry
point
input-character AST.

parameter 2

is a number that can be used to
identify this
terminal as the
input source upon entry to an
unsolicited character AST routine.

ast2

is the entry point for an unsolicited CTRL/C AST.

pr add

is the starting address of the byte buffer
the prompt is stored.

pr size

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

for

unsolicited-

where

size

is the size of the stadd data buffer
in bytes.
The specified size must be greater than zero 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

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

table

is the address of the 16-word special
table.

tmo

is an optional timeout count
in
ten-second
intervals for
the full-duplex terminal driver.
If zero
is specified,
no timeout can occur.
Timeout
is the maximum time allowed between two
input characters before the read is aborted.

vf c

is a character for vertical :Eormat
Table 2-11 (see Section 2.7).

SYSGEN options in RSX-llM.

2-8

terminator

control

from

FULL-DUPLEX TERMINAL DRIVER
2.3.1

Subfunction Bits

Most device-specified functions
supported
by
terminal
driv,ers
described
in this section are selected using "subfunction bits".
One
or more functions can be selected by ORing their relative
bits
in a
QIO function.
Table 2-4 contains a listing of device-specific QIO
functions and relative subfunction bits that can be issued.
Each subfunction bit and subfunction selected when it is included in a
QIO function is listed as follows:
Symbolic
NamL __
TF.AST
TF.BIN
TF.CCO
TF.ESQ
TF.NOT

TF.RAL
TF.RCU
TF.RNE
'rF .RST
TF.TMO
TF.WAL
TF.WBT
TF.XCC
TF.XOF

Subf unction
unsolicited-input-character AST
binary prompt
cancel CTRL/O
recognize escape sequences
notification;
unsolicited
input
AST
in the
unsolicited
characters are stored
type-ahead buffer until they are read by the
task
read all bits
restore cursor position
read with no echo
read with special terminators
read with timeout
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
to
invoke device-specific 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 functi.on.
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), followed 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.1.
In addition to the device-specific QIO functions,
this
section
describes use of subfunction bits TF.ESQ, TF.BIN, and TF.XOF.

2-9

also

FULL-DUPLEX TERMINAL DRIVER
Table 2-·4
Subfunction Bits

Function

Allowed Subfunction Bits

Equivalent
Subfunctions

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

STANDARD FUNCTIONS

10.ATT

10.DET
10.RLB

10.RVB

10.KIL

..
x

10.WLB
10.WVB

.. . ..
x

***

...

DEVICE-SPECIFIC FUNCTIONS
10.ATA

10.ATT 1TF.AST

10.C'CO

10.WLB!TF.CCO

SF.GMC
10.GTS
10.RAL

10.RLB!TF.RAL

10.RNE

10.RLB'TF.RNE

10.RPR
10.RST

10.RLB!TF.RST

10.RTT
JO.WAL

10.WLB'TF.WAL

...

10.WBT

10.WLB!TF.WBT

SF.SMC

...
.

.
*

...

x
x
x

x
x
x
x
x

x
x
x
x
x
***

***

*Exercise great care when using Read All and Read with Special Terminators together. Obscure problems can result.
**These subfunctions are allowed but are not effective. They are stripped off when the read or write virtual operation is converted to a read or write logical operation.
***During a write-pass-all operation (JO.WAL or 10.WLB!TF.WAL) the terminal driver outputs characters without interpretation; it does not keep track of cursor position.

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 • ATA , ••• , < [as t] , [par a me t er 2] [ , as t 2 ] >
NOTE
A minimum of one AST parameter
as t 2 ) i s r eq u i red •

(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 can not be invoked to abort the
task in case of difficulty.

2-10

FULL-DUPLEX TERMINAL DRIVER
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 pribr 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 CL! 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).
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, the use of 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
typeahead 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.ATTITF.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 2e6
for a discussion of escape
sequences. )
If the terminal has not been declared capable of generating escape
sequences,
IO.ATTlTF.ESQ has no effect other than attaching the
terminal. No escape sequences are returned to the task because any

2-11

FULL-DUPLEX TERMINAL DRIVER
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.CCO is equivalent to IO.WLB!TF.CCO.

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

function

returns

where stadd is the starting address of a data buffer of length
bytes.
Each word in the buff er has the form:

"size"

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

characteristic-name
0

.BYTE
.BYTE

where characteristic-name is 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.
Table 2-5
Full-Duplex Terminal Driver-Terminal Characteristics
for SF.GMC and SF.SMC Functions
Bit
Name

Octal
Value

Meaning (if asserted)

Corresponding
MCR Command

TC.ACR

Wrap-around mode

SET /WRAP=TTnn:

TC.BIN

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

SET /RPA=TTnn:

TC.CTS

Suspend output to terminal
0 = resume
1 = suspend

TC.DLU

Dial-up line

SET /REMOTE=TTnn:

TC.ESQ

Input escape sequence
recognition

SET /ESCSEQ=TTnn:

TC.FDX

Full-duplex mode

SET /FDX=TTnn:

TC.HFF

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

SET /FORMFEED=TTnn:

(continued on next page)

2-12

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

..._,,

Bit
Name

Octal
Value

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

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

SET /HHT=TTnn:

TC.HLD 1

Hold screen mode

SET /HOLD=TTnn:

TC.ISL

Subline on interface (=0-15)

TC.LPP

Page length (1-255.=x)

SET /LINES=TTnn:x

TC.NEC

Echo suppressed

SET /ECHO=TTnn:

TC.PR!

Terminal is privileged

TC.RAT

Type-ahead buffer:
0 - 1-character type-ahead
1 - 36. character type-ahead

SET /TYPEAHEAD=TTnn:

TC.RSP2

Receiver speed

SET /SPEED=TTnn:rcv:xmit

TC.SCP

Terminal is a scope (CRT)

SET /CRT=TTnn:

TC.SLY

Terminal is a slave
If set to 0 (SET /NOSLAVE=TTnn:),
the terminal's type-ahead buffer
is cleared

SET /SLAVE=TTnn:

TC .SMR

Upper-case conversion disabled

SET /LOWER=TTnn:

TC.TBF

Type-ahead buffer count read,
or flush

TC .. TTP

Terminal type (=0-255.=x)

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

TC .. VFL

Send 4 fill characters after
line feed

SET /VFILL=TTnn:

Tc .. wro 3

Page width (=1-255.=x)

SET /BUF=TTnn:x

Tc .. xsp2

Transmitter speed

SET /SPEED=TTnn:rcv:xmit

TC. SBC

Meaning

Corresponding
MCR Command

(if asserted)

(Read only)

(bits-per-second)

SET /PRIV=TTnn:

SET /EBC=TTnn:

Pass 8 bits on input, even
if not binary input mode
(TC.BIN)
1 Effective for VT5x, VT61, and VTlOO, only.
2 r 3 See next page.

2-13

FULL-DUPLEX TERMINAL DRIVER

2 TC.RSP, TCXSP, and corresponding MCR SET /SPEED command values
terminal receiver and transmitter speeds are listed below:

for

NOTE
The MCR SET /SPEED command requires
parameters for both receiver (rev) and
transmitter
(xmit)
baud
rates,
as
follows:
SET /SPEED=TTnn:rcv:xmit
TC.RSP or
TC.XSP
value

Actual baud rate (in bps)
and valid MCR SET /SPEED values
(disabled)
50 (Baudot codes are not
supported)
75

s.o
S.50

S.75
llO
S.110
134
S.134
150
s.150
S.200
200
300
s.3oo
600
S.600
S.1200
1200
1800
S.1800
s.2000
2000
2400
S.2400
S.3600
3600
4800
s.4800
7200
s.1200
9600
S.9600
S.EXTA (DHl 1 external speed A)
S.EXTB (DHl 1 external speed B)
NOTE

Speed can be set only on DHll and DZll
controllers.
DZll
transmitter
and
receiver speeds must be equal (no split
baud rates permitted).
3 Unsolicited input that fills
the buffer before a
terminator is
received is likely inva1id. When this happens, the driver discards
the input by simulating a CTRL/U and echoing ~U.
The TC.TPP 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.TPP is used by the terminal driver to
determine cursor positioning commands, as appropriate.

2-14

FULL-DUPLEX TERMINAL DRIVER
Table 2-6
Bit TC.TTP (Terminal Type) Values Set by SF.SMC
and Returned by SF.GMC

.'-'

Implicit Characteristics
Octa1l
Valuie
0
1
2
3
4
5
6
7
10
llL

12
13
14
1 !)
16

Symbolic

Terminal
Type

TC.LPP

TC.WID

T.UNKO
T.AS33
T.KS33
T.AS35
T.L30S
T.L30P
T.LA36
T.VTOS
T.VTSO
T.VT52
T.VT55
T.VT61
T.Ll80
T.VlOO
T.Ll 20

Unknown
ASR33
KSR33
ASR35
LA30S
LA30P
LA36
VTOS
VTSO
VT52
VT55
VT61
LA180S
VTJ.00
LAJ.20

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

72
72
72
80
80
132

TC.HFF

TC.HHT

TC.VFL

TC.SCP

1
1
1
1
1

1
1
1
7
1
1
1
1
1

80
80
80
80
132
80
132

TC.HFL

1
1

'-'
NOTE:S
•

Octal values 0-177 are reserved by DIGITAL.
Values 200-377
are
available
for
customer use to define non-DIGITAL
terminals.

•

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
Returnee!
0
1
2
3

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

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.

2-15

FULL-DUPLEX TERMINAL DRIVER
NOTES
1.

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

The capacity of the type-ahead buffer is
36.
characters, maximum.

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

will

2.3.2.5 IO.GTS - This function is a Get Terminal Support request that
returns
information
to
a
four-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.
Table 2·-7
Information Returned by Get Terminal Support (IO.GTS)

Bit

Octal
Value

Mnemonic

QIO

Meaning When Set to l

Word 0 of Buffer:

12
13
14

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

Fl .ACR
lFl.BTW
Fl.BUF
lFl.UIA
Fl.CCO
lFl.ESQ
Fl .HLD
lFl .LWC
Fl.RNE
lFl.RPR
Fl.RST
lF l .RUB
Fl.SYN
F 1. TRW
Fl.UTB

100000

Fl.VBF

0
1
2
3
4
5
6
7
8
9

10
11

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-upper-case 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 l of Buffer:
0
l
2

3
4
5
6

1
2

4
10
20
40
100

1F2.SCH
1F2.GCH
F2 .DCH
F2 .DKL
F2.ALT
F2.SFF
1F2.CUP

Set characteristics QIO (SF.SMC)
Get characteristics QIO (SF.GMC)
Dump/restore characteristics
Historical IAS/RSX-llD IO.KIL
Altmode is echoed
Formf eed can be simulated
Cursor positioning

1 SYSGEN options on RSX-llM systems

2-16

~
'

FULL-DUPLEX TERMINAL DRIVER

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.

the

Therefore,

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
IOoRAL!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.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
function;
see Table 2-5, bit TC.NEC.)

selected

via

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 dif:fers from this combination of functions as follows:

•

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

2-17

FULL-DUPLEX TERMINAL DRIVER

•

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 is
cancelled 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.RPRITF.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!TF.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.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.I 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
n·ot put in the buffer.

not
I/O
and
the
is

IO.RST is equivalent to IO.RLBlTF.RST.

1 If upper-lower-case conversion is disabled, characters 175 and 176
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-18

FULL-DUPLEX TERMINAL DRIVER
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>
where stadd is the starting address of a buffer
bytes.
Each word in the buffer has the form:

length

"size"

.BYTE characteristic-name
.BYTE value
where "characteristic-name" is one of the symbolic bit names given in
Table 2-5,
and "value" is either 0 (to clear a given characteristic)
or 1 (to set a characteristic).
Table 2-5 notes the restrictions that
apply to these characteristics.
If the "characteristic-name" is TC.TTP (terminal
have any of the values listed in Table 2-6.

type),

"value"

can

A nonprivileged task can only issue an SF.SMC request for
its own
terminal (TI:).
A privileged task can issue SF.SMC to any ter~inal.
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.
Specifying any value for TC.TBF flushes (clears) th~ type-ahead buffer
(forces the type-ahead buffer count to 0).

2.3e2.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 16 character codes (20-37), and so-on,
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 representin~ 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 a~bits (TC.SBC), as listed in Table 2-5.
The optional timeout 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
int«~rcept 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-19

FULL-DUPLEX TERMINAL DRIVER

2.3.2.15 IO.WBT - 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.WB~', 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 IO.WBT
functions can be
stopped by a CTRL/S. Therefore, it may be desirable for tasks
to timeout on IO.WBT operations.

•

If a read is currently posted, the IO.WBT proceeds,
and an
automatic CTRL/R is performed to redisplay any input that was
received before the break-through write was effected
(if the
terminal is not in the full-duplex mode).

•

CTRL/O, if in effect,

•

An escape sequence that was interrupted is rubbed out.

is cancelled.

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

that

task.

in
The

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 rs.sue is 1. However, IS.CC, 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 1 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 IS.CC, IS.CR, IS.ESC, or IS.ESQ.
(If the
full word tests equal to IS.sue,
then its high byte
is zero,
indicating byte-count termination of the read.)
The "error" return IE.EOF may be considered a successful
read since
characters returned t~ 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.

2-20

FULL-DUPLEX TERMINAL DRIVER
Table 2:-8
Terminal Status Returns
Code
IIE.EOF

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

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.

IS.CC

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

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

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.
(continued on next page)

2-21

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

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

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.
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.OET
function was not attached by the issuing task.
This
code has no bearing on the attachment status of other
tasks.
(continued on next page)

2-22

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

Reason
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
timeout
occurred
on
the
physical
device-unit (that is, an interrupt was lost).

•

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

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.

IE .NOD

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 a~sociated with
the LUN
specified in the QIO directive was not online. 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 offline.

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.
(continued on next page)

2-:23

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

Reason
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 for a read or write request was
partially or totally outside the address space of the
issuing task, a byte count of zero was specified,
or
an odd or O AST address was specified.

IE.VER

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
in Table
2-5 was named in an SF.GMC or SF.SMC request, or a
task attempted to assert TC.PR!.
·

SE.FIX

An attempt was made to change a fixed characteristic
in a SF.SMC sub£unction 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.

SE.NSC

An attempt was made to change
a
non-settable
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 !emote 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-24

FULL-DUPLEX TERMINAL DRIVER
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 ftR, ftu, and AZ respectively.

T~rminal

Table 2-9
Control Characters
Meaning

Character
C~rRL/C

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
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.
If the hold-screen mode SYSGEN option has been
selected and
the
terminal
is a VT5x or VT61 in
hold-screen mode1 typing a CTRL/C
removes
the
terminal from hold-screen mode.
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 typeahead 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.
(continued on next page)

2-25

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

Meaning

CTRL/J

CTRL/J is equivalent to a LINE FEED character.

CTRL/K

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

CTRL/L

CTRL/L Ldtiates 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, 4 LINE FEEDs a·re 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.

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.

previously
(Output

suspended
can

(continued on next page)

2-26

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

Meaning

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

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 via the MCR
SET /BUF=TI:
command.
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 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
2. 6.)

HETU RN

Typing RETURN terminates the current line and causes
the carriage or cursor to return to the first column
on the line.
(continued on next page)

2-27

FULL-DUPLEX TERMINAL DRIVER

Table 2-10 (Cont.)
Special Terminal Keys
Key

Meaning

RUBOUT

Typjng 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 ~hat
has been deleted, even if the terminal
is
in the
noecho 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 noecho 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:
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.

2.6

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 in a SYSGEN option.
Some terminals generate
an escape sequence when a special key is pressed (for example, the FCN
key on the VT61).
On any
terminal,
an escape sequence may be

2-28

FULL-DUPLEX TERMINAL DRIVER

generated manually
characters.

typing

ESCape

followed

the appropriate

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

Definition

2.6.1

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

American

National

••• F

Where:
1.

ESC is the introducer control character
escape.

(33(8))

··~ are 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 is 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
execeptions are:
If the character ESC occurs,
the current
escape
sequence
is aborted,
and a
new one commences,
beginning with the ESC just recieved.
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.6.2

that is named

these

definition;

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 function
invoking the subfunction bit TF.ESQ.

and

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

2-29

FULL-DUPLEX TERMINAL DRIVER
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.

Characteristics

2.6.3

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

Escape Sequence Syntax Violations

2.6.4

A violation of the syntax defined in Section 2.6.l 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.
2.6.4.2 Control Characters (0-037) - The reception of any character
in the range
0 to 037 (with four exceptions -- see footnote2) is a
syntax violation that terminates the read with an error (IE.IES).

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
lower-case (MCR command SET /LOWER).
2 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

ffi

with the additional effect of turning off the output stream.

2-30

FULL-DUPLEX TERMINAL DRIVER

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 is~ues an IO.RLB with a buffer length of 2, and
you type:
ESC l

the buffer contains "ESC l", and the 1/0 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 0 •••
ESC p •••
ESC y • ••
ESC [

...

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.

2.8

AUTOMATIC CARRIAGE RETURN

Individual terminals can be set for wraparound, as desired, using
MCR SET commGI nd:

the

>SET /WHAP=TTxx:
Once wrap around has been selected, the column at
occurs can be selected using the MCR SET command:

which

wrap

around

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

display

>SET /BUF=TI:n

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

2-31

FULL-DUPLEX TERMINAL DRIVER
Table 2-11
Vertical Format Control Characters
Octal
Value

Character

040

blank

SINGLE SPACE - Output 1 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 2 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
4 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

PROMPTING OUTPUT Output 1 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.

000

null

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.

Meaning

All other vertical format control characters are interpreted as blanks
( 04 0) •
A task can determine the buffer width by issuing a Get LUN Information
directive ~nd 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 buff er
if
wraparound 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-32

FULL-DUPLEX TERMINAL DRIVER
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 Management 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 'l'T: /SI ZE==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 SK words.
Depending on driver options selected, the code requires from 2.5 to
3.5k words.
Thus, the maximum buffer pool size is from 4.5k to 5.5k
words.
Alternatively, on a processor that has separate I- and D-space mapping
registers,
it
is possible to allocate the private pool together with
all driver data in a separate common block called TTCOM.
This block
can range up to 8k words,
allowing the private buffer pool to be
almost as large.
When this is desired, answer Y to the following
two
SYSGEN questions:

>* DO YOU WANT KERNEL DATA SPACE SUPPORT? [Y/N] :
>* DO YOU WANT A SEPARATE TERMINAL BUFFER POOL? [Y/N]:

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 DHll and DZll
interfaces.

2-33

FULL-DUPLEX TERMINAL DRIVER

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

IE.DAO
IE.VER

Hard Receive Error
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 echDed,
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.

was

If the character cannot be processed immediately,
it is
stored in the typeahead buffer.
A flag is set for the line,
indicating that the last character in the typeahead buffer
has no error,
disabling further storage in the typeahead
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.

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

2 .10

TASK BUFFERING OF RECEIVED CHARA.CTERS

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.
Task buffering is overridden during checkpointing.
If a
task
is
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-34

•

FULL-DUPLEX TERMINAL DRIVER
2.11

TYPEAHEAD BUFFERING

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

Store in buffer:
An input character is stored in the typeahead buffer
or more of the following conditions are true:
•

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

•

~rhere

the

character

one
(fork

is at least one character presently in the typeahead

buffer
•

~rhe

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

•

No read request is in progress, no unsolicited input AST
is specified, and the terminal is either attached or
slaved.
NOTE
Depending on the terminal mode and the presence of
a
read
function,
read subf unctions and an
unsolicited input AST, the CTRL-C, CTRL-0, CTRL-Q,
CTRL-S, and CTRL-X characters may be processed
immediately and not stored in the
typeahead
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 or slaved.

Flush the buffer:
The buffer is flushed (cleared) when:
1.

CTRL--C is received

CTRL--X is received

the terminal becomes detached

the terminal becomes non-slaved

Exceptions: CTRL-C and CTRL-X do not flush the buffer if
read-pass-all or read-with-special-terminators is in effect.

2-3.5

FULL-DUPLEX TERMINAL DRIVER
If the buffer becomes full, each character that cannot
causes a BELL chBracter 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,
typeahead buffers and UCB extensions.
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 ip the system pool.
~owever, 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.
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 1:ead request to receive the rest
of the data.
The typeahead 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.

2-36

FULL-DUPLEX TERMINAL DRIVER
The unconditional output buffering serves three purposes.
1.

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)

2.15

the

TERMINAL-INDEPENDENT CURSOR CONTROL

Terminal-independent cursor control capability is provided at SYSGEN
time if the assembly parameter T$$CUP is defined.
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 zero.
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).
Home
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, IF.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 IN'l'ERFACES

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

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

2-37

FULL-DUPLEX TERMINAL DRIVER
2.16.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. Baud rates are jumper-selectable.

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

2.16.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, transmit and receive baud rates must be the
same. The DZll can control a full duplex modem in auto-answer mode.

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 LS.ESC status if
upper to lower-case 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.17.3

Use of IO.WVB Instead of IO.WLB

The use 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-38

FULL-DUP~EX

2.17.4

TERMINAL DRIVER

Remote DLll-E, 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 SYSGEN time.
Before 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.gSQ, TC.HLD, TC.SMR, TC.NEC, TC.FOX, TC.HFF,
TC.HHT,
TC.VFL, TC.HFL, and TC.TTP.
(Clearing TC.TTP means that a
terminal
type of "unknown" will be returned in an SF.GMC request.) Buffer size
is set to 72.
A DZll remote line must be declared to be remote before
driver will correctly handle the modem.

2.17.5

the

terminal

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/upper-case conversion . disable mode.
Their effects are
described as follows.

TC.BLD -- Unexpected behavior

can result
from a
terminal
in the
hold-screen mode
if
its
reception rate
is much greater than its
transmission rateo
(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/upper-case
conversion is disabled), octal characters 175 and 176 are interpreted
as "right brace ( } ) " and "tilde (-.)" respectively.
If TC.SMR is not
asserted,
these characters are
interpreted as an Altmode (that is,
they function as line terminators that do not advance the cursor to a
new line).

2.17.6

Modem Support

The terminal driver provides terminal support for modem control.
A
communications line can be set to remote or local operation via the
TC.DLU caracteristic bit.
MCR supports this bit with the SET /REMOTE
and SET /LOCAL commands.
If a communication link is established when a
the line is properly hung up.
If 6arrier is
seconds for carrier to return, otherwise, the
ring interrupt occurs during this time, the
up.

2-39

line is set to
local,
lost, the driver waits 2
line is hung up.
If a
line is immediately hung

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

Lines/
screenl

Character
set

Baud
range

Upper
Send

lower case?
Receive

ASH-33/35

110

KSR-33/ 35

110

LA30-P

300

LA30-S

110-300

LA36

80-132

64-96

110-300

yes

yes2

LA120

132

50-9600

yes

LA180S

132

300-9600

RT02

110-1200

R'I'02-C

110-1200

V'I'O 58

7.2

110-2400

yes

1 Applies only to video terminals.
2 Only for 96-character terminal.
The terminal driver supports the
terminal
interfaces summarized in Table 3-2. These interfaces are
described in greater detail in Section 3.9. Programming is
identical
for all.
(continued on next page)

3-1

HALF-DUPLEX TERMINAL DRIVER
Table 3-1 (Cont.)
Supported Terminal Devices
Model

Columns

VT50

110-9600

VT50H

110-9600

VT52

110-9600

yes

VT55

110-9600

yes

VT61

110-9600

yes

VTlOO

80-132

50-9600

yes

Lines/ Character
screenl
set

Baud
range

Upper & lower case?
Send
Receive

1 Applies only to video terminals.
Table 3-2
Standard Terminal Interfaces
Type

Model
DHll

16-line multiplexer l

DHl 1-DMll-BB

16-line multiplexer with modem control

DJll

16-line multiplexer

DLll-A/B/C/D/W

Single-line interfaces

DZll

8-line multiplexer with modem control.

1 Direct memory access

2
"

(OMA) not supported.

2 Full-duplex control only.
modem.

For example,

in the USA, a Bell 103A-type

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 Teletypes 3

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 Teletypes 3

The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals.
3 Teletype is a registered trademark of the Teletype Corporation.

3-2

HALF-DUPLEX TERMINAL DRIVER
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 upper-case and lower-case characters.

3.1.5

LA120 DECwriter

The LA120 DECwriter is a hard-copy upper- and lower-case 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 user-selected
features,
including font size, line spacing, tabs, margins, and forms
control.
These functions can also be set-up by ~ser tasks that
issue
appropriate ANSI-standard escape sequences.

3.1~6

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 upper-case and lower-case letters.

3 .1,, 7

RT0:2 l~lphanumeric Display Terminal
Alphanumeric Display Terminal

and

RT02-C

Badge

Reader/

3.1.8

VT05B 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-3

HALF-DUPLEX TER~ITNAL DRIVER
VTSO Alphanumeric Display Terminal

3.1.9

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

3.1.10

VTSOH Alphanumeric Display Terminal

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

3~1.11

VT52 Alphanumeric Display Terminal

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

3.1.12

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

3.1.13

VT61 Alphanumeric Display Terminal

The VT61
is an "intelligent"
upper-and-lower-case
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.)

3.1.14

VTlOO DECscope

The VTlOO DECscope is an upperand
lower-case
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, etc.
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.

3-4

HALF-DUPLEX TERMINAL DRIVER
Bit

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

()

Sequential device

()

Reserved

()

User-mode diagnostics supported

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

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

OIO MACno

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 for compatibility with IAS.

3-5

HALF-DUPLEX TERMINAL DRIVER
Table 3-·3
Standard and Device-Specific QIO Functions for Terminals
Format

Function

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

Attach device.

QIO$C IO.DET, •••

Detach device.

QIO$C IO.KIL, •••

Cancel I/O requests.

QIO$C IO.RLB, ••• ,<stadd,~ize>

Read logical block
(read typed input into buffer).

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

Read virtual block
(read typed input into buffer).

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

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),
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 block, pass all 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 ended by special
terminators.

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

Set multiple characteristics.

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

Write logical block, pass all bits.

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

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

where:

then

ast

is the entry point for
AST.

pradd

is the starting address of the byte buffer where the
prompt is stored. The buffer must be within the task's
address space.

unsolicited-input-character

3-6

HALF-DUPLEX TERMINAL DRIVER
prsize is the size of the pradd prompt buffer
in bytes.
If
the system supports variable length reads, the buffer
size must be greater than zero and less than or equal
to 255.
If the system does not support variable length
reads, the specified size must be greater than zero and
less than or equal to 80.
size

is the size of the stadd data buffer in bytes (must be
greater than zero).
If the function is a read and the
system supports variable length reads,
size must be
less than or equal to 255. Otherwise, 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, size must be an even number less than 4065
(decimal).
If the function is a write, size can be up
to 32K bytes.

st add

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

tmo

included
is an optional timeout count,
compatibility.
If supplied, it is ignored.

for

!AS

vf c

is a character for vertical format control
3-11 (see Section 3. 7) •

from

Table

"'-"'

3.3.1

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. AS'I'
TF. BIN
TF.CCO
TF.ESQ
TF.RAL
TF. RNE;
TF .RS'l'
TF.WAL
TF. WB'l'
TF.XOF

unsolicited-input-character AST
binary prompt
cancel CTRL/O
recognize escape sequences
read a 11 bi ts
read with no echo
read with special terminators
write all bits
break-through write
send XOFF

10
2

40
20
10
20
1
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, we recommend 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 QIO's 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>
Table 3·-4
Subfunction Bits
Allowed Subfunction Bits
Function

Equivalent with
subfunction bits TF.AST

TF. BIN

TF. CCO

TF.ESQ

TF.RAL

TF.RNE

TF.RST

IO .RLB

IO.RVB

TF.WAL

TF.WBT

TF.XOF

STANDARD FUNCTIONS:

IO.ATT
IO.DET
IO.KIL

IO.WLB

IO.WVB

DEVICE-SPECIFIC FUNCTIONS:
IO.ATA

IO.ATT!TF.AST

IO.cco

IO.WLB!TF.CCO

SF.GMC
IO.GTS
IO.RAL

IO.RLB!TF.RAL

IO.RNE

IO.RLB!TF.RNE

IO. RPR
IO.RST

IO.RLS!TF.RST

SF.SMC
IO.WAL

IO.WLB!TF.WAL

IO.WBT

IO. WLB ! TF. WBT

x
x

Exercise great care when using Read All and Read with Special Terminators together.
can result.

These subfunction bits are allowed but are not effecti.ve.
write virtual is converted to a read or write logical.

3.3.2

They are stripped

off

Obscure
when

the

problems
read

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.

3-8

HALF-DUPLEX TERMINAL DRIVER
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
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 trans~er 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 ace that neither type-ahead nor
full-duplex
operations can be simulated perfectly using unsolicited character
ASTs.
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 10.ATT ORed with the subfunction bit TF.AST.

"-"'

3.3.2.2 IO.ATTITF.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.

3-9

HALF-DUPLEX TERMINAL DRIVER
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 are 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 cancelled before the write is done.
IO.Ceo 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 Charac~erist~cs
is used in the following way:
.~.

QIO$C SF.GMC, ••• ,<stadd,size>
where stadd is the starting address of a data buffer of length
bytes.
Each word in the buffer has the form:
.BYTE
• BYTE

"size"

characteristic-name
0

where characteristic-name is one of the eight bit names given in Table
3-5.
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.

Table 3-5
Terminal Characteristics for SF.GMC and SF.SMC Requests
Bit
Name

Octal
Value

Meaning
(If Asserted) :

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

35
44
47
51
12
50
25
10

••• can generate escape sequences
••• is in hold-screen mode
••• is in no-echo mode
••• is privileged
••• is a scope (CRT)
••• is slaved
Upper-case conversion disabled
Terminal type

TC.HFF
TC.RSP3
TC.XSP3

17
3
4

••• handle hardware form feeds
Receiver speed
Transmitter speed

Terminal •••

Corresponding
MCR Command
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 /HHF=TI:
SET /SPEED=TI:rcv:xmit
(as above)

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

must use MCR command.

3 Recognized only by the SF.SMC function.

3-10

HALF-DUPLEX TERMINAL DRIVER
Table 3-6
Bit TC.TTP (Terminal Type): Values Set by SF.SMC
and Returned by SF.GMC
r-·

Octal Value

Symbolic

Meaning

T.UNKO
T.L30S
T.VT05

Terminal type is unknown
Terminal is an LA30
Terminal is a VT05B

t-·

0
4
7

3.3.2.5 IO.GTS - The Get Terminal Support QIO returns a
four-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 ~O.GTS QIO
is itself a SYSGEN option.
If IO.GTS is issued on a m1n1mum 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

Mnemonic

Meaning When Set to 1

Word 0 of Bu :Efer:

12
13
14

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

Fl.ACR
Fl.BTW
Flc.BUF
Fl.UIA
Fl.CCC
Fl.ESQ
Fl .. HLD
Fl .. LWC
Fl.RNE
Fl .. RPR
Fl.RST
Fl.RUB
F'l .SYN
Fl eTRW
Fl.UTB

100000

Fl~VBF

0
1
2
3
4
5
6
7
8
9

10
11

'-""

Word 1 .of Buffer:
0 Ll
l
2

I F2.SCH

Set characteristics QIO (SF.SMC)

~-G_c_H_____G__e_t__c_h_a_r_a_c_t_e__·r__is__t_i_c_s__o_I_o__(_s_F_._G_M_c__) ______________

3-11

HALF-DUPLEX TERMINAL DRIVER

The various symbols used by the IO.GTS, SF.GMC, and SF.SMC QIO's 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.
we recommend that you always use the symbolic names.

Therefore,

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, fot
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
(i.e., 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 via the SF.SMC QIO or the MCR SET /NOECHO command.
See
Table 3-5, bit TC.WEC.}
CTRL/R, if selected as a SYSGEN option,
in progress.

is ignored while an IO.RNE

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

3-12

HALF-DUPLEX TERMINAL DRIVER
3.3.2.8 IO.RPR - ~rhe 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
QIO's. 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 cancelled before the
is written.

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

checkpointed
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.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.RPRlTF.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 octal and 175-177 octal.
The driver does not
interpret the terminating character, with certain exceptions.! 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.

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

3-13

HALF-DUPLEX TERMINAL DRIVER
Upon successful completion
terminated by filling
the
like:

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

Terminating
character
IOSB

IS .SUC&377

# of bytes in buff er
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.GMC, it is called in the following
way:
QIO$C SF.SMC, ••• ,<stadd,size>
where stadd is the starting address of a
buffer
bytes.
Each word in the buffer has the form:

length

"size"

.BYTE characteristic-name
.BYTE value
where "characteristic-name" is one of the symbolic bit names given in
Table 3-5, and "value" is either 0 (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
have any of the values listed in Table 3-6.

"value"

can

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 - IO.WBT instructs the driver to write the buff er
regardless of the I/O status of the receiving terminal.
If an IO .. WBT
is issued on a system that does not support IO.WBT, it is treated as
an IO.WLB.

3-14

HALF-DUPLEX TERMINAL DRIVER

•

If another write is in progress, it finishes and the IO.WBT 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
timeout on IO.WBT.

•

If a read is posted,
the IO.WBT 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 cancelled.

•

Characters input during a break-through write are ignored.

An IO.WBT cannot break through another IO.WBT that is in progress or
if a prompt is being 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.WBT if it is built with
the
/PR:O
switch
specified.
The privileged MCR command BRO
(broadcast) uses IO.WBT.

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

status

block

the

Byte

~---_.._+_1_ _ _ __

~mber of bytes read
means
ret = 0
read terminated by buffer full
1

whe1re:

(byte

count satisfied);
ret

means

IS.CR:

ret

means

IS.ESC: read terminated by an Altmode;

ret

233

means

IS.ESQ: read
terminated
sequence.

rs.sue:

for

successful

read terminated by carriage return;

the return
completion.

code

escape

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.

3-15

HALF-DUPLEX TERMINAL DRIVER
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 zero,
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 QIO's.
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 O) to the byte in error in the QIO's stadd buffer.
Table 3-·8
Terminal Status Returns
Code
IE.EOF

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

rs.sue

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 zeros.
(continued on next page)

3-16

HALF-DUPLEX TERMINAL DRIVER

Table 3-8 (Cont.)
Terminal Status Returns
Code
IE.ABO

Reason
Operation aborted
The specified I/O operation was cancelled by to.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.

IE .BAD

Bad parameter.
The size of the prompt in a
read-after-prompt QIO
is too big (i.e., greater than 255 bytes on systems
supporting variable-length buffers or greater than
80 on systems that do not).

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.
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:
• A timeout
device-unit
lost).

occurred
on
(that is,
an

the
physical
interrupt was

• An attempt was made to perform a
function
on a
remote DHll or DZll line without
carrier present.
(The line is hung up.)
IE. !ES

Invalid escape sequence
An escape sequence was started but escape-sequence
syntax
was
violated before the sequence was
completed.
See Section 3.6.4.
(continued on next page)

3-17

HALF-DUPLEX TERMINAL DRIVER
Table 3-8 (Cont.)
Terminal Status Returns
Code
IE. I FC

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

IE.NOD

Buffer allocation failure
System dynamic storage has been depleted, and there
was insufficient space available to allocate an
intermediate buffer for an input request.

IE.OFL

Device off-line
The physical device-unit associated with the LUN
specified in the QIO directive was not online.
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,
was in progress when an IO.WBT was issued.
Reissue
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
zero 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.FRI.

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

~
!

HALF-DUPLEX TERMINAL DRIVER

3.5

CONTROL CHARACTERS AND SPECIAL KEYS

This section describes the meanings of special terminal cont~ol
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.Sol

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
C~rRL/C

Meaning
Typing CTRL/C
repeatedly
is the way to
terminal's
attention.
Normally,
typing
causes unsolicited input on that terminal
directed to the Monitor Control Routine
"MCR>" echoes when the terminal is ready to
unsolicited input.
When the unsolicited
completes, it is passed to MCR.

get a
CTRL/C
to be
(MCR) •
accept
input

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/C's 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/C's 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 drivero

CTRL/J

Typing CTRL/J is equivalent to typing the LINE FEED
key on the terminale

CTRL/K

Typing CTRL/K initiates a vertical
terminal performs four line feeds.

tab,

and

the

(continued on next page)
3-19

HALF-DUPLEX TERMINAL DRIVER

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

Meaning

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

CTRL/O

Typing CTRL/O suppresses output being sent to a
For attached
terminal
by the current I/O request.
terminals, CTRL/O remains
in effect,
and output
continues
to be suppressed until
any of the
following occurs:
•
•
•
•

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 i ne) •
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 hardcopy 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.

CTR'L/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 ~U followed by a carriage
return and a line feed.
This allows you to
retype
the line.

CTRL/Z

Typing CTRL/Z
indicates
current terminal input.
and other system tasks
complete and the task
echoes this character as
return and a line feed.

3-20

an end-of-file for
the
It signals MAC, PIP, TKB,
that terminal
input
is
should exit.
The system
~z followed by a
carriage

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).
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: I I .
Table 3-10
Special Terminal Keys
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.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.
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 ch~racter 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='rI:
(continued on next page)

3-21

HALF-DUPLEX TERMINAL DRIVER

Table 3-10 (Cont.)
Special Terminal Keys
(Note:
see Section 3.3.2.12 for another way this
SET
can be accomplished,
via 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-backspac~ 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 th~ incomplete input line.

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 one-character Read All's,
but escape sequences allow a
neater way to accomplish it (they can be read with ordinary IO.RLB's).
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.

Definition

3.6.1

An escape sequence is defined as follows:
ESC [int]

•••

[int] fin

where:
ESC

is the result of pressing the ESCape key, a byte (character) of
33 octal.

int

is an "intermediate character" in the range
40 to
57 octal.
This range
includes the character "space" and 15 punctuation
marks.
An escape sequence may contain
any
number
of
intermediate characters, or none.

fin

is a "final character" in the range
60 to 176 octal.
This
range
includes upper- and lower-case letters, numbers, and 13
punctuation marks.

3-22

HALF-DUPLEX TERMINAL DRIVER
There are four exceptions to this general
exceptions are discussed in Section 3.6.5.

3.6.2

definition;

these

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 octal)
may be
used as an Altmode.l This character does not act as an Altmode from a
terminal that cannot generate escape sequences.

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

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

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 and 176 octal, if the terminal has not been declared lower-case
(MCR command SET /LOWER).
If the terminal is lower-case,
then these
characters represent right-brace and tilde, respectively.

3-23

HALF-DUPLEX TERMINAL DRIVER

3.6.4.1 DEL or RUBOUT (177 Octal) - The character DEL or RUBOUT is
not legal within an escape sequence.
Typing it at any point with:in 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.
For example,
if you
enter:
AB ESC

DEL CR

the buffer contains "AB" and the I/O status block looks like:
IOSB

3.6.4.2 Control Characters
(0-37 Octal) - The
reception of
any
character
in the range 0 to
37 octal
(with four exceptions -- see
footnotel) is a syntax violation that terminates the
read with an
error (IE.IES).
For example, enterinq:
ESC 1

CTRL/SHIFT/O

results in a buffer that contains these three characters
status block that looks like:

and

I/O

IOSB

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

with the side effect of turning off the output stream.

3-24

HALF-DUPLEX TERMINAL DRIVER
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
receipt 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
two, and you type:

ESC

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

The "A" is treated as unsolicited input.

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 characters are:
(73 octal),
?
(77 octal), and 0 (117
octal).
The syntax for
escape sequences that contain these four
characters as intermediates is:
ESC

[int]

[int] fin

ESC ? [:int]

[int] fin

ESC 0

[int] f inl

where:

[:int]

int
fin
f inl

=>
=>
=>

40-57
60-176
100-176

octal;
octal; and
octal.

The fourth exception to the general syntax given in section 3.6.1
involves the
"final character"
Y (131 octal). 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 rowpos
where colpos and rowpos are both characters in the range 40-176 octal.
They represent bias-40 numbers:
colpos = 40 corresponds to column O,
etc.

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.

3-25

HALF-DUPLEX TERMINAL DRIVER
Table 3-·ll
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.
Normailly ,.
printing
immediately
follows the previously printed line.

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

PAGE EJECT - Out.put eight 1 i ne feeds
(or,
if
the terminal
is an LA180S,
output a form
feed), print the contents of the buffer,
and
output a carriage return.

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

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.

Meaning

All other vertical format control characters are interpreted as blanks
(octal 40).

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
Installation
Guide,
as appropriate).
Some have been mentioned
previously in the text;
these are:
•

All the device-specific QIO functions

•

Special keys

•

Escape sequences

CTRL/S
Suspend output
CTRL/Q
Resume suspended output
CTRL/R
Write incomplete input buffer
CRT rubout

Other features that you may select at SYSGEN time are described in the
following sections.

3-26

HALF-DUPLEX TERMINAL DRIVER
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

>
(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
(dee ima 1).
The SET /BUF command used without an argument
returns the current buffer width for a terminal:

enquiry

that

>SET /BUF=TI:
BUF=TIO: 0007 2.

>
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 wraparound, 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.
Wraparound
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 wraparound to malfunction.
This can
occur
when
more than 255.
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.
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
(decimal) characters may be read from a terminal.
The terminal driver
allocates an Executive buffer the same size as the read request.

3-27

HALF-DUPLEX TERMINAL DRIVER
If the variable-length option is not chosen, any number of characters
may be read from a terminal, but a maximum of 80 are transferred to
the task
issuing the
read request.
An Executive buffer of 80
characters is always allocated.
Note that, whether variable-length buffering is selected or not,
a
maximum of 80 characters may be directed to MCR as unsolicited input.

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

3.8.4

LA30-P Support

This option provides a 1-byte software buffer for terminal input from
an
LA30-P.
Because
LA30-P's
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-P's in
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 dialin
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).

3-28

~·

HALF-DUPLEX TERMINAL DRIVER
The direct memory access (DMA) capability of the DHll is not supported
by the RSX-llM 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 dialin 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 modem in auto-answer mode.

3.10

PROGRAMMING HINTS

This section contains information relevant to users
driver.

3.10.l

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

HALF-DUPLEX TERMINAL DRIVER
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).
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 one second to succeed.
This is
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
one 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 -- your use of 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

3-30

HALF-DUPLEX TERMINAL DRIVER

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.
~he
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.
A DZll remote line must be declared to be remote before the terminal
driver will correctly handle the modern.
This is done with the MCR
command SET /REMOTE=TI:.
NOTE:
Because of the few modern 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
f rorn
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.
TCoSMR -- If this
characteristic
is
asserted
(that
is,
if
lower/upper-case
conversion
is
disabled by,
for example,
SET
/LOWER=TI:), the two characters 175 and 176 octal are interpreted as [
(right-brace) and
(tilde), respectively.
If TC.SMR is not asserted,
these two characters act as Altrnodes.
That is,
they act as line
terminators that do not advance the cursor to a new line.
Altrnodes
ar~e not echoed.

3-31

HALF-DUPLEX TERMINAL DRIVER
3.10.10

Unsolicited-Input-Character AST's for Tasks Attaching
Several Terminals

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

QIO$C IO.ATA, ••• ,<UICl>
BR CONT
QIO$C IO.ATA, ••• ,<UIC2>
BR CONT

MOV #1,-(SP)
BR UIC
MOV #2,-(SP)
BR UIC

MOV (SP)+,INDEX
~
.

3.10.11

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.Wl\Ls. 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 {E~.g., the terminal does not echo
input characters).
The terminal driver has no
mechanism
for
recognizing the disabling.
Therefore,
it cannot recover.
The bit
must be reset with an MCR OPEN command,
or the console switch
register, or a periodically rescheduled task.

3-32

HALF-DUPLEX TERMINAL DRIVER

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

CHAPTEJR 4
VIRTUAL TERMINAL DRIVER

4.1

INTRODUCTION

The virtual terminal driver supports offspring task use of virtual
terminals :Ln RSX-UM-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 via the Create Virtual Terminal directive. Virtual
terminals are useful in batch processing and other
processing
environments to provide non-interactive 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

Settin9

Record-oriented device

Carriage-control device

Terminal device

File-structured device

Single-directory device

Sequential device

Reserved

User-mode diagnositcs supported

Massbus device

Meanin9

4-1

VIRTUAL TERMINAL DRIVER
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

Meani1~

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:
QIO$C IO.ATT, •••

Attach device

QIO$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
(effects IO.RLB)

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

Write logical block

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

Write virtual block
(effects IO.WLB)

DEVICE-SPECIFIC FUNCTION:
QIO$C IO.STC, ••• ,<cb,sw2,swl>

Set terminal characteristics
(enable/disable intermediate
I/O buffering, or return I/O
completion
status
to
offspring task)

4-2

VIRTUAL TERMINAL DRIVER

Where:
size

is the size of the data buffer
in bytes
(must be
greater than zero).
The buffer must be located within
the addressing space of the parent or offspring task
issuing the I/O request.

st add

is the starting address of the data buffer.

stat

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

defines characteristic bits to become set,
the following virtual terminal functions:
cb Value

swl

selecting

Function

Bits Set

none

Enable
intermediate
buffering
in
the
Executive pool

Return the specified
virtual terminal
I/O
completion status to
the
requesting
offspring task

Disable
intermediate
buffering

is the I/O completion code for I/O completion status.
NOTE
The sw2 and swl parameters are valid
the IO.STC function only when cb=l.

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

•

VIRTUAL TERMINAL DRIVER
4.3.1.3

IO.KIL -- Parent and offspring tasks can issue IO.KIL to
I/O requests. An offspring task issuing IO.KIL can result in
IE.ABO being returned to the parent task.
can~el

4.3.1.4 IO.RLB,
IO.RVS, 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
ignores,
but does not reject,
offspring task IO.WLB and IO.WVB requests containing the vfc
parameter used by terminal drivers described in Chapter 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 or 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.

4.3.2

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 the Executive 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 the Executive pool.
Intermediate buffering, when
enabled, is performed on offspring task virtual terminal read and
write requests when the offspring task:
1.

is checkpointable

is not executing an AST routine

ASTs are enabled

is not already at the stopped state.

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 the Executive pool.
In addition to the conditions that permit intermediate buffering (when
specified),
one
additional condition can automatically disable
intermediate parent task in the Create Virtual Terminal directive
exceeds the maximum size specified at Sysgen time (512(10) maximum).
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

4-4

VIRTUAL TERMINAL DRIVER
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 via the virtual terminal driver.
When used
in
this manner,
the IO.STC
function must
include three parameters
<cb,sw2,swl>, as follows:

"--"

4.4

A value of 1 is specified to
indicate that
the I/O
completion status
return to
the offspring task is
desired.

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

Value

Completion Status Indicated

IS oSUC

Successful completion

IS oCR

Read terminated by carriage
return

ISoESC

Read terminated by an Altmode

IS .. ESQ

233

Read terminated by an escape
sequence

STATUS RETURNS

The error and status conditions listed
in Tables 4-2 and
4-3 are
returned by the virtual terminal driver described in this chapter.

4-5

VIRTUAL TERMHIAL DRIVER
Table 4-·2
Virtual Terminal Status Returns for Offspring Task Requests
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/0
status block
indicates
the
number
of
bytes
transferred on a write operation.

IE. I FC

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

parent

task
~!

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.

4-6

VIRTUAL TERMINAL DRIVER
Table 4-3
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 Sysgen time.

rn .DUN

Device not attachable
An IO.ATT or IO.DET function was issued by the parent
task.

rn. 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
Sysgen time.

~·

4-7

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,
RLOl, and RL02) may be connected to their respective controllers.
Disks and other file-structured media under RSX-llM are divided
logically into a series of 256-word blocks.

5.1.l

RFll/RSll Fixed-Bead 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.
The RFll/RSll
is unique because the hardware can
automatically perform a spiral read across disk platters.

5.1.2

RS03 Fixed-Bead Disk

The RS03 (RH11-RH70 controller/RS03 fixed-head disk) is a
fixed-head
disk which offers speed and efficiency. With 64 tracks per platter,
and recording on one surface, .the RS03 has a capacity of 262,144
words.

5.lo3

RS04 Fixed-Bead 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 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

DISK DRIVERS

Table 5-1
Standard Disk Devices
Controller/
Drive

RPM

Secs

Trks

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

RH11/RP04,RP05 3600

411

87,960,576

171,798

RH70/RP06

3600

815

174,423,040

340,670

RK11/RK05

1500

200

2,457,600

4800

RLll/RLOl

2400

402

256

5,242,880

10,240

RLll/RLO 2

2400

402

512

10,485,760

20,480

RK6 ll/RK06

2400

411

13,888,512

27,126

RK6 ll/RK07

2400

815

27,810,800

53,790

RXll/RXOl

360

263

256,256

494

RX211/RX02

360

263

512,512

988

1 THE RS03 has 64 words per
sector.

sector;

the

RS04

has

128

words

per

·~

2 The RLOl and RL02 each have 128 words per sector.
3 The RXOl has 64 words per
sector.

sector;

the

RX02

has

128

words

per

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,
RLOl, or RL02) may be connected to their respective controllers.
Disks and other file-structured media under RSX-llM are divided
logically into a series of 256-word blocks.

5.1.5

RM02/RM03 Pack Disk

The RM02/RM03 are MASSBUS disk drives and adapters that uses the
existing MASSBUS controller.
With a single-head per surface, they
provide a 1.2 megabyte per second data transfer rate.
The RM03 is
used with the RH70 controller on PDP-11/70 systems.
All other systems
use the RM02 with the RHll controller.

5-2

DISK DRIVERS
5.1.6

RP04, RPOS, RP06 Pack Disks

The RP04 or RP05 (RH11-RH70 controller/RP04 or RP05 pack disk)
disks consist of 19 data surfaces and a moving read/write head.
offer large storage capacity with rapid access time.
The RP06
disk has approximately twice the capacity of the RP04 or RP05.

5.1.7

pack
Both
pack

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 (non-removable) 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.1.10

RXlO/RXOl Flexible Disk

The RXll controller/RXOl flexible disk is an economical storage system
for
low-volume,
random-access storage.
Data is stored in 26 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 one and provides access
to 494 logical blocks.

5.1.11

RX211/RX02 Flexible Disk

The RX211 controller/RX02 flexible disk
is an
random-access storage.
system for
low-volume,

5-3

economical storage
It is capable of

DISK DRIVERS
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 26 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.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the ~et 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.

•

Meaning

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported (device
dependent)

Massbus device device dependent (can be set
for Massbus devices using the RH70 controller)

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 contain thE~ maximum logical block number.
Word 5 indicates the default buffer size, which is 512 bytes for all
disks.

5-4

.$!" _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

DISK DRIVERS
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.
Table 5-2
Standard QIO Functions for Disks
Format

Function

QIO$C IO .. ATT I • • •

Attach device 1

QIO$C I 0 .• D ET I • • •

Detach device

QIO$C IO.KIL, •••

Kill I/O 2

QIO$C IO. RLB, ••• , <s tadd, s i zfe, , bJJkh, p~l<.J>

Read logical block

QIO$C IO.RVB, ••• ,<stadd,si~e,,blkh,blkl>

Read virtual block

QIO$C IO.WLB, ••• ,<stadd,si~e,~blkh,blkl>

Write logical block

QIO$C IO.WLC, ••• ,<stadd,size,,blkh,blkl>

Write logical block
followed by write
check3

IO.WVB,~ •• ,<stadd,size,,blkh,blkl>

Write virtual block

QIO$C

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.PR!
status being returned in the I/O status doubleword.

2 In-progress disk
received,
because
queued when IO.KIL
status is returned

operations are allowed to complete when IO.KIL is
they take such a short time.
I/O requests that are
is received are killed immediately.
An IE.ABO
in the I/O status doubleword.

3 Not supported on RXOl or RX02 flexible disks.
where:

stadd

is the starting address of the data buffer {must be
a word boundary).

size

is the data buffer size in bytes {must be even, greater
than zero, and, for the RP02 and RP03, also a multiple
of four bytes).

blkh/blkl

are 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 eight bits
of the address, and blkl the low 16 bits.

5-5

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.
Table 5-3
Device-Specific Functions for the RXOl,. RX02, RLOl, and RL02

RXOl

Disk Drivers

,Function

Format

QIO$C IO.RPB, ••• ,<stadd,size,,,pbn> Rea.d physical block
QIO$C I 0. 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-6

DISK DRIVERS
wh.e1re:

st add

is the starting address of the data buffer
on a word boundary).

(must

size

is the data buffer size in bytes
greater than zero).

must

even

and

pbn

is the physical block number where
starts (no validation will occur).

the

transfer

density is the media density as follows:
0
2

5.4

single (RXOl-compatible) density
double density

STATUS RETURNS

The error and status conditions listed in Table 5-4
the disk drivers described in this chapter.

are

returned

Table 5-4
Disk 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 zeros.

IS .RDD

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

Hequest 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.
(continued on next page)

5-7

DISK DRIVf:RS

Table 5-4 (Cont.)
Disk Status Returns
Reason

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

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.
(continued on next page)

5-8

DISK DRIVERS
Table 5-4 (Cont.)
Disk Status Returns
Reason
IE: .OFL

IE: .OVR

Illegal read overlay request
A read over~ay 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.

II~ .PRI

Privilege violation
The task which issued the
request
was
not
privileged to execute that request.
For disk, this
code is returned if a nonprivileged task attempts
to
read or write a mounted volume directly (i.e.,
using IO.RLB or IO.WLB).
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
zero was specified.

r:E:. 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 disk,
unrecoverable errors are usually parity errors.

IE .WCK

Write check error
An error was detected
portion of an operation.

IE.WLK

during

the

write

check

Write-locked device
The task attempted to write
physically 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-9

DISK DRIVERS
5.5

PROGRAMMING HINTS

For the RK611 controller/RK06 or RK07 disk, the RLll controller/RLOl
or RL02 disk, RM02 disk and RM03 disk, the driver write-protects the
last track of the cartridge. This track contains the factory-recorded
bad-sector file.

""·
5-10

CHAPTEH 6

DECTAPE DRIVER

6.1

._,..
.

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

•'-".

'-".

INTRODUCTION

GET LUN INFORMATION MACRO

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

§et tins

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Mean ins

"-"
6-1

DECTAPE DIUVER

Bit

sett ins

Device mountable as a communications
channel

Device moun ta1bl e as a FILES-11 volume

Device moun ta1bl e

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-·l
Standard QIO Functions for DECtape

--Format

Function

~
'
I

QIO$C IO.ATT, •••

Attach device 1

QIO$C I 0 .DET, •••

Detach device

QIO$C IO.KIL, •••

Kill I/O 2

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 a~tempt to attach a
mounted volume will result in an IE.PR! 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

DECTAPE DRIVER
where:

stadd

is the starting address of the data buffer
a word boundary).

size

is the data buffer size in
greater than zero).

even

and

lbn

is the logical block number on the DECtape where
transfer starts (must be in the range 0-577).

the

bytes

(must

(must be
be

IO.RVB and IO.WVB are associated with file operations
(see the
IAS/nSX-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~

Device-Specific QIO Functions

6.3.2

•.'-"

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
Function

Format
QIO$C IO.RLV, ••• ,<stadd,size,,,lbn>

Read logical block

(reverse)

QIO$C IO.WLV, ••• ,<stadd,size,,,lbn>

Write logical block

(reverse)

Where:

6.4

stadd

is the starting address of the data buffer
a word boundary).

size

is the data buffer size in
greater than zero).

even

and

lbn

is the logical block number on the DECtape where
transfer starts (must be in the range 0-577).

the

bytes

(must

(must be
be

STATUS RETURNS

The error and status conditions listed in Table 6-3
the DECtape driver described in this chapter.

6-3

are

returned

DECTAPE DIUVER

Table 6-·3
DECtape 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 zeros.

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

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.

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
Code
IE .. NLN

Reason
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

IE.OFL

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 which 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
zero was specified.
(continued on next page)

6-5

DECTAPE DFtIVER
Table 6-3 (Cont.)
DECtape Status Returns
Code
IE.VER

Reason
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
multi-block
transfer past block 577 (1101 octal).

•

The task attempted a
backward
transfer past block zero.

multi-block

Write-locked device
The task attempted to write on a DECtape unit
was physically write-locked.

that

6.4.1 , 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 eight.
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 backward. The next block number in this direction is
96 and 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
eight has been established.

6-6

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
considerat:ions
this chapter.,

6.5 .. l

information
on
important
programming
contains
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
(e.g.,
word 255 becomes word O, 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 per.formed, 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 one second.

selected,

the

~\
'
!

6-8

CHAPTER 7

DECTAPE II DRIVER

7.1

INTRODUCTION

The DECTAPE II (TU58) driver supports TU58 system hardware,
low cost, block replacable mass storage.

7.1.1

providing

TU58 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
is 10
seconds,
average.
All I/O transfers (commands and data) are via 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 8
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

TUSS Driver

The TU58 driver communicates with the TU58 hardware via a serial line
interface
(DLll);
no other interface is required.
All data and
command transfers between the PDP-11 system and the TU58 are via
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 I I .DRIVER

Bit

sett ins

Meaning

Record-oriented device

Carr iage-contr,ol device

Terminal devi c·e

File-structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications

Device mountable as a FILES-11 volume

Device mountable

channe~l

Words 3 and 4 of the buffer are a double prec1s1on 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
the TU58.

7.3.1

de~vice-specific

QIO functions for

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
~"'orma

Function

QIO$C

IO. ATT, •••

Attach device

QIO$C

I 0 .D ET, •••

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

received.
are killed.
where:

7.3.2

I/O

requests

when IO.KIL is
that are queued when IO.KIL is received

stadd

is the starting address of the data buff er
on a word boundary)

(must

size

is the data buffer size in bytes (must
greater than zero)

even

and

lbn

is the logical block number on the cartridge tape
where the data transfer starts (must be in the range
of 0-777)

Device-Specific QIO Functions

The device-specific QIO system directive functions that are valid
the TU58 are shown in Table 7-2.

for

Table 7-2
Device-Specific QIO Functions for the TU58
Function

For.mat
QIO$C IO.WLC, ••• ,<stadd,size,,,lbn>

Write
check

logical

block

with

QIO$C IO.RLC, ••• ,<stadd,size,,,lbn>

Read logical
check

block

with

QIO$C IO.BLS, ••• ,<lbn>

Position tape

QIO$C IO.DGN, •••

Run internal diagnostics

where:

stadd

is the starting address of the data buffer
on a word boundary)

(must

size

is the data baffer size in bytes (must
greater than zero)

even

and

lbn

is the logical block number on the cartridge tape
where the data transfer starts (must be in the range
of 0-777)
7-3

DECTAPE II DRIVER
Additional details for device-specific QIO functions are
the following paragraphs.

provi~ed

7.3.2.l 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 TU58'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
to position the tape to the specified logical block number.

purposes

~'
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 via the I/O status
block.

7.4

STATUS RETURNS

Table 7-3 lists the error and status conditions that are
the TU58 driver.

returned

Table 7-3
TU58 Driver 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.

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.

(continued on next page)

7-4

DECTAPE II DRIVER
Table 7-3 (Cont.)
TU58 Driver Status Returns
Code

Reason

IE. FHE

Fatal hardware error

IE .TMO

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

Table 8-1
Standard Magtape Devices

TElO,TUlO
Channels

9 (TElO)
7 or 9 (TUlO)

TE16,TU16

TU45

TU77

TS04

TS03

Recording densi t.y For 7-channel:
(frames/inch)
200, 556, or
800
For 9-channel:
800

800 or 1600

800

1600

Tape speed
45
(inches/secon d)

125

Maximum data
Transfer rate
(bytes/second )

36,000

For 800 bpi:
36,000
For 1600 bpi:
72,000

For 800 bpi:
60,000
For 1600 bpi:
120,000

12,000
For 800 bpi:
100,000
For 1600 bpi:
200,000

Recording metho d

NRZI

NRZI or
Phase
Encoding

72,000

NRZI
Phase
Encoding

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 non-return-to-zero,
inverted (NRZI).

8-1

MAGNETIC TAPE DRIVERS

8.1.2

TE16/TU16/TU45/TU77 Magnetic Tape

The TE16/TU16/TU45/TU77 consist of an RH11/RH70 controller, a TM02 or
TM03 formatter,
and a TE16/TU16/TU45/TU77 transport.
They are quite
similar to the TElO/TUlO but are Massbus devices,
with a
common
controller, a specialized formatter, and a drive.
Recording is either
800 bpi NRZI or 1600 bpi phase-encoded (PE).

8.1.3 TS04 Magnetic Tape
The TS04 tape system consists of a TSll controller and a TS04
integrated drive,
controller,
and formatter.
The TS04 hardware is
microprocessor-controlled for all operations, including I/O transfers,
tape motion,
(etc.),
and comprehensive
(internal) diagnostic test
execution.
Recording is 1600 bpi phase-encoded (PE).

8.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 magtapes.
A bit setting of 1
indicates that the
described characteristic is true for magtapes.
Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

0 or 1

User-mode diagnostics supported!

0 or 1

Massbus device (set only for TE16, TU16, TU45
or TU77 drives interfaced via an RH70
controller)l

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Device mountable as a communications
channel

Meaning

1 SYSGEN and device-dependent characteristic

8-2

MAGNETIC TAPE DRIVERS
Bit

Meaning

Setting

0 or 1

Device mountable as a FILES-11 volumel

0 or 1

Device mountablel

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.

8.3.l

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

Q IO$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)

where:

stadd

is the starting address of the data buffer {must be
a word boundary).

size

is the data buffer size in bytes. Size must be even,
greater than zero, and, for a write, must be at least
14 bytes.

IO.KIL does not cancel an in progress request unless
has occurred.
1

SYSGEN and device-dependent characteristic

8-3

select

error

MAGNETIC

TAPJ~

DRIVERS

Device-Specific QIO Functions

8.3.2

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

IO.RLV - A TE16, TU16, TS04, TU45, or TU77 in performing a
read
reverse, decrements its bus address register.
The net effect is
that data are not inverted in memory locations (as is the case for the
DECtape driver).
Thus, the data appear in the specified buffer in an
identical fashion as with IO.RLB or IO.RVB.

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
(e.g.,
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.EOF, •••

Write end-of-file mark

QIO$C IO.ERS, •••

Erase
only)

(tape mark)

('I'El6, TU16, TU45, TU77, TS04

QIO$C IO.RLV, ••• ,<stadd,size> Read logical block reverse (TE16, TU16,
TU45, TS04, and TU77 only).
QIO$C IO.RWD, •••

Rewind unit

Q IO$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

8-4

MAGNETIC TAPE DRIVERS

where:

represents the characteristic bits to set.

nbs

is the number of blocks to space
forward, negative if reverse).

past

(positive

nes

is the number of EOF marks to space past
forward, negative if reverse).

(positive

size

is the size of the stadd data buffer in bytes (must
an even number of bytes greater than zero).

stadd

is the starting address of the data buffer
byte boundary).

(may be on a

8.3.2.4 IOeERS - The TE16, TU16, TU45, TU77, or TS04 will erase
3-inches of
(write blank)
tape.
Effectively,
this provides an
extended interrecord gap.

8.3 .. 2.5 IO.SEC - This function returns the tape characteristics in
the second I/O status word.
The tape characteristic bits are defined
a s f: o 11 ow s :

Bit

Can Be Set by
IO.SMO and IO.STC

Meaning When Set

For TUlO, 556 bpi
density (seven-channel).
For TE16, TU16, TU45, TU77, and
TS04, reserved.

For TUlO, 200 bpi
density (seven-channel).
For TE16, TU16, TU45, TU77, and
TS04, reserved.

For TUlO, core-dump
mode (seven-channel, see below).
For TE16, TU16, TS04, TU45 and
Tu77, reserved.

Even parity (default is odd).
(Not selectable for the TS04.)

Tape is past EOT.

Last tape command encountered
EOF (unless last command was
backspace).

Writing is prohibited.

Writing with extended interrecord gap is prohibited
(i.e., no recovery is attempted
after write error).

8-5

MAGNETIC TAPE: DRIVERS

Can Be Set by
IO.SMO and IO.STC

Bit

Meaning When Set

Select error on unit.

Unit is rewinding.

Tape is physically write-locked.

For TElO, TUlO, and TS03, reserved.
For TE16, TU16, TU45, TU77, and TS04,
1600 bpi, density.

For TUlO, drive is seven-channel.
For TE16, TU16, TU45, TU77, and
TS04, reserved.

Tape is at load point (BOT).

Tape is at end-of-volume

Tape is past EOV (reserved for driver;
always 0 when read by user) .

(EOV).

In core-dump mode (TUlO only, 800 bpi density,
and seven-channel),
each eight-bit byte is written on two tape frames, four bits per
frame.
In other modes on seven-channel tape, only six low-order bits
per byte are written.
For the TS04, 1600 bpi density is always selected (bit 11=1).
Bit 11
cannoi be modified by either the IO.SMO 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.
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-6

MAGNETIC TAPE DRIVERS

SET EVEN
PARITY

yes

SET 800 BPI,
NINE-CHANNEL

yes

SET 556 BPI,
SEVEN-CHANNEL

yes

SET 800 BPI,
SEVEN-CHANNEL,
CORE-DUMP MODE

yes

SET 200 BPI,
SEVEN-CHANNEL

yes

BP~

SET 800
SEVEN-CHANNE__:_j

Figure 8-1

Determination of Tape Characteristics for the TElO/TUlO

8-7

MAGNETIC TAPE DRIVERS

SET 1600 BPI ___
ye_s_ _ _-<

SET 800 BPj

yes

Figure 8-2

SET
EVEN PARITY

Determination of Tape Characteristics
for the TE16/TU16/TU45/TU77

8.3.2.6 IO.SMO - This function can be used as a combination of the
sense
(IO.SEC)
and set
(IO.STC)
t.ape characteristics functions.
Unlike IO.STC, however, the IO~SMO f.unction 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 has
not been loaded properly on the drive.

8.4

STATUS RETURNS

The error and status conditions listed in Table 8-4
the magtape drivers described in this chapter.

8-8

are

returned

MAGNETIC TAPE DRIVERS
Table 8-4
Magtape 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 8 the
number
of
bytes processed,
if the operation
involved reading or writing.
This code is also
returned if nbs equals zero in an IO.SPB function
or if nes equals zero 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 zeros.

IE: .ABO

Operation aborted
The specified I/O operation was cancelled via
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.

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

H:.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: .DAO

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.
(continued on next page)

8-9

MAGNETIC T.APJ!: DRIVERS

Table 8-4 (Cont.)
Magtape Status Returns
Code
IE.DNA

Rc~ason

Device not attached
The physical device unit specified
in an IQ.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.EQF

•

A timeout occurred on the physical
(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)

•

A tape position or hardware error occurred for
which no recovery procedure is possible.
(Also
occurs if bit 7 in u.cw2, or IQ.X, becomes set.)

space,

device

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 ten-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.
EQT
is
not returned on a
read
operation.

IE.EQV

End-of-volume encountered
On a
forward
space
function,
the
logical
end-of-volume was encountered. An end-of-volume is
two consecutive end-of-file marks
(EQF),
or a
beqinning-of-tape mark
{BOT) ~followed by an EOF.
The tape is normally left positioned between the
two marks.
(continued on next page)

8-10

_._,

____________________

MAGNETIC TAPE DRIVERS
Table 8-4 (Cont.)
Magtape Status Returns
Code
IE.FHE

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

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 zero 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.
Alternately,
tape
characteristic bit 6 was set by the software to
write-lock the unit logically.

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 spaced over. The
EOF mark counts as one block.
If an EOF mark is encountered by a read
operation, the second I/O status word will contain an octal 2.

8-11

MAGNETIC TAPE DRIVERS
8.4.1

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

Where n is 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 (e.g., vertical parity error),
the
recovery procedure depends on the type of magtape in use. A bad tape
error on a TElO, TUlO, or TS03 results in an immediate return of the
error code IE.VER.
All other read errors for these devices and the
TE16, TU16, TU45, and 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.
The TS04 attempts to recover from read errors by alternately reading
reverse and forward (up to 16 attempts, maximum). During the next 8
attempts, the driver precedes each read attempt by positioning the
tape under the clean heads.
If the error persists after 24 retries
have been executed, IE.VER is returned.
Write recovery is the same for all devices. When a write operation
fails,
the driver attempts to avoid the bad spot on the tape by means
of an extended interrecord gap (IRG). This means that it backspaces,
makes the IRG
just before the record three inches longer, and then
retries the write.
If the error persists after nine 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

Powerfail 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
online.
To prevent accidental destruction of data currently on tape,
the
driver maintains a powerfail 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 powerfail 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 powerfail indicator is set.
These
functions, however, will not clear the bit.

8-12

MAGNETIC TAPE DRIVERS
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 powerfail 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.
It is more reasonable, however, to work
with a block size of approximately 2,048 bytes.

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 thH 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 magtape unit to be
the magtape driver recognizes this fact within one second.

8.5.4

Writing an Even-Parity Zero-NRZI

If an even-parity
drive as blank
this conversion
even-parity zeros

8.5.5

selected,

zero were written normally, it would appear to the
tape.
It is therefore converted to 20 (octal).
If
is undesirable,
the user must ensure that
no
are output on the tape.

Density Selection

The TM03 controller
imposes
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
IOQSEC function can be used to determine (sense) tape density.

8-13

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
infc>rmation for cassettes.
A bit setting of l
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

Reserved

User-mode di.agnostics supported

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Mean ins

'-"
9-1

CASSETTE DRIVER
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;
default buffer size, for cassettes 128 bytes.

9.3

word

indicates

the

QIO MACRO

This section summa~izes 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 buff er contents tC>
tape)

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

Write virtual block
(write buffer contents tc>
tape)

where:

stadd

is the starting address of the data buffer (may be on a
byte boundary).

size

is the data buffer size in bytes (must be greater
zero).

IO.KIL does not affect in progress-requests.

9-2

than

CASSETTE DRIVER

Device-Specific QIO Functions

9.3.2
-~

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

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
Function

Format

where:

.._,..

QIO$C IO. EOF I • • •

Write end-of-file gap

QIO$ c IO • RWD I • • •

Rewind unit

QIO$C IO.SPB, ••• ,<nbs>

Space blocks

QIO$C IO.SPF, ••• ,<nes>

Sp.ace files

nbs

is the number of blocks to space
forward, negative if reverse) •

past

(positive

nes

is the number of EOF gaps to space
forward, negative if reverse).

past

(positive

Table 9-3
Cassette 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, or the number of
blocks or files spaced, if the operation involved
spacing blocks or files.

I:S.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 zeros.
(continued on next page)

9-3

CASSETTE DRIVER
Table 9-3 (Cont.)
Cassette Status Returns
Reason

Code
IE.ABO

Operation aborted
The specified I/O operation was cancelled
IO • K I L wh i 1 e st i l 1 i n the I IO queue •

IE.DAA

via

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:

IE.EOF

•

The cassette has not been physically inserted.

•

The unit is off-line.

•

A timeout occurred on the physical
(that is, an interrupt was lost).

device

unit

End-of-file encountered
An end-of-file gap was recognized on the cassette
tape.
This code is returned
if an EOF gap is
encountered during a read or
if the cassette is
physically removed during an I/O 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 rewrite the block on another cassette
in its entirety.

~·
!

(continued on next page)

9-4

CASSETTE DRIVER
Table 9-3 (Cont.)
Cassette Status Returns
Code

Reason

IE.IFC

Illegal function
A function code was specified
that is illegal for cassette.

IE.OFL

I/O

request

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
zero 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 two-byte value located at the end of
each block, is a checksum that is tested d~ring 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.WLK

Write-locked device
The task attempted to write on a cassette unit that
was physically write-locked.
This code may be
returned after an IO.WLB,
IO.WVB,
or
IO.EOF
function.

9.4.1

Cassette Recovery Procedures

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

CASSETTE DRIVER
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, jnterrecord 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
EOT

BOT

\ - - - - - -..........- - - - - - '

\...._-....----_J '---'

FILE 2

FILE 1

LEOT

150 FEET

Figure 9-1

Structure of Cassette Tape

Abbreviation

9.6

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)

EOF

End-of-file gap

IRG

Interrecord gap

SLR

Sentinel label record

LEOT

Logical end-of-tape

EQT

Physical end-of-tape

Clear trailer

driver

PROGRAMMING HINTS

This
sect ion
considerations
this chapter.

contains
information
on
important
programming
relevant to users of the cassette driver described in

9-6

CASSETTE DRIVER
9.6.l

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

9.6.2

End-of-File and IO.SPF

The hardware senses end-of-file (EOF) as a timeout.
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 (i.e., 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 IOoSPB in reverse for one block.

9.6.3

The Space Functions, IO.SPB and IO.SPF

IO.SPB always stops in an IRG, IO.SPF in an EOF gaps.
Neither space
function actually takes effect until data 1s 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.6.4

Verification 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 as
verification of 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.6fi6

Logical End-of-Tape

The conventional method of signaling logical end-of-tape by multiple
EOF gaps
is inadequate for cassettes.
This is 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-7

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

"'-"
Meiael

Column Width

Character Set

Lines per Minute

LPll-F

170-1110

LPll-H

170-1110

LPll-J

132

170-1110

LPll-K

132

170-1110

LPll-R

132

1110

LPll-S

132

1110

LPll-V

132

300

Ll?ll-W

132

300

LSll

132

60-200

LVll

132

500

Ll\180

132

150

10.1.l

LPll Line Printer

The LPll is a high-speed line printer available in a variety of
models.
The entire LPll model line consists of impact printers, using
one hammer per column and a
revolving drum with upper-case and
optional lower-case characters.
The LPll-R and LPll-S are fully
buffered models which operate at a standard speed of 1110 lines per
minute. The other LPll 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 which exceed this maximum are
printed at a slower rate.
Forms with up to six parts may be used for
multiple copies.

10-1

LINE PRINTER DRIVER
LSll Line Printer

10.l.2

The LSll is a mediu~-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.

LVll Line Printer

10.1.3

The LVll is a
fully-buffered,
electrostatic printer-plotter which
operates at a standard rate of 500 lines per minute. RSX-llM supports
only the LVll print capability, not the plotter mode.

LA180 DECprinter

10.1.4

The LA180 is a 180-character/sec, dot-matrix impact printer.
accepts multipart forms and pages of various lengths and widths.

10.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 line printers. A bit setting of 1 indicates that the
described characteristic is true for line printers.
Bit

Settin9

Record-oriented device

Carriage-control device

Terminal dev:lce

File structured device

Single-directory device

Sequential

Reserved

User-mode diagnostics supported

Massbus device

Unit

Input spooled device

Output

spoolE~d

Pseudo

devicE~

Device mountable as a communications channel

Device mountable as a FI LES-11 volume

Device mountable

Meanin9

dE~vice

softwan~

10-2

write-locked

device

LINE PRINTER DRIVER
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.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, •••

Attach device

QIO$C IO.DET, ....

Detach device

QIO$C IO.KIL, ....

Cancel I/O requests

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

Write logical block
{print buff er contents)

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

Write virtual block
{print buffer contents)

where: stadd

is the starting address of the data buffer {may be on a
byte boundary).

size

is the data buffer size in bytes {must be greater
zero).

vfc

is a vertical format control character from Table 10-4.

than

IO.KIL does not cancel an in progress request unless the line printer
is in an offline 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.

10-3

LINE PRINTER DRIVER
Table 10-3
Line Printer 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 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 zeros.

IE.ABO

Operation aborted
The specified I/O operation was cancelled while in
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.

IE.OFL

I/O

request

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
the issuing task.
Alternately, a
byte count of
zero was specified.

10-4

LINE PRINTER DRIVER
10.4.1

Ready Recovery

I f any of thE! following conditions occur:

• Paper jam
• Printer out of paper
• Pr:inter 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
wheire n is the unit number of the line printer that is not ready.
The
driver retries the function which 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.
Table 10-4
Vertical Format Control Characters
Octal
Value

Character

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 b~ffer,
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.

Cl 53

plus

OVERPRINT:
print the contents of the buffer
and
perform a
carriage return,
normally
overprinting the previous line.

'-""'

Meaning

(continued on next page)

10-5

LINE PRINTER DRIVER
Table 10-4 (Cont.)
Vertical Format Control Characters
Octal
Value

Character

044

dollar
sign

PROMPTING OUTPUT: output a line feed
then print the '::::ontents of the buffer.

000

null

buffer
VERTICAL
INTERNAL
FORMAT:
the
contents are printed without addition ()f
vertical format control characters. In th:ls
mode,
more than one line of guarantec~d
contiguous output can be printed per I/O
request.

Meaning
and

All other vertical format control characters are interpreted as blanks
(octal 040)."'

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

Print Line Truncation

If the number of characters to be printed 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 examining
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 one second.

10-6

CHAPTER 11

CARD READER DRIVER

INTRODUCTION

11.1

The RSX-llM card reader driver supports the CRll card reader.
This
reader
is a virtually jam-proof device which 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 which 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.
It has a very short card
track, so only one card is in motion at a time.

GET LUN INFORMATION MACRO

11.2

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

Settir!_9

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported

Massbus device

Unit software write-locked

Input spooled device

Output spooled device

Pseudo device

Mean ins

'-""'
11-1

CARD READER DRIVER

Bit

Setting

Device mountable as a communications
channel

Device mountable as a FI LES-11 volume

Device mountable

Meaning

Words 3 and 4 of the buffer are undefined;
word 5 indicates
default buffer size, which is 80 bytes for the card reader.

QIO

11.3

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

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)

where:

stadd

is the starting address of the data buffer (may be
a byte boundary).

size

is the data buffer size in bytes (must be greater than
zero).

IO.KIL does not cancel an in progress request unless the card
reader
is in an offline condition because of a pick, read, stack or hopper
check, because of power failure, or because the RESET button has not
been depressed.

11.3.2

Device-Specific QIO Function

The device-specific function of the QIO macro that is
card reader is shown in Table 11-2.

11-2

valid

for

the

CARD READER DRIVER
Table 11-2
Device-Specific QIO Function for the Card Reader

Forma._t~----------------------~-~--~------F_u_n_c_t

[

__i_o_n________

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

whe :re:

11.4

~--~-1

Read logical block (binary)

stadd

is the starting address of the data buffer (may be
a byte boundary).

size

is the data buffer size in bytes (must be greater than
zero) •

STATUS RETURNS

There are a wide variety of error conditions and
recovery procedures
related to the use of the card reader.
This section describes the
three major ways in which the system reports error conditions.
l.

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

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.

try

the

•

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.

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 one 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 which might be encountered while reading cards and
recovery
procedures associated with these error conditions.

CARD READER DRIVER
Table 11-3
Card Reader Switches and Indicators
Recovery

Indicator

Description

Action

POWER
switch

pushbutton
indicator
switch
(alternate
action:
pressed for
both ON and
OFF)

Card may have been
read incorrectly;
restore power if
possible by depressWhen indicator is
ing the POWER
off, depressing switch switch; insert the
card again as the
applies power to
first card in the
reader and causes
input hopper, and
associated indicapress the RESET
tor to light.
switch; in some
cases, it may be
When indicator is
necessary to
lit, depressing
restart the program.
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 0
or 81.

Controls application
of all power to the
card reader.

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

CARD READER DRIVER
Table 11-3 (Cont.)
Card Reader Switches and Indicators
Indicator

Description

STACK
CHECK
indi.cator

white light

Action
When lit, this light
indicates that the
previous card was not
properly seated in
the output stacker
and therefore may be
badly mutilated.
Stops card reader
operation and extinguishes RESET
indicator.

Recovery
Card may have been
read incorrectly and
is not positioned
properly in the output stacker; duplicate the card if it
is damaged; insert
the card again as
the first card in
the input hopper and
press the RESET
switch.

HOPPER
CHECK
ind:icator

white light

Card may have been
When lit, this light
indicates that either read incorrectly;
empty the stacker or
the input hopper is
empty or that the out- fill the hopper; insert the card again
put stacker is full.
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
light)

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
STOP switch is depressed or whenever
an error indicator
lights (READ CHECK,
PICK CHECK, STACK
CHECK, or HOPPER
CHECK).
11-5

CARD READER DRIVER
11.4.2

Ready and Card Reader Check Recovery

If any of the following conditions occurs:
e

POWER failure

•

Reset switch not pressed (reader offline)

•

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

When a timing error occurs, the operator can proceed with normal
reader operation by:

card

*** CRn: -- NOT READY

Placing the card reader offline by pressing the STOP switch,

Removing the last card read and insert it where
the next card read, and

Placing the card reader online by pressing the RESET switch.

will

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

I/O

Status Conditions

The error and status conditions listed in Table 11-4 are
the card reader driver described in this chaptera

11-6

returned

CARD READER DRIVER
Table 11-4
Card Reader 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.

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

rn .ABO

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

rn .DAA

Device already attached
The physical device unit specified in an IO.ATT
function was already attached by the issuing task.

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

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

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

Reason

IE .OFL

Device off-line
The physical device unit associated with the LUN
specified in the QIO direct~ve 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. Alternately, a byte count of
zero 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.
Table 11-5
Card Reader Control Characters
Punches
12-11-0-1-6-7-8-9
12-11-0-1-6-7-8-9

Columns

Meaning

End-of-file (alphanumeric)

(all 8 punches in
the first 8 columns)

End-of-file (binary)

12-2-4-8

026-coded cards follow

12-0-2-4-6-8

029-coded cards follow

11-8

CARD READER DRIVER
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
effE~ct even when the reader is attached and subsequently detached.
The default condition can easily be changed from DEC026 to DEC029 by
reading an 029 control card, and then saving the system with the MCR
SAV command.

11.6

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

11. 7

PROGRAMMING

HINTS

This
section
contains
information
considerations relevant to users of the
in this chapter. Section 11.4 contains
error-recovery procedures which might be
point of view.

11.7.l

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 columns, 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.
The user can specify that only the first 10
columns, for example, of each card are to be read.

11.7.2

Aborting a Task

If a task which is waiting for
the
aborted,
the card reader driver
second.

11-9

card reader to
recognizes this

be readied is
fact within one

CARD READER DRIVER
Table 11-6
Translation from DEC026 or DEC029 to ASCII

Character

SPACE
!
II

$
%

AND

(
)

+
:
i

<
=

>
?
@

A
B

c
D
E
F
-G
H

I
J
K
L

NonParity
ASCII

DEC029

DEC026

Character

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

12 0
11 0
none
12 8 7
8 7
8 3
11 8 3
0 8 4
12
8 5
12 8 5
11 8 5
11 8 4
12 8 6
8 2
11 8 6
12 8 4
8 6
0 8 6
0 8 7
8 4
12 1
12 2
12 3
12 4
12 5
12 6
12 7
12 8
12 9
11 1
11 2
11 3

12 0
11 0
none
12 8 7
0 8 5
0 8 6
11 8 3
0 8 7
11 8 7
8 6
0 8 4
12 8 4
11 8 4
12
11 8 2
0 8 2
12 8 6
8 3
11 8 6
12 8 2
8 4
12 1
12 2
12 3
12 4
12 5
12 6
12 7
12 8
12 9
11 1
11 2
11 3

'
-

0
1
2
3
4
5
6
7
8
9
M

N
0
p

Q
R

w
x
y

z
[

]
""

11-10

•

- or

NonParity
ASCII

DEC029

DEC026

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

0 8 3
11
12 8 3
0 l
0
1
2
3
4
5
6
7
8
9
11 4
11 5
11 6
11 7
11 8
11 9
0 2
0 3
0 4
0 5
0 6
0 7
0 8
0 9
12 8 2
o a· 2
11 8 2
11 8 7
0 8 5

0 8 3
11
12 8 3
0 l
0

l•

2
3
4
5
6
7
8
9
11 4
11 5
11 6
11 7
11 8
11 9
0 2
0 3
0 4
0 5
0 6
0 7
0 8
0 9
11 8 5
8 7
12 8 5
8 5
8 2

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

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) communicati6ns devices

•

Multicomputer (message-oriented) communications devices

Chapter 1, 2 and 3 describe the character-oriented asyncnronous
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 (i.e., they are supported via 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 driveFs 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 via the Assign LUN system directive, at
task build,
or via 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)

Synch.
Character

32K

programmable

2-19.2

32K

programmable

Serial, synchronous

2.4-1000

32K

programmable

Du11l

Serial, synchronous

0.05-9.6

32K

programmable

DUPll

Serial, synchronous

0.05-9.6

32K

programmable

DAll-81

Parallel

DLl l-E2

500

Serial, asynchronous

0.05-9.6

DMCll

Serial, synchronous

19.2-1000

DPlll

Serial, synchronous

DQlll

1 Support is not provided on RSX-llM-PLUS systems.
2 DLll-E support is provided on
full-duplex terminal driver only.

12.1.1

RSX-llM-PLUS

systems

using

the

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
w~rd 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 asynchronoust 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.3

3 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 SK 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 which 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 which 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
DUPll Synchronous Line Interface

12.1.7

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

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supported

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

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
1 2 •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
Q1I0$C IO.ATT, •••

Attach devicel

QIO$C IO.DET, •••

Detach device

CHO$C IO.KIL, •••

Cancel I/O requests

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

Read logical block
sync)

(stripping

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

Write logical block
syncs)

(preceded by

1 Only unmounted channels may be attached.
An attempt to attach a
mounted channel will result in an IE.PR! status being returned in the
I/O status doubleword.
whE~re:

stadd is the starting address of the data buffer
byte boundary).
size

12.3.2

(may be on a

is the data buffer size in bytes (must be greater
zero).

than

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
Format

Function

QIO$C IO.FOX

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.

QIO$C 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.

where:

and

set

stadd is the starting address of the data buffer (may be on a
byte boundary).
size

is the data buffer size in bytes (must be greater
zero).

syn

is the sync character, expressed as an octal value.

stat

is the station assignment (primary or secondary).

mode

is the transmission mode

than

(normal or maintenance).

The device-specific functions listed in Table 12-3
greater detail below.

are

described

12.3.2.1 IO.FDX - 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.FOX 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-6

MESSAGE-ORIENTED COMMUNICATION DRIVERS
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 zero indicates primary
station and a non-zero 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 zero selects normal mode and a non-zero 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 is used to read a
logical
block of data, without stripping the sync characters which may precede
the data.
A similar function is IO.RLB, which is non-transparent,
in
that it causes sync characters preceding the data message to be
stripped.
IO.RLB is used at the start of a segmented data request, in
which the block might have the following layout:

[SJ s

H ..__H_.._H_ _._l_c_s__,l.__c_s__.________D_A_T_A_ _ _ _l _c_s__,I

where:

S is a sync character
H is a header character
CS is a validity check character

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
latE~r 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.FOX to set the characteristics of the physical device unit.

12-7

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12.3.2.6 IO.WMS - 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 e>ther
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
He a son

Code

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

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

IE .BCC

Block check error
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
match, and represents a transmission error.

IE.CNR

Connection rejected
(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.
(continued on next page)

12-8

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 12-4 (Cont.)
Communication Status Returns
Code
IE:.DAO

Reason
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 (i.e., 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:

IE. I FC

•

The physical device unit could not be initialized
(i.e., 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 timeout period.
This timeout 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 timeout 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.

Illegal function
A function code was specified in an I/O request that
is
illegal
for
me~sage-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.
Alternately, a byte count of zero was
specified.
(continued on next page)

12-9

MESSAGE-ORIENTED COMMUMICATION DRIVERS
Table 12-4 (Cont.)
Communication Status Returns
Code

RE!ason

IE.VER

Nonrecoverable error

(D.lUl-B only)

The data transfer terminated before all of the data
The error code is returned on
has been transmitted.
transmit when both systems attempt to transmit at the
This condition is detected by the device
same time.
The error co die is returned on receive when
protocol.
the transmit data count of the transmitting side does
receive
not equal the data count specified by the
QIO.

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 which
is
clo~ked
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 which receives the message
can determine whether or not 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 which
receives a communication can determine whether or not 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.
Both DQll and DUPll incorporate hardware to compute a CRC.
CRC hardware requires an extra system unit.

12-10

______ ___________________
,

The

DQll

MESSAGE-ORIENTED COMMUNICATION DRIVERS
12.5.3

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,
DMClJL, DPll, DQll, DUll, and DUPll. The mode is settable by using
IO.FOX 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.
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
drivj~r
gives the first seven transmits (or receives) directly 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:
1 for base
table(s), 2 for active transmits, and 2 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"
(i.e.,
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 via 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, DLll-E, DPll, DQll, or
DUll. Codes are assumed to be eight-bit only.

12.5.6

Powerfail with DMCll

The DMCll currently cannot recover after a power failure.
This is
because the RAM in its internal microprocessor is erased when power
fails.
Any I/O requests outstanding at the time of a power failure

12-11

MESSAGE-ORIENTED COMMUNICATION DRIVERS
will
return
IE.ABO.
These
initializing the DMCll (IO.INL).

12.5.7

requests

must

reissued

after

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.
Tasks sending messages to the DMCll should begin by terminating and
reinitializing the device
(IO.TRM,IO.INL) .I
IO.INL must be issued
after each IO.KIL
(which effectively kills the
DMCll),
after
powerfail, 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

#1,#"XP,#0
USE LUNl FOR DPll
#IO.HDX!IO.SYN,#l,,,,,<#226>
SET DEVICE PARAMETERS
#IO.INL,#1
; PUT DEVICE ON LINE
#IO.WLB,#l,,,#TXSTS,#TXAST,<#TXBUF,#100>; SEND A BLOCK

CMPB

#IS.SUC&377,@(SP)+

BEQ

10$

WAS DATA CLOCKED OUT
SUCCESSFULLY?
IF SO, SET UP FOR NEXT
BLOCK

1 Note that this will cause the error IE.CNR to be returned on any I/O
outstanding on the other end of the line.

12-12

CHAPTER 13
PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

13.1

INTRODUCTION

PCLll Parallel Communications Link
hardware
is
supported
on
RSX-llM-PLUS systems via 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 TDM bus to a receiver
sect.ion 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
sect.ion 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 TDM 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 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 ackowledge a
transmitter when a data transmission is requested by that transmitter.
Subsequent requests by other transmitters on the TDM bus are
ignored

13-1

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
until all
completed.

message

transactions

with

the

current

transmitter are

GET LUN INFORMATION MACRO

13.2

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

Meaning

Record-or i e~nted device

Carriage-control device

Terminal de!Vi ce

File-structured device

S inqle-di re!ctory device

Sequential device

Reserved

User-mode diagnostic supported

Massbus device

Unit softwc:1re write-locked

Input spooled device

Output spooled device

Pseudo device

, 3

Device mountable as a communications channel

Device mountable as a FILES-11 volume

Device mountable

Word 3 contains device

driv~r-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 b~te 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:

13-2:

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS

Meaning
0

No task is connected

Task connected but not triggered

Task triggered and waiting for IO.RTF
function

Task triggered and timed out
IO.RTF or IO.ATF function

-2

IO.ATF function in progress

-4

Task connected, not triggered, and has an
function in proqress

-6

An IO.RTF function is in proqress

while

IO.ATF

waiting

for

IO.ATF

The high byte of word 3 is undefined.
Word 4 is undefined.
Word 5 is the default buffer size in bytes.
the PCLll, this value is 64 bytes.

13. 3

13.3.1

For

QIO MACRO -- PCLll TRANSMITTER. DRIVER FUNCTIONS

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

13.3.2

Format

Function

QIO$C I 0 .ATT, •••

Attach device

QI0$C I 0 .DET, •••

Detach device

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

13-3

PCLll PARALLEL COMMUNICA'rIONS LINK DRIVERS

Table 13-.2
Device-Specific QIO Functions for PCLll Transmitters
Format

Function

QIO$C IO.ATX, ••• ,<stadd,size,
flagwd,id,retries,retadd>

Attempt message transmission

QIO$C I 0. SEC, ••• ,

Sense master section status

QIO$C IO.STC, ••• ,<stadd,size,
[state], [mode],, retadd>

Set master section characteristics

Where:
st add

(its
is the starting address of a data buff er
description
and
function
is dependent upon the
specific QIO function).

size

is the data buffer size in bytes (its description and
function is dependent upon the specific QIO function).

f lagwd

is the value of the f lagword which is to precede the
message being sent.
The flags specify the desired
receiver function as defined by the user's protocol.

is 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, etc.

retries

is 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

is the starting address of a 7-word buffer into which
the contents of the 6 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

is the desired state setting for the
follows:
Parameter
specified

transmitter,

State

SS.MAS

TOM bus master

SS.NEU

Neutral

13-4

(default state)

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
mode

is the desired mode setting for allocating transmitter
timeslices on the TDM bus, as follows:
Parameter
entered

Mode

MS .AUT

Auto addressing (default mode)

MS .ADS

Address silo

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
fol lows:

J Status Code
Current TMMR Contents

NOTE
The optional isb parameter
1.5.1) must be included
request.

(see Section
in this QIO

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

13-5

PCLll PARALLEL COMMUNICA.TIONS LINK DRIVERS

will send and receive messages in a normal manner,
but the master
section cannot control transmitter timeslice allocation on the TOM
bus. The master state
(SS.MAS)
designates this unit as TOM bus
master,
enabling control of transmitter unit timeslice allotments on
the TOM bus;
only one master section on the TOM bus can be designated
TOM bus master.
Mode -- The TOM 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 TOM bus master, equal timeslice allotments
are qiven to each transmitter unit;
transmitter unit addresses are
sequentially put on the TOM 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,
i f 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/0
status block contains the length of the requested
transfer, rather than the actual count of words
successfully received in the receiver's buffer.

n:.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 addressinq 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 timeout (no response from the
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.

addressed

(continued on next paqe)

13-7

PCLll PARALLEL

COMMUNICA~rIONS

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 TDM bus master.

IE.SPC

Illegal user buffer
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 .I FC

Illegal function
A function code was specified in an I/O
that is illegal for PCLll transmitters.

13-8

·-----!------------------------------------------~--~--~-----------------------

request

PCLll PARALLEL COMMUNICATIONS LINK DRIVERS
13.5

QIO MACRO -- PCLll RECEIVER DRIVER FUNCTIONS

13.5.1

Standard QIO Functions

Table 13-4 lists the standard function of the QIO macro that is
for the PCLll receiver driver.

valid

Table 13-4
Standard QIO Functions for PCLll Receivers

[

Function

Format

Cancel I/O request

LQIO$C IO.KIL, •••

13.5.2

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
Function

~ormat

QIO$C IO.CRX, ••• ,<tef,bufadd>

Connect for reception

arose re.RTF, •••

Reject transfer

QIO$C IO.ATF, ••• ,<stadd,size,
retadd>

Accept transfer

QIO$C IO.DRX, •••

Disconnect from reception

where:
tef

is the number of a "trigger" event flag which will be
set whenever a flagword is received over the TDM bus.

bufadd

is the address of a
2-word buffer containing
transmitter id, trigger status and the flagword.

stadd

is the address
message.
This
(even address).

size

is the data buffer size in·bytes.
must be an even, positive value.

retadd

is the address of a
6-word buffer
into which
the
contents of the
6 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.

the

of a data buffer to
receive the
address must occur on a word boundary

13-9

The size

specified

PCLll PARALLEL COMMUNICA'rIONS LINK DRIVERS

13.5.2.l 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
rece1v1nq
messages via the receiver on this CPU. The trigger event flag (a
local, common, or qroup-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 messaqE~ 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
flagwd

where:
sts

is the current trigger status.

is the identification code
of
attempting to send the message.

flagwd

is the flagword transmitted to the connected receiver.

the

transmitter

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 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 trigqered.
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-6 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 timeout
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

-1\.

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 can not 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

~
' I

CHAPTER 14

ANALOG-TO-DIGITAL CONVERTER DRIVERS

14.l

,...,,.

INTRODUCTION

The AFCll and ADOl-D analog-to-digital (A/D) converters are used for
the acquisition of 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
Maximum samp ling rate
per second)

200 ( 20 per single)
channel

Approximately
10,000

Number of bi ts

13 or 14

10 or 11

Maximum numb er of analog channels
that can be multiplexed

1024

14.1.1

(points

ADOl-D

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

Thei 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 an optional sign-bit facilitates bipolar
opE~rationo

14-1

ANALOG-TO-DIGITAL CCINVERTER DRIVERS

14.2

GET LON 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 zeros, words 3 and 4 are undefined,
and word 5 is not significant, since there is no concept of a default
buffer size for analoq-to-digital converters •

. 14.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
analoq-to-digital converter drivers.

14.3.l

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 cancelled. 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>
where:

Initiate multiple A/D
conversions

stadd

is the starting address of the data buffer {must be
a word boundary).

size

is the control buffer size in bytes {must be even and
qreater than zero);
the data buffer is the same size.

stcnta

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

14-2

ANALOG-TO-DIGITAL CONVERTER DRIVERS
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:

14 .. 4

ADOl-D

AFCll

15
--

14
·-

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

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

0-1023

Ranqe:

0-63

Gain:

1
2
illegal
illegal
10
20
i llega 1
illegal
50
100
i llega 1
illegal
200
1000
illegal
illegal

1
2
4
8

i lleqal
illegal
illegal
illeqal
illeqal
illegal
illegal
i llega 1
illegal
illegal
illegal
i llega 1

FORTRAN INTERFACE

A collect:ion 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.l

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 (e.g., 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.4.2

The isb Status Array

The isb (I/O status block) parameter is a two-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
a status code on completion of an I/O operation.

14-·3

ANALOG-TO-DIGITAL CONVERTER DRIVERS
The first word of isb receives a status code from the FORTRAN
interface in ISA-compatible format, with the exception of ~he
I/O pendinq condition, which is indicated by a status of
zero.
The ISA standard code for this condition is +2.

The meaning of the contents of isb varies, dependinq on the FORTRAN
call that has been executed,
but Table 14-5 lists certain qeneral
principles that apply.
The section describing each
subroutine
provides further details.
Table 14-5
Contents of First Word of isb

•

Meaning

Contents

I/O in progress

i sb ( 1) = 0

Operation pending.;

isb(l) = 1

Successful completion

i sb ( 1) = 3

Interface subroutine unable to generate
QIO directive or number of samples is
zero

< i sb ( 1} < 300

i sb ( 1)

> 300

QIO directive rejected and actual
code = -(isb(l} - 3)

error

Driver rejected request and actual error
code = -(isb(l)
300)

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 lis~s the FORTRAN interface subroutines supported
AFCll and ADOl-D under RSX-llM.

for

the

Table 14-6
FORTRAN Interface Subroutines for the AFCll and ADOl-D
Subroutine

Function

AIRD/AI ROW

Perform input of analoq data
sequence

AISQ/AISQW

Read a series of sequential analoq input
channels

ASADLN

Assign a LUN to the ADOl-D

ASAFLN

Assign a LUN to the AFCll

14-4

random

ANALOG-TO-DIGITAL CONVERTER DRIVERS
'rhe 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:
Sequence

Performing

Input

Analog

Data

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog
random sequence.
These calls are issued as follows:
CALL

where:

l l
AIRD
AIRDW

Random
data

(inm, icont, idata, [isb], [lun])

inm

specifies the number of analoq input channels.

icont

is an
integer array containing terminal
connection
data - channel number
(riqht-justified in bits 0-11)
and qain (bits 12-15), as shown in Table 14-4.

idata

is an integer array to receive the converted values.

isb

is a two-word integer array
status is returned

lun

is the logical unit number.

which

the

subroutine

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

14.4.5

AISQ/AISQW:

Reading Sequential Analoq Input Channels

The ISA standard AISQ/AISQW FORTRAN subroutines
read a
series of
sequential analog input channels.
These calls are issued as follows:
CALL

where:

f AISQ l
~ AISQW f

(inm, icont, idata, [isb], [lun])

inm

specifies the number of analog input channels.

icont:

is an integer array containing terminal
connection
data - channel number
(right-justified in bits 0-11)
and qain (bits 12-15), as shown in Table 14-4.

idata

is an integer array to receive the converted values.

isb

is a 2-word
integer
status is returned.

lun

is the logical unit number.

array

which

the

subroutine

14-51

ANALOG-TO-DIGITAL CONVERTER DRIVERS
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 qain must be specified for
each
conversion to be performed.
The isb array has the standard meaning defined in Section 14.4.2.
If
inm = O,
then isb(l) = 3. The contents of idata are undefined if an
error occurs.

14.4.6

ASADLN:

Assigning a LUN to thie 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])
where:

lun

is the logical unit number to be assigned to the ADOl-D
and defined as the default unit.

isw

is an integer variable to which the
result
ASSIGN LUN system directive is returned.

iun

is the unit number to be
value of 0 is assumed.

assigned~

unspecified,

the
a

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])
where:

lun

is the logical unit number to be assigned to AFCll
defined as the default unit.

and

isw

is an inteqer variable to which the status
ASSIGN LUN system directive is returned.

the

iun

is the unit number to be
value of 0 is assumed.

assigned~

from

unspecified,

Only the LUN specified in the last call to ASAFLN or ASADLN is defined
as the default unit.

14.5

STATUS RETURNS

The error and status conditions listed in Table 14-7 are
returned·
the analoq-to-diqital converter drivers described in this chapter.

14-6

ANALOG-TO-DIGITAL CONVERTER DRIVERS
Table 14-7
A/D Converter Status Returns
Code

Is.sue

Reason
Successful completion
The operation specified in the QIO directive was
completed successfully.
The second word of the I/0
status block can be examined to determine the number of
A/D conversions performed.

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

IE.AIBO

Operation aborted
The specified I/O operation was
while still in the I/O queue.

IE. B.r..D

cancelled

via

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-diqital
converters,
this
code
indicates that a
bad channel number or qain 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 leqal for
analog-to-diqital converters.
Alternately, the lenqth
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
timeout occurred or the power failed.
In the case of
the ADOl-D, which is not operated in interrupt mode,
this code
indicates a software timeout occurred (i.e.
a conversion did not complete within 30 microseconds).

IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for analog-to-diqital converters.
(continued on next paqe)

14-7

ANALOG-TO-DIGITAL CONVERTER DRIVERS

Table 14-7 (Cont.)
A/D Converter Status Returns
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.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 zero 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

subroutine

Table 14-8
FORTRAN Interface Values
Status Return

FORTRAN Value

Is.sue
IS .PND
IE .ABO
IE .ADP
IE .BAD
IE.BYT
IE .DAO
IE .DNR
IE. I EF
IE. I FC
IE.ILU
IE .NOD
IE.ONP
IE .PRI
IE.RSU
IE .SDP
IE.SPC
IE. ULN
IE .UPN

+01
+00
+315
+101
+301
+319
+313
+303
+100
+302
+99
+323
+305
+316
+317
+102
+306
+08
+04

14-8

ANALOG-TO-DIGITAL CONVERTER DRIVERS

14.6

FUNCTIONAL CAPABILITIES

The AFCll and ADOl-D operate only in multi-sample mode,
because tbe
user can simulate single-sample mode by simply specifyinq one sample.
Multi-sample mode permits many channels to be sampled at approximately
the same time without
requirinq the user to queue multiple I/O
requests.
The maximum number of channels in the configuration is specified at
system-qeneration 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 qain 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
programminq
cons:iderations relevant to users of the analog-to-diqital converter
drivers described in this chapter.

14.7.1

Use of A/D Gain Ranges

Note that the A/D gain ranqes overlap.
The key to successful use of
the A/D converters is to change to a hiqher qain whenever a full-scale
reading is imminent and to chanqe to a lower qain whenever the last
A/D value recorded was less than half of full scale. This method
maintains maximum resolution while avoidinq saturation.

14.7.2

Identical Channel Numbers on the AFCll

When requestinq samplinq of more than one channel, the user should not
specify multiple samplinq of a
sinqle channel without 10 or more
interveninq samples on other char1nels.
This ensures 50 milliseconds
between samples on a sinqle channel.
If samplinq occurs more often
than this on a single channel,
partial
results are returned
(see
Section 14.7.3).

14-9

ANALOG..:TO-DIGITAL COIWERTER 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 recharqe after each
conversion, more frequent samplinq may result in partial readinqs.
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 ten other channels
before returning to the first one.

14. 7 .4

Restricting the Number of ADOl-·D Conversions

The ADOl-D is an extremely fast device,
providinq a
25-microsecond
conversion rate,
and
is driven programmablv to minimize system
overhead. However, an excessive number ot 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-10

CHAPTER 15
UNIVERSAL DIGITAL CONTROLLER DRIVER

15.l

INTRODUCTION

The UDCll is a diqital 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 hiqh-level diqital multiplexer,
interrogatinq diqital inputs and drivinq diqital 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/0
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-diqital 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-diqital 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.~

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 qeneration accordinq 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 qeneration dialog. The encodinq has the followinq format:
8

[number of modules

startinq module number

15-1

UNIVERSAL DIGITAL COl~TROLLER DRIVER
One or more of the followinq symbols is qenerated:
Symbol

Module Type

U$$ADM
U$$AOM
U$$CIM
U$$CSM
U$$LTM
U$$SSM
U$$TIM

Ana.log input
Ana.log output
Contact interrupt
Contact sense input
Latching digital output
Sinqle-shot diqital output
Timer (I/O counter)

Note that all modules of a qiven type must be
sequential slots.

15.1.2

installed

toqether

Accessing UDCll Modules

RSX-llM provides two methods of accessinq the UDCll:
1.

A QIO macro call issued to the driver

Restricted direct access by any task to
dedicated to the UDCll

I/O

paqe

reqisters

The first method, access throuqh the driver, is required
to service
interruptinq modules and
to set and
record the state of latchinq
digital output modules.
The second method, direct access, is a high-speed, low-overhead way to
service noninterruptinq modules.
The followinq
functions may be
performed in this manner:
•

Analoq output

•

Contact sense input

•

Sinqle-shot digital output

•

Read a contact interrupt module

•

Read a timer module

15.1.2.1
modules:

Driver Services - The driver services the followinq types of

Contact interrupt

Timer

Analog input

Latchinq diqital output

(I/O counter)

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 providinq a
circular buffer
information and an event flaq to allow triggerinq
a buffer entry is made.

15-2

by a sinqle 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 qlobal common block within th~ I/0 paqe
provides restricted direct access to the UDCll device reqisters.
In a
mapped system, the lenqth of the block is set to prevent access to
other device registers.
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 reqisters, and thus require
the use of qlobal 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 diqital controllers.

15.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the UDCll driver.
In issuinq them, note the numberinq conventions
described in 15.7.2.

15.3.1 Standard QIO Function
The standard function that is valid for the UDCll is
15-JL.

shown

Table

Table 15-1
Standard QIO Function for the UDCll

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

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

where:

stadd

is the startinq address of the data buffer
a word boundary).

sizb

is the data buffer size in bytes
(must be even and
larqe enouqh to include a 2-word buffer header plus one
data entry;
the buffer may cross a 4K boundary).

tevf

is the triqqer event flaq number.

arv

is the startinq address of the table
values (must be on a word boundary).

is the module number.

is the initial count.

opn

is the first
latchinq diqital output point number,
which must be on a module boundary (evenly divisible by
16) •

is the 16-bit mask.

is the data pattern.

size

is the control buffer size in bytes (must be even and
qreater than zero);
the data buffer is the same size.

(must be

initial/reset

stcnta is the startinq 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 followinq sections describe the functions listed in Table 15-2.

15-4

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-3
A/D Conversion Control Word
Bits

Meaninq

0-11

Channel number

Ranqe:

12-15

Gain value for this
sample, expressed as
a bit pattern as
follows

Gain:

ADUOl

-15 14

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

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

0
0
0
0
0
0
0
0
1
1
1
1

1
1
1
1

0-4095

1
2
i lleqa 1
i lleqa 1
10
20
illeqal
i lleqa 1
50
100
i lleqa 1
i lleqa 1
200
1000
i lleqa 1
i lleqa 1

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 chanqe of state occurs in one or more contact points an
interrupt
is qenerated.
The UDCll driver qains control, determines
whether the change of state is of interest (i.e.,
a contact closure
and point closinq
(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 triqqer event flaq of the connected task.
Each entry consists of five words in the followinq format:
Contents

Word
0

Entry existence indicator

Chanqe-of-state (COS)

Module data

15-5

indicator

(current point values)

UNIVERSAL DIGITAL

COJ~TROLLER

Word

DRIVER

Contents

Module number

(interruptinq module)

Generic code (interruptinq module)

The driver enters data in the location currently indicated by the
driver
index. This pointer can be considered as a FORTRAN index into
the buffer, i.e., the first location of the buffer is associated with
the
index 1.
The beginninq of the data area is the location of the
first entry (index 3).
Entries are made
in a circular fashion,
starting at the beginninq of the data area, fillinq in order of
increasinq memory address to the end of the data area,
and then
wrappinq around from the end to the beqinninq 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 triqqered by the
driver,
it should process data in the buffer startinq at the location
indicated by its pointer and continuinq 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 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.
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 chanqe of state in the
direction of
interest has been recoqnized for one or more discrete
points.
The direction of the chanqe may be from 0 to 1 or 1 to O,
dependinq on the PCL (point closinq) and POP (point openinq) module
iumpers.
The chanqe of state (COS) indicator specifies which point or
~oints of the module have chanqed 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 loqical
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.DC!
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
int~rrupt
in the low-order
byte and the initial FORTRAN index to the beqinninq of the data area
in the hiqh-order byte.
NOTE
The size of the data area
multiple of the entry size.

15-6

must

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.3.2.2 Timer (W734 1/0 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 followinq
format:
Word

Contents

Entry existence indicator

Module data

Module number

Generic code (interruptinq module)

(current value)
(interruptinq module)

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-clockinq modules and modules that interrupt on half count can
continue countinq from the initial value.
The IO.DTI function in Table 15-2 disconnects a
task from timer
interrupts,
and the IO.ITI
function provides the capability of
initializinq a sinqle timer.
Requests to
initialize a counter are
valid only
if the issuinq task has connected a buffer for receivinq
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 latchinq diqital 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 correspondinq point
is
opened or closed,
dependinq on whether the correspondinq bit in the
data pattern is clear or set.
If a bit in the mask
is clear,
the
correspondinq point remains unaltered.

15.3.2.4 Analog-to-Digital Converter
(ADUOl Module) - Each
ADUOl
module has eiqht analog input channels.
The IO.RBC function in Table
15-2 initiates A/D conversions on multiple ADUOl
input channels.
Restrictions on maximum samplinq rates are the same as defined for the
AFCll in Chapter 14.
The converted analoq value is returned as 12 bits, left-justified,
a 16-bit word with the low order 4 bits set to zero.

15-7

UNIVERSAL DIGITAL CONTROLLER DRIVER

15.3.2.5

ICSll Analog-to-Diqital Cc1nverter
(IAD-IA Module) - Each
Module has eight analoq 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 samplinq rates are the same as defined for the AFCll
in
Chapter 14. The IAD-IA module preempts eiqht module slots reqardless
of the number of IMX-IA multiplexers installed.
IAD~IA

For addressinq purposes,
each converter occupies a
block of 120
channels.
Thus, A/D converter 0 is addressed by referencinq channels
0 throuqh 119; A/D converter 1 is addressed by referencinq channels
120
throuqh 239 etc.
When fewer
th~n
seven multiplexers are
installed, not all addresses within the block are valid.
The converted analoq value is returned as 12 bits, left iustified,
a 16-bit word with the low order 4 bits set to zero.

15.4

DIRECT ACCESS

Section 15.1.2 describes UDCll functions
that may be performed by
referencinq a module throuqh
its physical address in the I/O paqe.
Under RSX-llM such access is accomplished by one of the followinq
methods:
1.

A privileqed task or any task runninq in an unmapped system
has unrestricted access to the I/O paqe and may therefore
access each module by absolute address.

Usinq the Task Builder, a task may link to a qlobal 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
relinkinq.
Further,
in a mapped system the memory
management hardware will abort all
references to device
reqisters
outside the physical address limits of the common block.
The operations required to implement each method may be summarized
fol lows:
1.

Unrestricted access to the I/O paqe
a.

An object module
is created which defines the UDCll
configuration throuqh a list of absolute qlobal addresses
and addressinq limits for each module type.

The obiect module is included in the system library file.

A task
is created containinq the appropriate qlobal
references.
Such references are resolved when the task
builder automatically searches the system library file.

Steps a and b are executed once, durinq system qeneration {see RSX-llM
System Generation and Management Guide).
Step c is performed e~ach
time a task is created that references the UDC12.
2.

Access to the I/O paqe throuqh a Global Common Block:
a.

An obiect module
is created which defines the UDCll
configuration
throuqh a
list of
relocatable qlobal
addresses and addressinq 1imits for each module type.

15-8

~
. "'\

UNIVERSAL DIGITAL CONTROLLER DRIVER
b.

The obiect module is linked, usinq 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 paqe.

The INSTALL MCR command is used to make the Global Common
Block resident in memory.

A task
is created containinq the appropriate qlobal
references.
Such r~ferences ·are resolved by directinq
the Task Builder to link the Task to the common block.

common

block

to
that

Steps a throuqh d are executed once, durinq system qeneration.
Step e
is performed each time a task is created that references the UDCll
common block.
The followinq paraqraphs describe each step in detail.

15.4.1

Defininq the UDCll Confiquration

The source module UDCOM.MAcl, when assembled with the proper pref ix
file, provides qlobal definitions for the followinq parameters:
•

The starting address of each module type.

•

The hiqhest point number within a qiven module type.

•

The highest module number within a qiven module type.

The last two parameters are absolute quantities that may be used to
prevent a task from referencinq a module that is nonexistent or out of
limjL ts.
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 Proqram section to be used when buildinq and
linkinq to the UDCll Global Common area.

15.·~.l.l

Assembly Procedure for

with the RSX-llM
RSXMC .MAC.

configuration

UDCOM.MAC - UDCOM.MAC
parameters

contained

is assembled
in the file

To ,create relocatable module addresses either the parameter U$$DCM or
M$$MGE must be defined.
M$$MGE will be included in RSXMC.MAC i f
memory management was specified when the system was qenerated.
If
not,
the user should edit the file
to
include the followinq
definition:
U$$DCM=O
The file may then be assembled usinq the MCR command:
>MAC UDCOM,UDLST=[ll,lO]RSXMC,UDCOM

1 This module resides on the RK05 cartridqe of the RSX-llM RK
distribution kit labeled EXECUTIVE SOURCE.
For RP distribution kits,
it resides on the RP imaqe.
The file is located under UIC [11,10].

15-9

UNIVERSAL DIGITAL CONTROLLER DRIVER

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 followinq 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.
The followinq symbols define the absolute or
the first module of a qiven type:

section

relocatable

Symbol

Module Type

$.ADM
$.AOM
$.CIM
$.CSM
$.LTM
$.SSM
$.TIM

Analoq input
Analoq output
Contact interrupt
Contact sense input
Latchinq digital output~
Sinqle-shot diqital output
Timer (I/O counter)

The addresses in relocatable form are defined
named UDCOM havinq the attributes:
REL
OVR
D
GBL

lists

the

address

proqram

section

- relocatable
- overlaid
- data
- qlobal scope

Note that these attributes correspond to those
common block within a FORTRAN proqram.
In either the absolute or relocatable case,
referenced by the correspondinq symbolic
module index.

attached

named

individual modules are
address plus a relative

The followinq symbols define the hiqhest diqital point within a module
type:
Symbol

Module Type

P$.CIM
P$.CSM
P$.LTM
P$.SSM

Contact interrupt
Contact sense input
Latchinq diqital output
Sinqle-shot diqital 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 followinq symbols define the hiqhest module number within a
module type.

15-10

qiven

"""'·

UNIVERSAL DIGITAL CONTROLLER DRIVER
Symbo:~

Module Type

M$.ADM
M$ .AOM
M$.CIM
M$.CSM
M$.LTM
M$.SSM
M$.TIM

Analoq input
Analoq output
Contact interrupt
Contact sense input
Latchinq digital output
Sinqle-shot diqital output
Timer (I/O counter)

The hiqhest module number is defined relative to the first module of a
qive!n type.
Thus, based on the previous example, M$.CIM will have a
value of 1.

15.4.2

Including UDCll Symbolic
Module Library

Definitions

the

System

Object

As described in 15.4, a task having unrestricted access to the I/O
paqe! may
reference a UDCll module by absolute address.
The obiect
module UDCDF contains symbolic definitions of
absolute
module
addresses and may be included in the System Obiect Module Library:
SY: [l,l]SYSLIB.OLB
The Task Builder automatically searches this file to
resolve any
undefined qlobals remaininq after all input files have been processed.
The followinq example illustrates the procedure for includinq 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 obiect module UDCDF.OBJ in the file
SYSLIB .OLB.

15.4.3

Referencing the UDCll through a Global Common Block

The follow:inq sections define the procedure for
creatinq a Global
Common block in the I/O PAGE, makinq the block resident in memory, and
creatinq a task which
references UDCll modules within the block.
Examples are qiven for both mapped and unmapped systems.

15. 4. 3 .1 Cn~ating a Global Common Block - The fol low inq sequence
illustrates the use of the obiect file UDCOM.OBJ to create a disk
imaqe of the qlobal common area in a mapped system.
>SET /UIC=[l,l]
>TKB
TKB>UDCOM/MM,LP:,SY:UDCOM/PI/-HD=[200,200]UDCOM
'rKB>/
EWrER OPTIONS:
TKB>PAR=UDCOM:O:lOOO
TKB>STACK=O
'rKB>/

15-11

UNIVERSAL DIGITAL CONTROLLER DRIVER
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 followinq files:
•

A core image output file to be named UDCOM.TSK

•

A memory map output to the line printer

•

A svmbol table file to be named UDCOM.STB

(1,1].
All files reside on SY:
under UIC
UDCOM.OBJ containing the UDCll address
values, constitutes the input.
The switches specified for
the output
information to the Task Builder:

The sinqle input file,
definitions as relocatable

files

convey

the

followinq

/MM

indicates that the core imaqe of the common block
reside on a system with Memory Manaqement.

/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 imaqe will
not contain a
header.
A header
is only required for a core imaqe
file that is to be installed and executed as a task.

The names of the partition, task file,
aqree.

and

~
i.

symbol-table

will

files

must

The STACK option must be used to eliminate the stack space.
The followinq sequence illustrates the correspondinq 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>/
Aqain the task builder is requested to produce a core imaqe 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 imaqe of the common block
reside on an unmapped system.

will

/PI

Indicates that the core imaqe is position independent.
In an unmapped system the core imaqe is fixed in the
same address space for all tasks;
however, the qlobal
symbols defined in the symbol table file retain the
relocatable attribute.

/-HD

indicates that a core image without a header is
created.

be
~.

15-12

UNIVERSAL DIGITAL CONTROLLER DRIVER
The PAR option specifies the base and length of the common area to
All
coincide with the standard UDCll addresses in the I/O page.
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
The corresponding command in an unmapped system is:
>SET /MAIN= UDCO M: 1 7 1 0 : 1 0 : 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
> IN s [ 1 I l ] uDCO M
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
'!'KB>/
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:

15-13

UNIVERSAL DIGITAL COHTROLLER DRIVER

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

the

15.5.l Synchronous and Asynchronous Process Control I/O
The ISA standard provides for synchronous and asynchronous p~ocess
I/O.
Synchronous I/O is indicated by appending a "W" to the name of
the subroutine (e.g., 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 first word of isb receives a status code from the
FORTRAN interface in ISA-compatible format, with the
is
which
exception of the I/O pending condition,
indicated by a status of zero. 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 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.

15-14

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-4
Contents of First Word of isb
Meaning

isb(l)

Operation pending;

isb(l)

Successful

i sb ( 1)

Interface
subroutine
unable
to
generate QIO directive or number of
points requested is zero

I/O in progress

completi~n

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

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

Number of points requested is
zero

i sb ( 1)

+321

Invalid UDCll module

15.5.3 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.
Convert four BCD digits to a binary number:
!BIN = KBCD2B{IBCD)
Convert a binary number to four BCD digits:
!BCD = KB2BCD{IBIN)

15-15

I/O

directly,

but

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 15-5
FORTRAN Interface Subroutines for the UDCll
Subroutine

Function

AIRD/AIRDW

Perform input
sequence

AISQ/AISQW

Read a series of
channels

AO/AOW

Perform analog output on

analog

data

sequential

random

analog

input

several

channels

{ D)

ASUDLN

Assign a LUN to the UDCll

CTDI

Connect a circular buffer
contact interrupt data

CTTI

Connect a circular buffer to receive
interrupt data

DFDI

Disconnect a buffer from contact interrupts

DFTI

Disconnect a buffer from timer interrupts

DI/DIW

Read several 16-point contact sense

receive
timer

fields

{D)

DOL/DOLW

Latch or unlatch several 16-point fields

DOM/DO MW

Pulse several 16-point fields

RCIPT

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

SCTI

Set a timer module to an initial value

15-16

{D)

single

contact

(D)

UNIVERSAL DIGITAL CONTROLLER DRIVER
15.5.4

AIRD/AIRDW::
Sequence

Performing

Input

Analog

Data

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog
random sequence.
These calls are issued as follows:

data

l (inm, icont, idata, [isb], lun)

AIRD
{ AIRDW ~

CALL

where:

Random

inm

specifies the number of analog input channels.

icont

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

idata

is an integer array to receive the converted values.

isb

is a two-word integer array
status is returned.

lun

is the logical unit number.

which

the

subroutine

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

CALL

where:

l (inm,icont,idata, [isb],lun)

lAISQW~

inm

specifies the number of analog input channels.

icont

is an integer array containing terminal connect~on
data - channel number
(right-justified in bits 0-11)
and gain (bits 12-15), as shown in Table 15-3.

idata

is an integer array to receive the converted values.

isb

is a two-word integer array
status is returned.

lun

is the logical unit number.

which

the

NOTE
lun is a required parameter.

15-17

subroutine

UNIVERSAL DIGITAL CONTROLLER DRIVER

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 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
sevaral channels. These calls are issued as follows:
CALL

where:

{i nm, icon t, id at a , [ i s b] , [1 u n] )

inm

specifies the number of analog output channels.

icont

is an integer array containing the channel numbers.

idata

is an integer array containing
settings, in the range 0-1023.

isb

is a two-word integer array
status is returned.

lun

is the Logical unit number {ignored if present).

the
which

output
the

voltage

subroutine

The isb array has the standard meaning defined in Section 15.5.2.

15. 5. 7

ASUDLN:

Assigning a LUN to th•! 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 {lun, [isw], [iun])
where:

lun

is the logical unit number to be assigned
specified unit, and defined as the default.

the

isw

is an integer variable to which the result
ASSIGN LUN system directive is returned.

the

iun

is an integer defining the UDCll unit
number is specified, 0 is assumed.

15-18

number.

.......

UNIVERSAL DIGITAL CONTROLLER DRIVER

15.5.8

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

The UDCll driver generates a five-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])
wheire:

ibuf

is an integer
interrupt data.

array

that

isz

is the length of the array in
size of 15.

iev

is the trigger event flag number. The specified event
flag is set whenever the driver inserts an entry in the
data buffer.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

words,

which

receive
with

the

contact
a

minimum

subroutine

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

The UDCll driver generates a four-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
fol lows:
isz

(8 + 4 * n)

where n is the number of entries in the buffer and isz is expressed in
words.
15-19

UNIVERSAL DIGITAL CO~ITROLLER DRIVER
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])
where:

ibuf

is an integer array that is to receive timer
data.

isz

is the length of the array in
size of 12.

iev

is a trigger event flag number.
The specified event
flag is set whenever the driver inserts an entry in the
data buffer.

is an integer array which contains the
initial timer
module values,
with one entry for each timer module,
where entry n corresponds to timer module number n-1.

isb

is a 2-word
integer
status is returned.

lun

is the logical unit number.

array

words,

which

interrupt

with

the

minimum

subroutine

The isb array has the standard meaning defined in Section 15.5.2.

15.5.10

DFDI:

Disconnecting from Contact Interrupts

The OFOI FORTRAN subroutine disconnects
interrupts.
It is issued as follows:

task

which

from

contact

CALL OFOI ( [isb], [lun])
where:

isb

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

the

subroutine

The isb array has the standard meaning defined in Section 15.5.2.

15.5.11

DFTI:

Disconnecting from Timer Interrupts

The OFT! FORTRAN subroutine disconnects a task from timer
It is issued as follows:

interrupts.

CALL OFT! ( [isb], [lun])
where:

isb

is a 2-word integer
status is returned.

array

lun

is the logical unit number.

which

the

subroutine

The isb array has the standard meaning defined in Section 15.5.2.

15-20

UNIVERSAL DIGITAL CONTROLLER DRIVER
DI/DIW:

15.5.12

Reading Several Contact Sense Fields

The ISA standard DI/DIW FORTRAN
subroutines read several
contact sense fields.
These calls are issued as follows:
CALL
where:

16-point

(inm, icont, idata, isb, [lun])

inm

specifies the number of fields to be read.

icont

is an integer array containing the initial point number
of each field to be read.

idata

is an integer array that is to receive the input
16 bits of contact data for each field read.

isb

is a 2-word
integer
status is returned.

lun

is the logical unit number

array

which

the

data,

subroutine

(ignored if present).

The isb array has the standard meaning defined in Section 15.5.2.

DOL/DOLW:

15.S.13

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)
where:

inm

specifies the
unlatched.

number

icont

is an integer array containing the initial point number
of each 16-point field.

idata

is an integer array which 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 0 unlatching;
each entry
in
the array specifies a string of 16 points.

imsk

is 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

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

fields

which

the

latched

subroutine

The isb array has the standard meaning defined in Section 15.5.2.

15-21

UNIVERSAL DIGITAL co:NTROLLER DRIVER
DOM/DOMW:

15.5.14

Pulsing Several Fields

The ISA standard DOM/DOMW FORTRAN subroutines pulse several 16-bit
fields
(one-shot digital output points). These calls are issued as
follows:
} DOM

CALL
where:

(inm, icont, idata, [idx], [isb], [lun])

( DOMW f

inm

specifies the number of fields to be pulsed.

icont

is an integer array containing the initial point number
of each 16-point field.

idata

is an integer array which specifies the points to be
pulsed;
bit n of idata corresponds to point number
icont + n.

idx

is a dummy argument retained for compatibility with
existing Instrument Society of America standard FORTRAN
process control calls.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number (ignored if present).

array

which

the

subroutine

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 .ceads thE~ state
interrupt point. It is issued as follows:

single

contact

CALL RCIPT (ipt, isb, [lun])
where:

ipt

is the number of the point to be read;
points are
numbered sequentially from O, the first point on the
first contact interrupt module.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number (ignored if present).

array

which

the

subroutine

The isb array has the same basic meaning defined in Section
However,
isb word 2 is set to one of the following
representing the state of the point:
Setting

Meaning

• FALSE.

( 0)

Point is open

.TRUE.

(-1)

Point is closed

15-22

15.5.2.
values,

~.
'

UNIVERSAL DIGITAL CONTROLLER D.RIVER
NOTE
To increase throughputp the subroutines
RDCS, RDDI, 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 which 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
recE~ived all change-of-state information from the current entry.
If a
valid entry is not found, ipt is set negative and ict (if sp~cified)
is E~ither assigned a value of zero or an overrun count maintained by
the UDCll driver.
If ict is zero, 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
wen~

discardE~d.

The RDCS call is issued as follows:
CALL RDCS ( i pt, i va 1, [ i ct] )
whe1re:

ipt

is a variable to which the digital input
is returned;
it may be set as follows:
11

number

ipt < 0 if no valid entry is found
(i.e., no
interrupt data currently in buffer, or overrun
detected).
One of the following
values
is
returned to indicate the condition detected:
-1

-2
•

point

Buffer empty
Overrun detected

ipt => 0 if the value indicated is a point number
that has changed state; the state is returned to
ival.

15-23

UNIVERSAL DIGITAL CONTROLLER DRIVER
ival is a variable to which the state of
returned;
it may be set as follows:

15.5.17

•

.FALSE.

•

.TRUE.

(0)

the

point

if the point is open

(-1) if the point is closed

ict

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

RDDI:

Reading Contact Interrupt Data from a Circular Buffer

The RODI 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 which
was specified in the CTDI call is also cleared.
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 zero, examines the state of data bit n, and converts bit n
to a point number via 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 16, it is reset
to zero and an attempt is made to read the next interrupt entry :Erom
the circular buffer.
If a valid entry is not found, ipt is set
negative and ict (if specified) is either assigned a value of zero or
an overrun count maintained by the UDCll driver. If ict is zero, 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])
where:

ipt

is a variable to which the digital input
is returned;
it may be set as follows:

•

point

number

ipt < 0 if no valid entry is found
(i.e. , no
interrupt data currently in buffer, or buff er
empty). One of the following values is returned
to indicate the condition detected:
-l=Buffer empty
-2=0verrun detected

•

ipt => 0 if the value indicated is a point number;
the state is returned to ival

15-24

UNIVERSAL DIGITAL CONTROLLER DRIVER

ival

15.5.18

is a variable to which the state of
returned;
it may be set as follows:
•

• FALSE~

(0)

•

.TRUE.

(-1)

the

point

if the point is open
if the point is closed

ict

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

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 which 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).
The RDTI call is issued as follows:
CALL RDTI ( imod, i tm, [ i vrn])
where:

imod

is a variable to which the module number
it may be set as follows:

returned;

(i.e. , no
• imod < 0 if no valid entry is found
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
module number;
returned in itm

15.5.19

entry is valid,
indicating a
the value of the timer module is

itm

is a variable to which the timer value is returned.

ivrn

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

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.

15-25

UNIVERSAL DIGITAL CONTROLLER DRIVER
The call to RDWD is issued as follows:
CALL RDWD ( i mod, is t, [ i vr n] , [ i cos] )
where:

imod is a variable to which the module number
it may be set as follows:

returned;

• imod < 0 if no valid entry is found
(i.e., no
interrupt data currently in buffer or overrun
detected).
One of the following
values
is
returned to indicate the condition detected:
-l=Buf fer empty
-2=0verrun detected

15.5.20

ist

is a variable to which the module data is returned.

ivrn

is 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

is a variable to which the change-of-state data is
One bit is set for each point that has
returned.
changed state in the direction indicated by the "point
open"
(POP) or "point closed"
(PCL) jumpers on the
module.

RSTI:

Reading a Timer Module

The RSTI FORTRAN subroutine reads a single timer module.
as follows:

It is issued

CALL RSTI ( imod, isb, [lun])
where:

imod

is the module number of the timer to be read.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number (ignored if present).

array

which

the

subroutine

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:

initial

value.

CALL SCTI (imod, ival, [isb], [lun])
where:

imod

is the module number of the timer to be set.

ival

is the initial timer value.

isb

is a 2-word integer
status is returne.d.

lun

is the logical unit number.

array

which

the

subroutine

15-26

UNIVERSAL DIGITAL CONTROLLER DRIVER
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 via 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

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

IE.ABO

Operation aborted
The specified I/O operation was
while still in the I/O queue.

IE.BAD

cancelled

via

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.

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.
(continued on next page)

15-27

UNIVERSAL DIGITAL co:NTROLLER DRIVER

Table 15-6 (Cont.)
UDCll Status Returns
Reason

Code
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
timeout occurred or the power failed.

IE .I EF

Invalid event flag number
An invalid trigger event flag number was specified in a
connect function.

IE. I FC

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.IT!) 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
which
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.

IE.PR!

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 (6 words for timer
interrupts and 7 words for contact interrupts) or a
byte count of zero was specified.

FORTRAN interface values for these status
Section 15.6.1.

15-28

returns

are

presented

UNIVERSAL DIGITAL CONTROLLER DRIVER

15.6.l

FORTRAN Interface Values

The values listed in Table 15-7 are
calls.

returned

FORTRAN

subroutine

Table 15-7
FORTRAN Interface Values
Status Return

FORTRAN Value

rs.sue

+01
+00
+315
+101
+301
+319
+313
+303
+100
+302
+99
+321
+305
+316
+317
+102
+306
+08
+04

IS .PND
IE .ABO
IE .ADP
IE.BAD
IE.BYT
IE .DAO

IE.DNH
IE. I EF
IE. I FC
IE.ILU
IE .MOD
IE .ONP
IE.PR!
IE.RSU
IE.SDP
IE .SPC
IE. ULN
IE. UPN

......,

.•

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 O as the first point on the first
module of a given type.
For instance, point 20 (octal) is the first
point of the second contact sense module (i.e., relative module number
1) •

15-29

UNIVERSAL DIGITAL CON~ROLLER DRIVER
15.7.2

Proc•ssing 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-30

CHAPTER 16

LABORATORY PERIPHERAL SYSTEMS DRIVERS

INTRODUCTION

16.1

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 precision
10 channels (including display)

10 bits of precision
2 channels (including
display)

Display Control

4096 by 4096 dot matrix

1024 by 1024 dot matrix

Digital I/O Option

16 digital points
and programmable
relays

16 digital points
(available with
DRll-K opt ion)

________________________ ____________ _____________

..__

_.__

At system generation, the user can specify the following:
•

Number of A/D channels

•

(LPSAM-SG)
Presence or absence of the gain ranging option
(LPSll only)
and the polarity of each channel (uni- or
bi-polar).

•

Presence or absence of the external D/A option
(LPSVC
LPSDA), and if present, the number of D/A channels.

•

Clock preset value

16-1

and

___.

LABORATORY PERIPBERA.L SYSTEMS DRIVERS
ARll Laboratory Peripheral System

16.1.1

The ARll is a 1-module, real-time analog subsystem that interfaces to
the PDP-11 family of computers via 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.

LPSll Laboratory Peripheral System

16.1.2

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 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,
as explained in Section
16.6.1.

16.3

OIO 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

QIO$C IO.KIL, •••

Cancel I/O requests

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

QIO$C IO.SDI, ••• ,<mask>

Read digital input register

QIO$C IO.SDO, ••• ,<mask,data>

Write digital output register

whe!re:

"-''

(LPSll only)

int

is the 16-bit signed binary integer to display.

num

is the LED digit number where the decimal point is
to be placed.

rel

is the relay number

(zero or one).

pol

is the polarity
closed).

(zero

mask

is the mask word.

data

is the data word.

for

open,

nonzero

for

The! following subsections describe the functions listed above.

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

LABORATORY PERIPHERAL SYSTEMS DRIVERS
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.2

~
'I ~

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.

16.3.2.3

The operation performed is:
RETURN VALUE=MASK.AND.INPUT REGISTER

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 d~ta
to be written in corresponding bit positions.

16.3.2.4

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

16-4

LABORATORY PERIPHERAL SYSTEMS DRIVERS

where:

st add

is the starting address of the
(must be on a word boundary).

data

buffer

size

is the data buffer size in
greater than zero and a
bytes).

pnt

is
the
digital
·point
numbers
(byte
0 - starting input/output point number; byte
1 - input point number to stop the function).

ticks

is the number of real-time clock
ticks
between
samples
or
data transfers, as
appropriate.

buf s

is the number of data buffers to transfer.

chna

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

bytes
(must be
multiple of four

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

is 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

is 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 cl~aring of
a digital input point, or by the collection of a specified number of
bu ff e rs 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
(via the setting of an event flag)
that data is available to be
-~

16-5

LABORATORY PERIPHERAL SYSTEMS DRIVERS
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.
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

.~,
I

If the LPSAM-SG option is present, then each channel must have been
defined as uni- or bi-polar at system generation.
In addition, if
bandwidth filtering is enabled (and so indicated at SYSGEN 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 which 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.BIS - This LPSll-only function measures the elapsed time
between a series of events by means of Schmitt trigger one.
Each time
a sample is to be taken, a counter is incremented and Schmitt trigger
one
is tested.
If it has fired, then the counter is written into the
user buffer and reset to zero.
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 one fires, then a zero
value is written into the user buffer. Sampling may be started and
stopped as
described
in
Section
16~3.3.l.
All
input
is
double-buffered with respect to the user task.

16-6

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The subfunction modifier bits appear below.
the action listed in the right-hand column.
Bit

A setting of 1

indicates

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
specification means start immediately)

zero

16.3.3.3 :co.,MDA - This function writes data into one or more external
D/A ~onverters 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.l. 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 IOgMDI - 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 zero.

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

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

st add

Stop in-progress

requestj

is the buffer address of the function to stop
(must be the same as the address specified in
the initiating request).

16a3.4~1

IO.STP - IO.STP stops a single
in-progress
synchronous
request.
It
is unlike IO.KIL in that it only cancels the specified
request, whereas IO.KIL cancels all requests.

16a4

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

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
ISl\,-compatible format,
with the
exception of the I/O pending condition, which is indicated by
a
status of zero.
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-8

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-6
Contents of First Word of isb
Contents

Meaning

i sb ( 1)

Operation pending;

isb(l)

Successful completion

isb(l)

Interface subroutine unable to generate QIO
directive, or illegal time or buffer value

<= isb(l) <

300

directive
rejected
-(isb(l) - 3)

QIO

code
isb(l)

> 300

I/O in progress

Driver
rejected
code = -(isb(l) -

request
300)

and

actual

error

and

actual

error

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 I/O Status Word
Address of End of Buffer + l
Address of Start of Data

Start of Data
Half Buffer
End of Buffer
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 six.
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
(i.e.,
the buffer
is
full
of data) or if the driver attempts to obtain the next data item

16-9

LABORATORY PERIPHERAL SYSTEMS DRIVERS
is

.,_,

All synchronous functions may be
initiated immediately or when a
specified digital input point is set (i.e., a start button is pushed).

from the user buffer when none
empty).

available

(i.e.,

the

buffer

They may 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 (i.e., 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.
Table 16-7
FORTRAN Interface Subroutines for Laboratory Peripheral Systems
Subroutine

Function

ADC

Read a single A/D channel

ADJLPS

Adjust bu ff e r poi n t e rs

(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

DRS

Initiate synchronous digital input sampling (S)

HIST

Initiate histogram sampling (S)

!DIR

Read digital input

!DOR

Write digital output

IRDB

Read data from
(F,S)

LED

Display number in LED lights

LPSTP

Stop an in-progress synchronous function

PUTD

Put data into a synchronous function output buffer

RELAY

Latch an output relay

RTS

Initiate synchronous A/D sampling (S)

SDAC

Initiate synchronous D/A output

SDO

Initiate synchronous digital output

(F,S)

(F)

(LPSll only)

(F,S)
(F,S)

synchronous

(S)

16-10

(S)

function

input

buffer

(LPSll only)

(S)
(S)

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The following subsections briefly describe the function and format
each FORTRAN subroutine call.

16.4~4

ADC:

Reading a Single A/D Channel

The J\DC 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
when~:

(ichan, [var], [igain], [isb])

ichan

specifies the A/D channel to be converted.

var

is a floating-point variable that
receives
the converted value in floating-point format.

igain

specifies the gain at which the specified A/D
channel
is to be converted.
The default is
1.
If
spec i f i e d , . i g a in
may
have
the
following values:
Gain
(driver
Auto gain-ranging
provides
gain
that
significance)

A gain of
driver.
isb

always

selects
most

used

the

ARll

is a
2-word
integer array
subroutine status is returned.

which

the

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

16.4.5

ADJLPS:

* converted value) I conversion gain

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

LABORATORY PERIPHERAL. SYSTEMS DRIVERS

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 may
process the data directly, then call ADJLPS to free half the buffer.
Use of the routine for synchronous output functions is quite similar.
When a half buff er 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 ADJ LPS ( i buf, iadj, [i sb])
where:

ibuf

is an
integer array which was previously
specified in a
synchronous input or output
function.

iadj

specifies 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

is a
2-word
integer array to
subroutine status is returned.

which

the

The isb array has the standard meaning described in Section 16.4.1.

16. 4. 6

ASLSLN:

Assigning a LUN to LSI):

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 via
the LUN assigned.
The call is issued as follows:
CALL ASLSLN (lun, [isb], [iun])
where:

lun

is the number of the LUN to
LSO:

isb

is a
2-word integer array
subroutine status is returned.

iun

is the unit number of the device to be
assigned (defaults to 0 i f not specified).

be
to

assigned

which

the

The isb array has the standard meaning described in Section 16.4.1.

16-12

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.7

ASARLN:

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
perjlpheral system FORTRAN function or subroutine. Subsequent calls to
othe~r
interface routines
then implicitly reference the ARll via the
LUN assigned ..
The call is issued as follows:
CALL ASARLN (lun, [isb], [iun])
where:

assigned

which

the

lun

is the number of the LUN to
ARO:

isb

is a 2-word
integer array
to
subroutine status is returned.

iun

is the unit number of the device to be
assigned (defaults to 0 if not specified).

The isb array has the standard meaning described in Section 16.4.1.

16 .~l .8

CVSWG:

Converting a Switch Gain A/D Value to Floating-Point

The CVSWG lrORTRAN 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,
then converts
the result to a floating-point number.
It may be conveniently used in
conjunction with the IRDB routine (see Section 16.4.13).
The call is issued as follows:
CVSWG
whe t·e:

ival

( i va 1)
is 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

For the various gain codes,
var

= x * converted value

as shown below:
Gain

16-13

gain

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.4.9

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 via the IRDB routine
{see
Section 16.4.12),
or the ADJLPS routine (see ~ection 16.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], [istop])
where:

ibuf

is an integer array that is
input data values.

ilen

specifies the length of ibuf
(must
and greater than or equal to six).

imode

specifies the start, stop, and sampling mode.
Its value is encoded by adding together the
appropriate function selection values shown
below.
Function
Selection
Value

receive

the

even

"""'·
I,_,.

Meaning

128

Start on digital
set

Set digital
start

Stop on
clear

Stop on number of buffers

input

output

digital

point

input

point

Thus a value of 192 for imode specifies:

•

The sampling is to be started when a specified digital
point is set.

input

•

A digital output point is to be set when sampling is started.

•

Sampling will be stopped via a program request.
irate

is 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

Mi 11 i seconds

Seconds

Minutes

The second word specifies
the
interval
magnitude as a 16-bit unsigned integer.
16-14

Allh,-1
i

LABORATORY PERIPHERAL SYSTEMS DRIVERS
iefn

specifies the number of the event flag that
is to be set each time a half buffer of data
has been collected.

imask

specifies the
read.

isb

is a
2-word
integer array
subroutine status is returned.

nbuf

specifies 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

specifies 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

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

digital

input

points
to

which

the

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 buffero

16.4.10

HIST:

Initiating Histogram Sampling (LPSll only)

The HIST FORTRAN subroutine measures the elapsed time between a series
of events via Schmitt trigger one.
Each time a sample is to be taken,
a counter
is
incremented and
Schmitt
trigger one is tested.
If it has fired, then the counter is
written into the user buffer and the counter is reset to zero.
Thus
the data
returned
to the user
is the number of sample intervals
between Schmitt trigger firings.
If the counter overflows before
Schmitt
trigger one fires,
a
zero 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], [istop])
where:

:ibuf

is an integer array that is
input data values.

:ilen

specifies the length of ibuf
(must
and greater than or equal to six).

16-15

receive
be

the
even

LABORATORY PERIPHERAL SYSTEMS DRIVERS
imode

specifies the start, stop and sampling mode.
Its
value
is
encoded
by
adding the
appropriate function selection values shown
below:
Function
Selection
Value

irate

Meaning

128

Start of digital
set

input

Set digital
start

Stop on
clear

Stop on number of buffers

output

digital

point

input

point

is 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

Mi 11 i seconds

Seconds

Minutes

The second word specifies
the
interval
magnitude as a 16-bit signed integer.
iefn

specifies the number of the event flag that
is to be set each time a half buffer of data
has been collected.

isb

is a 2-word integer array to
subroutine status is returned.

nbuf

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

istart

specifies 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

specifies 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-16

which

the

LABORATORY PERIPHERAL SYSTEMS DRIVERS

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 zero
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
reglster as an unsigned binary integer or as four binary-coded decimal
(BCD) digitse 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 !DIR (imode, [ival], [isb])
where:

imode

specifies ~he mode in which the digital input
register is to be read.
If imode equals
zero, 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

is a variable that receives the value read.

:isb

is a 2-word integer array to
subroutine status is returned.

which

the

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

IDOR:

function

Writing Digital Output

The IDOR FOWrRAN 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])
where:

:imode

specifies whether the bits specified by imask
are to be cleared or set in the digital
output register. If imode equals zero, then
the bits are to be cleared. Otherwise they
are to be set.

:imask

specifies the bits to be cleared or set in
the digital output register.
It may be
conveniently specified as an octal constant.

newval

is a variable that receives
(actual)
value written into
output register.

isb

is a 2-word integer array to
subroutine status is returned.

16-17

the
the

updated
digital

which

the

LABORATORY PERIPHERAL SYSTEMS DRIVERS

The isb array has the standard meaning described in Section 16.4.l.
When the function form of the call is used, the value of the
is the same as that returned in newval.

16.4.13

IRDB:

function

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 I [ival])
where:

ibuf

is an integer array which was previously
specified in a synchronous input sampling
request (i.e.,, DRS, HIST, or RTS).

ival

is a variable that receives the next value in
the data buffl:~r.

When the function form of the call is used, the value of the
is the same as that returned in ival.

16.4.14

LED:

function

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] I [isb])
where:

value

is the variable
displayed.

idec

specifies the position of the decimal point.
A value of l to 5 specifies that a dec:imal
point is to be displayed. All other values
specify that no decimal point is to be
displayed.

isb

is a 2-word integer array to
subroutine status is returned.

16-18

whose

ival

which

the

LABORATORY PERIPHERAL SYSTEMS DRIVERS
The isb array has the standard meaning described in Section 16.4.l.
For example, the following call
CALL LED (-55,2)
would cause -0005.5 to be displayed in the LED lights.

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)
where:

16.4.16

is an integer array that specifies a
that
was
previously
specified
synchronous initiation request.

ibuf

PUTD:

buffer
in
a

Putting a Data Item into an Output Buffer

The PUTD FOR'l'RAN 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)
where:

16.4.17

lbuf

is an integer array which was previously
specified in a
synchronous output request
(SDO or SDAC).

lval

is a variable whose value is to be placed in
the next free location in the data buffer.

RELAY:

Latching an Output Relay (LPSll only)

The RELAY FORTRAN subroutine opens or closes the
call is issued as follows:

LPSll

relays.

The

CALL RELAY (irel, istate, [isb])
where:

irel

specifies which relay
is
closed
(zero for
relay
two).

to be opened or
one, one for relay

istate

specifies whether the relay is to be opened
or closed.
If istate equals zero, the relay
is to be opened.
Otherwise
it is to be
closed.

isb

is a
2-word integer array
subroutine status is returned.

which

The isb array has the standard meaning described in Section 16.4.1.

16-19

the

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 may be started when the interface subroutine is called 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
(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
(via the setting of an event flag)
that data is available to be
processed while the driver fills the other half of the buffer. Data
may be sequentially retrieved from the data buffer via the IRDB
routine
(see Section 16.4.12, or the ADJLPS routine (see Section
16.4.5) may be used in conjunction with direct access t6 the
input
data. The call is issued as follows:
CALL RTS (ibuf,ilen,imode,irate,iefn,ichan,nchan,isb,
[nbuf], [istart], [istop])
where:

ibuf

is an integer array that is
converted data values.

ilen

specifies the length of ibuf
(must
and greater than or equal to six).

imode

receive

the

even

specifies 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
set

Set digital
start

Stop on
clear

Stop on number of buffers

Auto gain-ranging (LPSll only)

16-20

input

output

digital

--.,

point

input

point

LABORATORY PERIPHERAL SYSTEMS DRIVERS
irate

is a 2-word integer array that specifies the
time interval between A/D samples.
The first
word specifies the interval unit as follows:
irate (1)

Unit

Real-time clock ticks

Milliseconds

Seconds

Minutes

The second word specifies
the
interval
magnitude as a 16-bit unsigned integer.
i.efn

specifies the number of the event flag that
is to be set each time a half buffer of data
has been collected.

i.chan

specifies 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

specifies the number of A/D channels
to be
sampled
(must be between 1 and 64 for LPSll
and between 1 and 16 for ARll).

isb

is a 2-word
integer array
subroutine status is returned.

nbuf

specifies 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

specifies 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 i f a
function selection value of 128 or
64 has
been added into imode.

is top

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

which

the

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

has

the

standard

meaning

described

Section

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

•

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16~4.19

SDAC:

Initiating Synchronous D/A Output

The SDAC FORTRAN subroutine writes datct 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
where:

(ibuf,ilen,imode,irate,iefn,ichan,nchan,isb,
[nbuf], [istart:], [istop])

ibuf

is an integer array that contains the
data values.

ilen

specifies the length of ibuf
(must
and greater than or equal to six).

imode

specifies the start, stop and sampling mode.
Its value is encoded by adding together the
appropriate function selection values
as
shown below:
Function
Selection
Values

irate

output
be

even

Meaning

128

Start on digital
set

Set digital
start

Stop on
clear

Stop on number of buffers

input

output

digital

point

input

point

is 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

Milli seconds

Seconds

Minutes

The second word specifies
the
interval
magnitude as a 16-bit unsigned integer.
iefn

specifies the number of the event flag that
is to be set each time a half buffer of data
has been output.

16-22

LABORATORY PERIPHERAL SYSTEMS DRIVERS
ichan

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

nchan

specifies the number of D/A channels to be
written
into
(must be between 1 and 10 for
LPSll and be l or 2 for ARll).

isb

is a
2-word
integer array
to
subroutine status is returned.

nbuf

specifies 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

specifies 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

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

which

the

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 zero
and the second word contains the number of free positions in the
buffer.

16.~l.20

SDO:

Initiating Synchronous Digital Output

into
The SDO FORTRAN subroutine writes data qualified by a mask word
Sampling
the digital output register at precisely timed intervals.
and all
may be started and stopped as for RTS (see Section 16.4.18)
One full
input
is double-buffered with
respect to the user task.
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], [istop])
whe ire:

ibuf

is an integer array that contains the digital
output values.

ilen

specifies the length of ibuf
(must
and greater than or equal to six).

16-23

even

LABORATORY PERIPHERAL SYSTEMS DRIVERS
imode

specifies the start, stop, and sampling mode.
Its value is encoded by adding together the
appropriate function selection values
as
shown below:
Function
Selection
Value

irate

Meaning

128

Start on digital
set

input

Set digital
start

Stop on
clear

Stop on number of buffers

output

digital

point

input

point

is a 2-word integer array that specifies the
time interval between digital outputs. The
first word specifies the interval units ~s
follows:
irate(l)

Unit

Real-time clock ticks

Milliseconds

Seconds
Minutes

The second word specifies
the
interval
magnitude as a 16-bit unsigned integer.
iefn

specifies the number of the event flag that
is to be set each time a half buffer of data
has been output.

imask

specifies the digital output points that are
to
be written.
It may be conveniently
specified as an octal constant.

isb

is a 2-word integer array to which the
subroutine status is returned.
specifies 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.

nbuf

istart

is top

specifies 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.
16-24

~.
i

l.ABORATORY PERIPHERAL SYSTEMS DRIVERS

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 zero
and the second word contains
the number of free positions in the
buff er.

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

IS.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 data values processed.

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 cancelled
IO.KIL or IO.STP) while in progress.

(via

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

IE .BYT

Byte-aligned buffer specified
Byte alignment was specified for a data buffer but
only
word alignment
is legal for Laboratory
Peripheral Systemsa
Alternately, 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.
(continued on next page)

16-25

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-8 (Cont.)
Laboratory Peripheral Systems Status Returns
Reason

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

IE. IEF

Invalid event flag number
An invalid event flag number was
synchronous function.

IE. I FC

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

Option not present
An option dependent function or subfunction was
requested,
and the required feature was not
specified at system generation.
For example the
gain-ranging option or D/A option is not present.
The second I/O status word contains zero.

IE.PR!

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.
(continued on next page)

16-26

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Table 16-8 (Cont.)
Laboratory Peripheral Systems Status Returns
Reason

Code
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
zero was specified.
The second I/O status word
contains zero.

FOR'rRAN interface values for these status
Sect.ion 16.5.4.

16.5.1

returns

are

presented

IE.RSU

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

I[ if specified)

IO.MDA

Digital output point (if specified) is in use

IO.MDI

Digital output point (if specified)
points to be sampled are in use

IO.MOO

Digital output point (if specified) or output
be written are in use

is in use

digital

input

bits

The following components of the Laboratory Peripheral Systems are each
considered a single resource:
Resource

When Sharable

The A/D Converter
and clock

Always sharable.

Each bit in the
digital output
register

Never sharable.

16-27

LABORATORY PERIPHERAL SYSTEMS DRIVERS
Resource

When Sharable

Each bit in the
digital input
register

Always sharable 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 sharable with another such
function.

Each resource is allocated on a first-come-first-served basis
(i.e.,
when a conflict arises,
the most recent request is rejected with a
status of IE.RSV).

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.

block,

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

Zero

IO .REL

Zero

IO.SDI

Masked value read from digital input register

I O.SDO

Updated value written into digital output register

IO.ADS

Number of data values remaining in buff er

IO.HIS

Number of data values remaining in buff er

IO.MCA

Number of free posttions in buffer

IO.MDI

Number of data values remaining in buff er

IO.MOO

Number of free positions in buff er

IO.STP

Zero

16-28

LABORATORY PERIPHERAL SYSTEMS DRIVERS

When IE.BAD is returned, the second I/O status word contains zero.
Laboratory Peripheral Systems drivers return the IE.BAD code under the
following conditions:
Function

When IE.BAD is Returned

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

No I/O status block or illegal
digital I/O point number

16 .5 .3

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
(177777
the user by placing illegal values in the data buffer. A -1
octal)
is placed in the buffer if an A/D conversion does not complete
within 30 microseconds.
A -2 (177776 octal) is placed in the buffer
if an error occurs during an A/D conversion (LPSll only).

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
IE .BAD
IE .BYT
IE.DAO
IE.DNR
IE. I EF
IE. I FC
IE. I LU
IE.NOD
IE .OFL
IE .ONP
IE .PR!
IE .RSU
IE .SDP
IE .SPC
IE. ULN
IE.UPN

16-29

LABORATORY PERIPHERAL SYSTEMS DRIVERS
16.6

PROGRAMMING HINTS

This
section
contains
information
on
important
pr9gramming
considerations relevant to users of the Laboratory Peripheral Systems
drivers described in this chapter.

16.6.l

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
16-bit buffer preset value, set dynamically or at system generation,
that controls the rate of "ticks" (i.e., 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 may 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.
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 65,536 different "tick" rates.
This provides a maximum
single-channel sample rate of l
sample every 100
microseconds
(possible in hardware but impractical in software) and a minimum of l
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:
l

request for l channel at 2.5KHz

request for 2 channels at 2.0KHz (aggregate 4KHz)

2 requests for l channel at 2.0KHz (aggregate 4KHz)
Digital rates:
l

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 uni-polar sampling.
Analog rates:
l

request for l channel at 3.3KHz

l request for 2 channels at 2.5KHz (aggregate 5.0KHz)
2 requests for l channel at 2.5KHz (aggregate 5.0KHz)
Digital rate:
2 requests for 2 channels at 3.3KHz (aggregate 6.6KHz)

16-30

memory

LABORATORY PERIPHERAL SYSTEMS DRIVERS
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.MOO).

16.6.3

Buffer Management

The buffer unload protocol for synchronous input functions
is
described below. The user constructs a five-word block that contains
the following:
IOSB:
CURPT:
LSTPT:
FSTPT:
'~

.BLKW
.WORD
.WORD
.WORD

I/O STATUS DOUBLE-WORD
ADDRESS OF BUFFER
ADDRESS OF END OF BUFFER
ADDRESS OF BUFFER

2
BUFFER
BUFFER+n
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 zeros both I/O status words to initialize them.
If the driver accepts the request, it sets up a write pointer to the
first word
in the user buffer.
Thus the user has a buffer read
pointer and the driver has a buffer write pointer. The user and the
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, butfer 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$:

4 0$:

CLE.F$ S
# EFN
;CLEAR EFN
;ANY DATA IN BUFFER?
TST
IOSB+2
BEQ
30$
;IF EQ NO
MOV
@CURPT,RO
;GET NEXT VALUE FROM BUFFER
DEC
IOSB+2
;REDUCE NUMBER OF ENTRIES
;UPDATE BUFFER READ POINTER
ADD
#2,CURPT
CMP
CURPT,LSTPT
;END OF BUFFER?
BLOS
20$
;IF LOS NO
;RESET BUFFER READ POINTER
MOV
FSTPT,CURPT
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

16-31

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 ADJLPS 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 INITIATE SYNCHRONOUS A/D SAMPLING,

INTVL(l)=2
INTVL(2)=5
CALL RTS(IBF,1004,160,INTVL,IEFN,6,6,IERR,50,l6,l5)

C INITIALIZE HALF BUFFER INDEX

INDX=4

C WAIT FOR HALF BUFFER OF DATA

c
c

CALL WAITFR(IEFN)

C CLEAR EVENT FLAG

CALL CLREF(IEFN)

C PROCESS HALF BUFFER OF DATA

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

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.O) GO TO end of sampling
GO TO 10

16-32'

for

LABORATORY PERIPHERAi. SYSTEMS DRIVERS

Synchronous output:
DIMENSION IBF(l004),IERR(2),INTVL(2)

C FIRST BUFFER OF DATA MUST BE AVAILABLE AT START

C THIS EXAMPLE ASSUMES FIRST BUFFER IS FULL AT START

C START SYNCHRONOUS DIGITAL OUTPUT FUNCTION

INTVL ( 1) =2
INTVL(2)=5
CALL SDO(IBF,1004,160,INTVL,IEFN,MASK,IERR,50,16,15)

C INITIALIZE HALF BUFFER INDEX

INDX=4

C WAITFOR ROOM IN BUFFER

CALL WAITFR(IEFN)

c
C CLEAR EVENT FLAG

c
c

CALL CLREF(IEFN)

C CALCULATE VALUES TO PUT IN BUFFER

X=(Y+2)*Z
DO 20 I=l,500
IBF(I+INDX)=X**5/A
CONTINUE

C SIGNIFY ANOTHER HALF BUFFER IS FULL

CALL ADJLPS(IBF,500)

c
C ADJUST BUFFER INDEX

INDX= INDX+500
IF ( IN DX • GE • 1 0 0 4 ) IN DX= 4

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

16-33

CHAPTER 17

PAPER TAPE READER/PUNCH DRIVERS

17.l

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 eight-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
the paper tape
r~ader 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 l indicates that
the described characteristic is true for these devices.

'-""'

Bit

§etting

Meaning

Record-oriented device

Carriage-control device

Terminal device

File structured device

Single-directory device

Sequential device

Reserved

User-mode diagnostics supI?orted

MAS SB US device

Unit software write-locked

Input spooled device

Output spooled device

17-1

PAPER TAPE READER/PUNCH DRIVERS
Meaning

Bit

Setting

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

Attach device
Detach device
Cance·l I/O requests
Read logical block (reader
Read virtual block (reader
Write logical block (punch
Write· virtual block {punch

QIO$C
QIO$C
QIO$C
QIO$C
QIO$C
QIO$C
QIO$C

I 0. ATT, •••
I 0. DET, •••
IO.KIL, •••
IO.RLB, ••• ,<stadd,size>
IO.RVB, ••• ,<stadd,size>
IO.WLB, ••• ,<stadd,size>
IO.WVB, ••• ,<stadd,size>

where:

stadd

is the starting address of the data buffer (may be
on a byte boundary)

size

is the data buffer size in bytes (must be
than zero)

only)
only)
only)
only)

greater

IO.KIL never cancels an in-progress read request~
In-progress write
requests are cancelled 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.

l~.4

STATUS RETURNS

Table 17-2 lists error and status conditions that are returned by
paper tape reader/punch drivers.

the

17-2

PAPER TAPE READER/PUNCH DRIVERS
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 zeros.

rn .ABO

Operation aborted.
The I/O request was cancelled while
while still in the I/O queue.

r:E: .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 ~ondition (s~e 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/lPUNCH DRIVERS

Table 17-2 (Cont.)
Paper Tape Reader/Punch Status Returns
Code
IE. I FC

Reason
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 LIJN
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 zero
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

where n is the unit number of the paper tape punch that is not
ready.
This message is repeated every 15 seconds until the error condition is
corrected, or until the I/O request
is cancelled.
When the error
condition has been corrected,
the transfer will begin within one
second.

17-4

PAPER TAPE READER./PUNCH DRIVERS
17.S

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the paper tape drivers described
in this chapter.

17.S.l

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

CHAPTER 18

INDUSTRIAL CONTROL SUBSYSTEMS

18.l

INTRODUCTION

This chapter describes RSX-llM drivers for two process I/O subsystems:
the ICS/ICRll and the DSS/DRSll.
(I/O subsystems driver support 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.l

Hardware Configuration

A single res or rcR controller can handle up to 16 r/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 ICS units
are supported.
The ICS/ICR 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.l ICS/ICR Address Assignments - Each ICRllA Unibus
interface
or rcs11
file box must be configured at SYSGEN time for individually
addressable interrupt vectors, Control and Status Registers
(!CSR),
and module Address Registers (!CAR) as shown in Table 18-1.

18-1

INDUSTRIAL CONTROL SUBSYSTEMS

Table 18-1
ICS/ICR Address Assignments
ICS/ICR UNIT NO.

MODULE ADDRESSES

ICSR/ICAR ADDR. INTERRUPT VECT.

171000-171036

171770-171776

234-236

171040-171076

171760-171766

XXX-XXX+2

171100-171136

171750-171756

XXX+4-XXX+6

171140-171176

171740-171746

XXX+l0-XXX+l2

171200-171236

171730-171736

XXX+l4-XXX+l6

1 7 12 4 0-1 7 12 76

171720-171726

xxx+20-xxx+22

171300-171336

171710-171716

xxx+24-xxx+26

171340-171376

171700-171706

xxx+30-xxx+32

171400-171436

171670-171676

xxx+34-xxx+36

171440-171476

171660-171666

xxx+40-xxx+42

171500-171536

171650-171656

xxx+44-xxx+46

1 71540-171576

171640-171646

xxx+50-xxx+52

NOTES
nnnnn6 = Control and Status Register
nnnnn4 = Address Register
Additional controllers
are
vector addresses above 300.

assigned

18.1.1.2 DSS/DRS Address Assignments - Unlike the ICS/ICR subsystem,
DSS/DRS devices are not restricted to specified bus addresses. The
following constraints apply, however:
1.

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

not

exceed

If both module types are installed in a system,
the DRSll
must occupy the lower set of bus and interrupt-vector
addresses.

Bus request priority is BR4.

18-2

may

INDUSTRIAL CONTROL SUBSYSTEMS
18.l.l.3 Supported ICS/ICR I/O Modules - The following
optional, are supported by the ICS/ICR driver.

modules,

all

D/A Converters
IDA-OA -

4-channel digital-to-analog converter.

A/D Converters
IAD-IA IMX-IA -

analog-to-digital
8-channel wide-range differential
converter.
16-channel flying capacitor relay multiplexer.

Counters
IDC-IC -

16-bit binary counter.

Bistable Digital Outputs
IDC-OA -·
IAC-OA -·
I RL-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
required,
then
ICRll controller, and if a driver of minimum size
is
UDCll support should be considered.
The hardware requirements for
such support are as follows:
l.

Each file box must be assigned to the same
address {normally 2 34) •

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

The control and status register within each file box must
appear at the same address within the I/O page (normally
171776).

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

Regardless of the actual number of IMX-IA multiplexers
installed,
each
converter
preempts a block of eight
contiguous module slots.

The slots reserved for all A/D converters and
must occupy a block of contiguous module slots.

multiplexers

If necessary, the vector and address changes can be made by Field
Service personnel.
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.

Multi-controller, 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.

18-4

INDUSTRIAL CONTROL SUBSYSTEMS
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)

NOTE
All functions listed in this subsection
Those which
apply to ICS/ICR modules.
and/or
DRS
also apply to the DSS
subsystems are so marked.
Driver requests are divided into the following categories:
1.

Noninterrupting output functions
a..

Bistable

(flip-flop) digital output

Analog output

Momentary

(DRS)

(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

18-5

INDUSTRIAL CONTROL SUBSYSTEMS
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:
1.

A/D inputs

Remote terminal output

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

Counter modules

Remote terminal input

Error interrupts

(DSS/DRS)

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 chara~ter 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 funciion of
IO.RAL.
~nvoked.

MCR is not

Characters are not echoed.

Carriage control is not performed.

TABs, RUBOUTs, etc.

Line terminators are not recognized.

Fill characters are not generated.

18.1.4

are not recognized.

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

INDUSTRIAL CONTROL SUBSYSTEMS

Module Addressing Conventions

18.1.5

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.
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 (e.g.,
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 fol~ows:
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-2
Sample ICS/ICR Configuration

Unit:

Slo1t Number
9.
10.
11.
12.
13.
14.
15.
16.
17.

Type

Bus Address

Relative Addresses

171000
171002

0-3.
0-119.

D/A Converter
A/D Converter
A/D Multiplexer
Counter
Flip-Flop driver
D/A Converter
Flip-Flop driver
Counter
A/D Converter

Table 18-3 is an example of
the
interrupt
points,
and point
con:Eiguration.

------

171006
171010
171012
171014
171016
171020
relationship
numbers
for

-----

0
0-15.
4-7.
16 .-31.
1.
120.-239.

among bus addresses,
a
sample DSSll/DRSll

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

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-3
Sample DSS/DRS Configuration

18.2

Bus Addresses

Module Type

Points

Interrupt Point

160030-160036
160040-160046

DRSll
DRSll

0-47.
48.-95.

0
l

170010-170016
170020-170026

DSSll
DSSll

0-47.
48.-95.

2
3

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 indicated by
a footnote are supported by the DSS/DRS driver.
Table 18·-4
Summary of Industrial Control QIO Functions
Function

Format
QIO$C I-0.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 buff er to
terminal interrupts

QIO$C IO.DC!, •••

Disconnect a buffer from
digital interrupts

QIO$C IO.DTI, •••

Disconnect a buffer from
counter interrupts

QIO$C I 0. DTY, •••

Disconnect a buffer from
terminal 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.FLN, •••

Set controller off line

QIO$C IO.ITI, ••• ,<mn,ic>

Initialize a counter

1QIO$C IO.LDI, ••• ,<tname, [,tevf],
pn,csm>

Link task to digital
interrupts

QIO$C IO.LKE, ••• ,<tname, [,tevf]>

Link task to error
interrupts

QIO$C IO .. LTI, ••• ,<tname, [,tevf]
cn[,arv]>

Link task to counter
interrupts

QIO$C IO .. L'l'Y, ••• ,<tname, [, tevf] >

Link task to remote
terminal interrupts

1QIO$C IO .. MLO, ••• ,<opn,pp,dp>

Open or close bistable
digital output points

QIO$C IO.MSO, ••• ,<opn,dp>

Pulse momentary digital
output points

1QIO$C IO.NLK, ••• ,<tname>

Unlink a task from all
interrupts

QIO$C IO.ONL, •••

Place ICS/ICR controller
online

1QIO$C IO.RAD, ••• ,<stadd>

Read activating data

QIO$C IO.RBC, ••• ,<stadd,size,
stcnta>

Initiate multiple A/D
conversions

QIO$C IO.SAO, ••• ,<chn,vout>

Perform analog output

1QIO$C IO.UDI, ••• ,<tname>

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 !CR
remote terminal

1 These functions are supported by the DSS/DRS driver.

18-9

INDUSTRIAL CONTROL SUBSYSTEMS

Where:
arv

is the starting address of a buffer containing initial
or reset counter values. The buffer must be aligned on
a word boundary.

chn

is the D/A channel number

is the counter number

csm

is the change-of-state mask

is the binary data pattern

is the initial count

is the module number

opn

is the first bistable (latching) digital output point
number.
This value must be on a module boundary
(evenly divisible by 16)

is the point number
boundary)

is a 16-bit mask

sizb

is 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

is the data and control buffer size in bytes.
This
value must be an even number that is greater than zero.

stadd

is the starting address of the data buffer (must be
a word boundary)

staddb

is the starting address of the terminal output
May be aligned on a byte boundary

st en ta

is 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

is an event flag number in the range 0 to 96,
(if the
group-global event flag SYSGEN option was selected), or
0 to 64 if group-global event flags are not supported

tname

is a task name composed of l
to 6 alphanumeric
characters in a 2-word RADIX-SO format. Two arguments,
each containing three characters, are required for this
parameter.
For example, the task name ICNAME is
specified as:

(must

assigned

module

buffer.

If the task name is less than 4 characters, a null
argument must be specified as follows for task ABC:

<""RABC,, ••• >
vout

is a binary number between 0 and 1023.
converted to an analog output

18-10

that is

~
'

INDUSTRIAL CONTROL SUBSYSTEMS
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 O 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 O as the first channel on the
first module of a given type.
Point numbers start at O with point 0 as the first point on the first
m6dule 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
example,
digital points 15(10)
and 16(10)
need not
reside
on
physically adjacent modules.
This restriction does apply to DSS/DRS
modules, however.
It is assumed that the number of points or channels per module
is a
constant for each generic type. Specifically the following weights
apply:

.._.,.,.

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

when

all

INDUSTRIAL

18.3.1.l

CONTROJ~

SUBSYSTEMS

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

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 (e.g., MARK TIME).

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

lun specification in a QIO
issuing task.
For example,
numbers associated with the
lun was greater than five.

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

I/O Conditions

IE.ABO - Operation aborted.
The specified operation was cancelled via
IO.KIL or the request timed out while the unit was offline.
IE~OFL

- Controller offline.
The physi.cal device unit associated with
the LUN specified in the QIO directive was not online. An
ICS/ICR controller may be offline because a device check
during bootstrap load has indicated that the controller is
not in the configuration.

IE.DNR - Controller not ready.
been detected.
IE.IFC -

A nonrecoverable controller error

has

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

INDUSTRIAL CONTROL SUBSYSTEMS
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>
where:
st add

the starting address of the data buffer
word boundary).

size

the data buffer size in bytes (must be even and greater
than zero);
the control buffer is the same size.

stcnta

the starting address of the control buffer (~ust be on
a word boundary);
each control buffer word must be
constructed as shown in Table 18-5.

(must be

Return Status:
Is.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.

length

IE.DNR -

interrupt

timeout

Device not
occurred.

ready.

A/D

converter

Note that the second I/O Status word contains
number of conversions successfully completed.

count

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 receipt and validation of the parameters within the I/O
the driver will initiate the following sampling procedure:

packet,

The control word is fetched and tested for
validity
(i.e.,
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 noninterrupt 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 l.
18-13

INDUSTRIAL

CONTROi~

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

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

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

Gain

1
2
illegal
illega 1
10
20
illegal
illegal
50
100
i llega 1
illegal
200
1000
illegal
illegal

The converted value is returned as 12 bits,
left-justified,
in a 16-bit word, with the low order 4 bits set to zero.

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
(e.g.,
a
hardware error and an erroneous control word).
The driver will return
the status associated with the earliest transaction that caused an
error condition. Thus, at the user interface, the driver will appear
to execute all conversions sequentially.

18.3.3

Analog Output

This function provides the capability
output channel to a specified voltage.
Q I 0 DP B for ma t :
QIO$C IO.SAO, ••• ,<chn,vout>

18-14

setting

single

analog

INDUSTRIAL CONTROL SUBSYSTEMS
where:
chn

= the output channel number

vout

= the output voltage representation

Output voltage varies linearly with the binary input to the channel,
where 0 to plus ten 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 zero.

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$C IO.MSO, ••• ,<opn,dp>
where:
opn

= the starting digital output point number.
Point number
must be aligned on a module boundary {i.e., must be a
multiple of 16).

the 16-bit mask.
One point is pulsed corresponding
each bit set in the mask word.

Return Status:

rs.sue -- Function submitted for output to the controller.
IE.MOD -

18.3.5

Invalid starting point number specified.
Point
nonexistent or not aligned on a module boundary.

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>
where:
opn

the starting digital output point number.
Point number
must be aligned on a module boundary {i.e., must be a
multiple of 16).

18-15

INDUSTRIAL CONTROL SUBSYSTEMS
pp

the 16-bit mask.

= 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 will be "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 -

18.3.6

Invalid starting point number specified.
Point does not
exist or is not aligned on a module boundary.

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

The driver will allow continual monito1:ing 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
~
':

18-16

INDUS~RIAL

CONTROL SUBSYSTEMS

The buffer to be connected has the format shown below:
~

FORTRAN
Index

Contents

driver index

user index

word 0 of entry

word l of entry

The buffer consists of a two-word header containing the driver and
user
index, as 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 add~ess,
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 zero.
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, i.e., 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.

18-17

INDUSTRIAL CONTROL SUBSYSTEMS
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:
WO 00

Hardware error indicator

WO nn
WO nn+l
WO nn+2

Contents of !CSR register
Physical unit number
Generic code indicator
set to 177770 (8)

(+2)

nn = offset to module data word.
This entry is always placed
status.

the

buffer

regardless

overflow

The error flags are obtained from the controller !CSR word at the time
the error was detected (see Table 18-7).

18.3.6.l Connect to Digital Interrupts - This
single task to receive digital interrupt data.

function

allows

connected

(must

QIO OPB format:
QIO IO.CCI, ••• ,<stadd,sizb,tevf>
where:
st add

starting address of buffer to
word aligned)

sizb

length of buffer in bytes
buffer length is 14 bytes

tevf

trigger event flag number

(must

even).

Minimum

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

IE.CON -

Interrupt already connected to another task.

IE.IEF -

Invalid event flag number.

odd

IE.PR! - Task checkpointable and not fixed in memory.
IK.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 (7 words minimum).

18-18

INDUSTRIAL CONTROL SUBSYSTEMS
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 l, 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 l 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 l, 2 or 3
as selected by user-installed jumpers on the module.

18.3.6.2 Disconnect from Digital Interrupts - This function allows
task to terminate the processing of digital interrupt data.

QIO DPB format:
QIO$C IO.DC!, •••
Return Status:

rs.sue - Function successfully completed.

Second I/O status

word

zero.
IE.CON - Task was not connected.

Second I/O status word is zero.

18.3.6.3 Connect to Counter Module Interrupts - This function
a single task to receive counter interrupt data.

allows

QIO DPB formc:tt:
QIO$C IO.CTI, ••• ,<stadd,sizb,tevf,arv>
whe ire:

st add

starting address
aligned)

sizb

length of buff er in bytes
buffer length is 12 bytes.

tevf

trigger event flag number

arv

= starting address of table

circular

(must be word aligned)

18-19

buff er

(must

initial

(must
even).

counter

word

Minimum

values

INDUSTRIAL CONTROL SUBSYSTEMS
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 (i.e., when the count reaches
zero).
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.

IE.IEF -

Invalid event flag number.

odd

IE.PR! - Task checkpointable and not fixed in memory.
IE.SPC -

Interrupt circular buffer or table of initial values was
not wholely within the address space of the task.
Alternately, the buffer was too small for a single data
entry (6 words minimum).

Entry Format:
WD 00 -

Existence indicator

WD 01 - Module data
WD 02 - Relative module number
WD 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>
where:
mn

relative module number

new initial count

Return Status:

rs.sue - New value submitted for output to the

controller.
second word of I/O status is set to zero.

The

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 will
be
reinitialized with this value on overflow if a task
is connected to
counter interrupts.

18-20

AL.

INDUSTRIAL CONTROL SUBSYSTEMS
18.3~6.5
Disconnect from Counter Interrupts - This function allows
task to terminate counter interrupt processing.

QIO DPB format:
QIO$C IO.OT!, •••
Retu1rn Status:

rs.sue - Function successfully completed.

The

second

word

I/O

reset

the

status is set to zero.
IE.CON -

Task was not connected to timer interrupts.

After disconnect is complete,
counters will
initial value at the time of the interrupt.

not

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>

where:
st add

address of circular buffer

,s izb

length of buffer
is 12 bytes.

tevf

trigger event flag number

(must be word aligned)

(must be even).

Minimum buffer length

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

IE.CON -

Interrupt already connected to another task.

IE.IEF -

Invalid event flag number.

IE.MOD - Nonexistent device.
IE.SPC -

number

Controller is ICSll.

Interrupt circular buffer was not wholly within the
address space of the task.
Alternatively, the buffer
was too small for a single entry (6 words minimum).

Entry Format:
WD 00 - Existence indicator
WD 01 -

High byte

= O, low byte = terminal input character

WD 02 - Relative module number

(normally 0)

WD 03 - Generic code indicator

(normally 0)

18-21

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:
IS.sue - Function successfully completed.
status is set to zero.

The second word of I/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 (i.e., made eligible for activation) provided that:
1.

the resource exists,

the task is installed, and

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

18-22

INDUSTRIAL CONTROL SUBSYSTEMS
ensured prior to the completion of task execution by issuing the
If system directive followed by the Clear Event Flag directive.

Exit

The linkage between a task and a specific
interrupt is
removed
issuing the appropriate unlink request via the QIO directive.

Only one task may be associated with each interrupt source (i.e.,
one
task per digital interrupt point, terminal input, or counter module.
NOTE
The MCR command REMOVE automatically
unlinks a task from all interrupts.

18.3.7.1 I.ink a Task to Digital Interrupts - The following function
allows a task to be activated on the occurrence of digital interrupts.
QIO DPB format:
QIO$C IO.LOI, ••• , <tname, [, tevf], pn, csm>
where:
tname

a 1- to 6-character alphanumeric task name
Radix-SO format

tevf

trigger event flag

point number

csm

change-of-state mask

2-word,

(O=none)

(must be aligned on a module boundary)

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
intE~rrupt point.
A zero change of state mask is not permitted.
Return Status:

rs .sue

Function successfully completed.
I/O status is set to zero.

IE.BAD

Change-of-state mask set to zero.

IE.IEF

Invalid event flag number.

IE .MOD

Nonexistent module or point not aligned
boundary.

IE .NOD

Insufficient dynamic
control block.

IE .NST

Task "tname" is not installed.

IE.RSU

One or more of the specified points is in use by other
tasks.

18-23

memory

The second

allocate

word

module

secondary

INDUSTRIAL CONTROL SUBSYSTEMS
18.3.7.2
task to
module.

Link a Task to Counter Interrupts - This function

allows a
activated by means of an interrupt from a single counter

QIO DPB format:
QIO$C IO.LTI, ••• ,<tname, [,tevf],cn[,ic]>
where:
tname

a 1- to 6-character alphanumeric task
Radix-SO format.

tevf

trigger event flag

relative module number

= counter value (optional)

name

2-word

(O=none)

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 zero.
Return Status:

Is.sue

Function successfully completed.
I/O status is set to zero.

IE. IEF

Invalid event flag number.

IE.MOD

Nonexistent module specified.

IE .NOD

Insufficient dynamic memory to
control block.

IE.RSU

Counter is linked to another task.

The second

allocate

word

secondary

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]>
where:
tname

a 1- to 6-character alphanumeric task name
Radix-SO format.

tevf

trigger event flag

2-word,

(O=none).

Return Status:

Is.sue

Function successfully completed.
I/O status is zero.

IE. I EF

Invalid event flag number.

IE .MOD

- Nonexistent module

The

second

(unit is ICSll controller).

18-24

word

INDUSTRIAL CONTROL SUBSYSTEMS
IE.NOD

IE .NST

- Task "tname" is not installed.

IE .RSU

insufficient dynamic
control block.

storage

allocate

secondary

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
receive error
error interrupts.
Once linked, the selected task may
reports from any !CR controller.
QIO DPB format:
QIO$C IO.LKE, ..•• ,<tname, [,tevf]>
where:
tname

a 1- to 6-character alphanumeric task
Rad:ix-50 format.

tevf

trigger event flag

name

2-word

none)

Return Stat.us:

rs .sue

Function successfully completed.
I/O status is zero.

IE.IEF

Invalid event flag number.

IE.IFC

No ICRll subsystems are installed.

IE .NOD

Insufficient dynamic
control block.

IE .NS'l~

Task "tname" is not installed.

IE .RSU

Another task is linked to error interrupts.

storage

The second

allocate

18.3.7.5 Read Activating Data - This function allows
determine the conditions that caused it to be activated.

word

secondary

task

QIO DPB format:
QIO$C IO.RAD, ••• ,<stadd>
where:
st add

address of 6-word buffer
(must be word aligned).

receive

The buffer receives data in the following format:
WD 00

- Activation indicator

WD 01

- Physical unit number

WD 02

- Generic Code

18-25

activation

data

INDUSTRIAL CONTROJL. SUBSYSTEMS

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.
The generic code is identical to that :specified
entries, namely:
0 -

that

received

the

for

circular

buffer

generic

code

will

Terminal (Control-C)

1,2,3 - Digital interrupt
4,5,6 - Counter interrupt
177770 - Fatal controller error
Hardware-dependent data is
consist of the following:

associated

with

and

Terminal:

WD 04

Terminal buffer contents

WD 05

undefined

(low byte)

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 !CSR register

(see Table 18-7)

woos

Contents of !CAR register

(see Table 18-8)

Return Status:

rs.sue - Function successfully completed.

The second word of I/O

status is zero.
IE.BYT -

Buffer address is aligned on an odd byte boundary.

18-26

INDUSTRIAL CONTROL SUBSYSTEMS
IE.NLK -

Task "tname" was not linked to interrupts.

IE.SPC -

Buffer not totally within the task's address space.

18.3.7.6 Unlink a Task from Interrupts - The functions
the following paragraphs provide the capability of:

described

Unlinking a task from all interrupts on a controller,

Selectively unlinking a task from interrupts by module type.

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,o •• ,<tname>
where:
tname

1- to 6-character
Radix-50 format.

alphanumeric

task

name

rs.sue -

Function successfully completed.
I/O status is zero.

The

second

IE.NLK -

Task "tname" was not linked to interrupts.

2-word

Return Status:

word

task

from

all

a 1- to 6-character alphanumeric task
Radix-50 format.

name

rs.sue -·

Function successfully completed.
I/O status is zero.

second

word

IE.NLK -

Task "tname" was not linked to the specified
interrupt.

class

IE.NST -

Task not installed.

IE.MOD -

Nonexistent module type specified.

from

all

Unlink a Task from all Digital Interrupts

This function provides the capability of unlinking
digital interrupt points on a controller.

QIO DPB format:
QIO$C IO.UDI, ••• ,<tname>
where:
tname

2-word

Return Status:

The

Unlink a Task from Counter Interrupts

This function provides the capability of unlink i/ng
counter module interrupts.

18-27

task

INDUSTRIAL CONTROL SUBSYSTEMS
QIO DPB format:
QIO$e IO.UTI, ••• ,<tname>
where:
tname

a 1- to 6-character alphanumeric task· name
Radix-50 format.

2-word

Return Status:

IS.sue -

Function successfully completed.
I/O status is zero.

The

second

word

IE.NLK -

Task
"tname"
interrupts.

linked

the

specified

IE.NST -

Task not installed.

IE.MOD -

Nonexistent module type specified.

unlinking

was

not

Unlink a Task from Terminal Interrupts

This function
provides
terminal interrupts.

the

capability

task

from

2-word

QIO DPB format:
QIO$e IO.UTY, ••• ,<tname>
where:
a 1- to 6-character alphanumeric task
Radix-50 format.

name

Is.sue -

Function successfully completed.
I/O status is zero.

The

second

word

IE.NLK -

Task
"tname"
interrupts.

the

specified

IE.NST -

Task not installed.

IE.MOD -

Nonexistent module specified (i.e., device is an
controller).

tname
Return Status:

was

not

linked

ICSll

Unlink a Task from Error Interrupts

This function provides the capability of unlinking
error interrupts.

task

from

name

all

QIO DPB format:
QIO$e IO.UER, ••• ,<tname>
where:
tname

1- to 6-character
Radix-50 format.

alphanumeric

18-28

task

2-word

INDUSTRIAL CONTROL SUBSYSTEMS
Return Status:

rs.sue -

Function successfully completed.
I/O status is zero.

IE.IFC -

No ICRll controllers exist in the system.

IE.NLK -

Task "tname" was not linked to error interrupts.

IE.NST -

Task not installed.

18.3.8

The

second

word

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>
where:
staddb

Buffer address (may be odd)

sizb

Byte count (may be odd)

Return Status:
IS

.sue

IE .MOD

'-".·

18.3.9

Function successfully completed. Second word
status contains the number of bytes output.
Nonexistent hardware function.
an ICSll controller.

I/O

Request was 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.9.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 timeouts are ignored. The occurrence of device
timeout while A/D conversion or remote terminal input is in progress
results in termination of the request with the error code IE.ABO.

18-29

INDUSTRIAL CONTROJI:. SUBSYSTEMS

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

digital,

counter,

remote

terminal

Disconnect
interrupts

Unlink from interrupts

Read activating data

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

IE.FRI

Task not privileged.

18.3.9.2 Enable Hardware Error Repor1:ing - 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 online.
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 .PRI

Task not privileged.

18.3.10

Special Functions

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

INDUSTRIAL CONTROL SUBSYSTEMS

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

Function successfully completed.

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.
(but not
Unless specifically noted, all subroutines are reentrant
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.

1.7\SISLN

Assign a LUN to a DSS/DRS controller.

CTDI

Connect a circular
interrupt data.

buffer

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.

input

random
channels

ICRll

remote

1 These subroutines are supported by the DSS/DRS driver.
(continued on next page)

18-31

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18-6 (Cont.)
FORTRAN Interface
Function

Subroutine
DFTI

Disconnect a buffer from counter interrupts.

DFTY

Disconnect
interrupts.

loI/DIW

Read several 16-point digital sense fields

looL/DOLW

Latch or unlatch several 16-point
fields.

bistable

output

DOM/DO MW

Pulse multiple 16-point
fields.

digital

output

buff er

from

terminal

remote

momentary

(D).

Link a task to unsolicited interrupts.
OFLIN

Suppress error reporting.
status.

Place unit in not

ready

ON LIN

Enable error
status.

Return

ready

RCIPT

Read a single digital interrupt point {D).

lRDACT

Read interrupt activation data.

RODI

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
Return a full data word.

RSTI

Read a single counter module {D).

RTO/RTOW

Perform output to a remote ICRll terminal.

luNLNK

Unlink a task from unsolicited interrupts.

reporting.

circular

unit

buffer.

1 These subroutines are supported by the DSS/DRS driver.

18.4.1

Synchronous and Asynchronous Process Control 1/0

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
{e.g., 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

18-32

INDUSTRIAL CONTROL SUBSYSTEMS
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 zero. The ISA standard
code for this condition is +2.

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.
is also required for
For compatibility, the two-word status block
status returned by the direct access calls.
Errors of this type that
may be returned are:
Word 1

Number of points requested is zero.

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
detected by the interface subroutine

3<Word l< 300.

QIO directive
rejected.
code = -(WORD 1 - 3)

Word 1

300

Actual

Request rejected by driver.
error code = -(WORD 1 - 300)

error
Actual

Table 18-7 lists all possible status values:
the FORTRAN value,
assembly language mnemonic, actual value, and related definition.

18-33

INDUSTRIAL CONTROL SUBSYSTEMS
Table 18·-7
Return Status Summary
FORTRAN
Interface
Value

Assembly
Language
Value

Assembly
Language
Mnemonic

Definition

IS .PND

Operation pending.

rs.sue

Successful completion.

none

Error detected in FORTRAN calling
sequence.

-1

IE .UPN

Insufficient dynamic
allocate I/O packet.

-5

IE.ULN

Unassigned LUN.

-6

IE.LNL

LUN usage interlocked.

+99

-96

IE. !LU

Invalid LUN.

+100

-97

IE.IEF

Invalid event flag number.

+101

-98

IE.ADP

Part of DPB
out
addressing space.

+102

-99

IE.SOP

Invalid DIC or DPB size.

+301

-1

IE.BAD

Bad parameters.

+302

-2

IE. I FC

Invalid I/O function code.

+303

-3

IE .DNR

Device not ready.

+306

-6

IE.SPC

Illegal buffer.

+315

-15

IE.ABO

R13quest aborted.

+316

-16

IE. PR!

Privilege violation.

+317

-17

IE .RSU

Rc3sou rce in use.

+319

-19

IE .BYT

Buffer address or length is 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 offline.

+381

-81

IE.NST

Task is not installed.

+397

-97

IE.IEF

Invalid event flag number.

storage

user's

~\
.

18-34

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

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.3

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

[, ival])

If the argument ival is to be omitted, the calling sequence would be:
CALL XYZ(IBUF,ILEN)
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
Output - ASICLN/ASUDLN (ICS/ICR) and ASISLN (DSS/DRS)

and

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
the assign lun directive.

iunt

An optional integer variable that specifies the unit
number to be assigned.
Assumed to be zero if omitted.

18-35

result

INDUSTRIAL CONTROi(, SUBSYSTEMS

Return Status:
The following values are returned t6 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:.
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:
1.

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
!Cl:.
>ASN !Cl:

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 one
(1)
for
the
unit number
in response to the GET LUN
Information directive.
This value will be stored and
later
referenced whenevE~r t'he 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-36

INDUSTRIAL CONTROL SUBSYSTEMS

18.4ti5

Analog Input

The following routines provide the capability of performing A/D input:
AIRD/AIRDW -

ISA Standard call to read multiple channels
in random
order.
This call requires one or more control variables
containing A/D channel and gain in the format
shown in
Tabl~ 18-5 (Section 18.3.2).

AISQ/AISQW -

ISA Standard call
sequential order.

read

multiple

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

idat

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:

channels

Conversion successfully completed.
The second
word contains the number of channels converted.

Number of channels requested was zero.

Insufficient
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
user's addressing space.

+319

Control or data buffer is byte aligned.

dynamic

18-37

storage

not

allocate

wholly

within

I/O

the

INDUSTRIAL CONTROL SUBSYSTEMS
lun

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 three IAD-IA A/D converter modules at a gain of 1.

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

0
l
2
3
120
121
122
123

240
241
242
243

-A/D MODULE 0

-A/D MODULE l

-A/D MODULE 2

C INTERLEAVED SEQUENCE FOR MAXIMUM
C THRUPUT.

c
c
c
c
c
c
c

c
c
c
c
c
c

0
120
240
l

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

DIMENSION !CONT (3,4)

c
c INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 0
c
DATA ICONT(l,l),ICONT(l,2),ICONT(l,3),ICONT(l,4)/0,l,2,3/

c INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE l
18-38

INDUSTRIAL CONTROL SUBSYSTEMS

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
c

DATA ICONT(3,l),ICONT(3,2),ICONT(3,3),ICONT(3,4)/240,241,242,243/

C ALLOCATE STORAGE FOR DATA ARRAY
C IN SIMILAR FASHION TO FACILITATE
C CHANNEL REFERENCES

c
DIMENSION !DATA (3,4)

c
C

BEGIN EXECUTABLE STATEMENTS

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

Conversion successfully completed.
The second
word contains the number of channels converted.

Number of channels requested was zero

Insufficient
packet

dynamic

18-39

storage

allocate

I/O

INDUSTRIAL CONTROL SUBSYSTEMS

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
user's addressing space

+319

Control or data buffer is byte aligned

lun

not

wholly

within

the

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

DIMENSION ICONT(S)
DATA ICONT(l),ICONT(2),ICONT(3)/0000003,0010000,0050000/
DATA ICONT(4),ICONT(5)/0l00000,0l50000/

c
C ALLOCATE SPACE FOR DATA ARRAY

c
DIMENSION !DAT (5)

c
C INITIATE SEQUENTIAL, ASYNCHRONOUS CONVERSION
C VIA LUN 1

CALL AISQ(S,ICONT,IDAT,ISB,l)
IF(ISB(l).NE.O) GO TO 20
(continue processing)

c
C TEST CONVERSION STATUS

GO TO 10

18-40

INDUSTRIAL CONTROL SUBSYSTEMS

(test for errors or process converted data)

END

18 .4 ,.6

AO/AO•f:

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 ••• etc.)
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 O and 1023 where:

0 = 0 volts de and
1023
isb

lun

= +9.99 volts

(full scale).

Optional 2-word integer array to receive status.
of the following values is returned in isb(l).
second element is always zero.
+l

Function successfully completed.

Zero channels requested.

Insufficient dynamic storage to
packet.

LUN was not assigned.

+99

Invalid LUN.

+303

Controller not ready.

+321

Nonexistent channel

allocate

spec~fied.

Integer variable containing the logical unit number.

18-41

One
The

I/O

INDUSTRIAL CONTROL SUBSYSTEMS

Example:
Output the variable voltages contained
channels 2 and 3 respectively.

IV(l)

and

IV(2)

D/A

c
C ALLOCATE DATA ARRAY

DIME NS ION IV ( 2)

C ALLOCATE CONTROL ARRAY

DIMENSION ICNT(2)

C ALLOCATE STATUS ARRAY

DIMENSION !SB ( 2)

C INITIALIZE CONTROL ARRAY

DATA ICNT(l),ICNT(2)/2,3/

c
C PERFORM A/D OUTPUT VIA LUN 3

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 ••• etc.)
Argument Descriptions:
inm

Integer variable specifying the number of fie1ds 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.

·~1

18-42

INDUSTRIAL CONTROL SUBSYSTEMS

Integer array containing binary data that defines
points within the field for which a change of state is
permitted.

imsk

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

,...,,.

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

Function successfully completed.

Zero points specified.

Insufficient dynamic storage to
packet.

LUN not assigned.

+99

Invalid LUN.

allocate

I/O

+303

Controller not ready.

+321

Nonexistent point number specified. One
points within the field do not exist.

lun

Integer specifying the Logical Unit Number.

Example:
Reset points 0,1,20 and 21

DIMENSION ICNT(2),IDAT(2),IMSK(2)

C INITIALIZE THE CONTROL ARRAY

DATA ICNT(l),ICNT(2)/0,20/

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

!CR IS ASSIGNED

CALL DOLW(2,ICNT,IDAT,IMSK,,3)

18-43

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 (!BCD).
Binary data can be converted to BCD through the FORTRAN function
IBCD=KB2BCD (!BIN).
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.1 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 ••• etc.)
Argument Descriptions:
inm

Integer variable specifying the number of fields to
read.

icnt

Integer array containing the initial
each field.

point

number

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
fol lows:

iun

Function succesfully completed.

Zero points requested.

+321 -

Nonexistent point requested.
One or more points within
the 16-bit field does not exist.
Optional integer variable specifying the physical
number.

18-44

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

2-word integer array to receive status
follows.
Status is returned to isb(l).
+l

+321 -

Function successfully completed. Data is
isb(2) as a logical value, where:
• TRUE.

(-1)

• FALSE.

( 0)

data

returned

Point closed •
Point open •

Nonexistent point specified.
Optional integer variable defining
number.

iun

and

the

Example:
Read the state of contact interrupt point 3 on unit O.
DIMENSION !SB (2)

CALL RCIPT (3,ISB,O)
IF (ISB(2).EQ •• FALSE.) go to point open routine.

18-45

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 ••• etc.)
Argument Descriptions:
inm

Integer variable specifying the number of fields to
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
inteqer
variable
retained
compatibility with the standard form of the call.

isb

Optional 2-word integer array to receive the results of
the ca 11 a s f o 11 ow s i n :l s b ( l ) , i s b ( 2 ) i s s e t to z e r <> •

the

initial

point

be
each

for

Function successfully completed.

Number of fields to be output is zero.

Insufficient dynamic storage to allocate on I/O packet.

LUN not assigned.

+99

Invalid LUN.

+303 -

Controller not ready

+321 -

Nonexistent point specified.
a field do not exist.

lun

One or more points within

Integer variable defining the logical unit number.

Example:
Pulse momentary digital output fields defined by points 20, 37
on LUN 1.
DIMENSION ICONT(3),IDAT(3)
DATA ICONT(l) ,ICONT(2) ,ICONT(3)/20,37 ,O/
CALL DOM(3,ICONT,IDAT,,l)

18-46

and

INDUSTRIAL CONTROL SUBSYSTEMS
RTO/RTOW:

18.4.10

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.
CALL RTO (ibc, idat [, isb] [, lun])
or
CALL RTOW (ibc,idat •••• etc.)
Argument Descriptions:
ibc

Integer variable specifying
output.

idat

Byte array
(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.

the

number

bytes

containing

the

character

Operation pending.

Function successfully completed.

Zero bytes to be transmitted.

Insufficient dynamic storage to allocate I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+303 -

Device not ready.
Terminal failed to respond within
second after character was transmitted.

+306 -

Part or all of buffer is
addressing space.

+321 -

Nonexistent module.

lun

out

the

issuing

task's

Device is ICSll.

Integer variable defining the logical unit number.

Example:
Output a character string to
assigned to LUN 3.

remote

terminal

via

the

ICR

unit

CALL RTOW(32,'APPLY +5 VOLTS TO A/D CHANNEL 10',,3)

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:

18-47

INDUSTRIAL CONTROL SUBSYSTEMS

Interrupting Digital Inputs
CTDI

Connect a buffer to receive digital interrupts.

RODI

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

DFDI

Disconnect a buffer from digital interrupts.

bits

interrupt

data

from

the

circular

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.

18.4.11.l 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 define an event
tlag that will be set upon the occurrence of each interrupt.

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.

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

circular

- Function successfully completed.
isb(2} receives the
number of words passed per interrupt in the low byte.

- Insufficient
packet.

dynamic

18-48

storage

allocate

I/O

INDUSTRIAL CONTROL SUBSYSTEMS
+8

- Unassigned LUN.

+99

+306

- Part of buffer is out of the user's address space
buffer is too small to accommodate a single entry.

+316

- Privilege violation - task is checkpointable and
fixed in memory.

not

+319

- Buffer address or length is an odd number of bytes.

+322

- Another task is already connected to interrupts.

+397

lun

Invalid LUN.

Invalid event flag specified

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)

where n is the number of entries to be contained in the buffer and isz
is 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:
1.

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 {e.g., fatal serial
line error or remote power-fail).

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

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 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 zero, examines the state of data bit n, and converts bit n
to a point number via the following formula:
ipt = module number

* 16 + n

18-49

INDUSTRIAL CONTROL SUBSYSTEMS

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 zero 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 zero or
an overrun count that is maintained by the ICS/ICR driver. If ict is
zero, 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

is a variable to which the digital input
is returned. It may be set as follows:
1.

point

ipt < 0 if no valid entry is found

The specific value of ipt reflects the error
detected as follows:
-1 -

-2 -

-3 2.

no data
(i.e.,
no
currently in buffer)
overrun
hardware error

1 • • FALSE.

ipt => 0 if the value indicated is a point
the state is returned to ival.

ict

.TRUE.

(0)

that

the

was
data

interrupt

is a variable to which the state of
returned; it may be set as follows:

ival

number

number;
point

if the point is open

(-1) if the point is closed

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 zero~
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
RODI 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.

18-50

INDUSTRIAL CONTROL SUBSYSTEMS
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 zero 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

E~rror

conditions is identical to subroutine RODI.

Calling Sequence:
CALL RDCS (ipt,ival[,ict])
Argument Descriptions:
ipt

Integer variable to receive
the digital
number.
It may be set as follows:
1.

ival

point

ipt < 0 if no valid entry is found (i.e.,
overrun,
error or no data in buffer). The specific value of
ipt reflects the error that was detected
as
follows:
-1 -2 -3 -

input

no data
overrun
hardware error

ipt => O if the value indicated is a point
the state is returned to ival.

number,

Integer variable to receive the state of the point as a
logical value where:

ict

.FALSE.

(0)

.TRUE.

(-1)

=point open
point closed

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 error.
Otherwise set to zero.
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.

18-51

INDUSTRIAL CONTROL SUBSYSTEMS

Calling Sequence:
CALL RDWD (imod,ival[,ict][,icos])
Argument Descriptions:
imod

an integer variable to receive
status as follows:
1.

the

module

imod < O if no data is present or
condition or error was detected
The specific value of ipt reflects
that was detected as follows:
-1 -2 -3 -

imod
ival

number
an
the

overrun
error

no data
overrun
hardware error

=> 0 Module number.

Interrupt data is in

ival

Integer variable to receive the digital interrupt data.

ict

icos

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.
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.3 DFDI:
Disconnect a Buffer from Digital Interrupts - The
following routine
is called to disconnect a task's circular buffer
from digital interrupts.
Calling Sequence:
CALL DFD I

( [ i s b] [ , 1 u n] )

Argument Descriptions:
isb

Optional 2-word integer array to receive the results of
the call as follows.
isb(2) is always zero.

Function successfully completed.

Insufficient dynamic storage to allocate I/O

Unassigned LUN.

18-52

packet~

INDUSTRIAL CONTR01L SUBSYSTEMS

+99

Invalid LUN.

+322 -

Task not connected to interrupts.

lun

Integer variable containing logical unit number.

18.4.11.4 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.
Calling Sequence:
CALL CTTI (ibuf,isz,iev,iv[,isb] l[,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.

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 zero 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
buffer is too small to accommodate a single entry.

+316 -·

Privilege violation - task is
fixed in memory.

not

+319 -·

Buffer address or length is an odd number of bytes.

+322 -

Another task is already connected to interrupts.

+397 -

Invalid event flag specified.

checkpointable

and

Integer variable specifying the logical unit number.

18-53

INDUSTRIAL CONTROL SUBSYSTEMS
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)

where n is the number of entries to be contained in the buffer.
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, i val [, ict])

Argument Descriptions:
imod

Integer variable to receive module number and status as
follows:
1.

imod < 0 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 -

no data
overrun
hardware error

imod => 0 Module number of counter.
data is in ival.

Interrupt

ival

Integer variable
interrupt.

ict

Optional integer variable to receive the overrun count,
or the ICSR contents
returned by the driver on the
occurrence of a fatal hardware error.
Otherwise,
set
to zero.

receive

the

counter

data

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

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.11.6

Miscellaneous Counter Routines

Read a Counter Module

RSTI:

The following routine directly accesses a counter register
its current value.

return

Calling Sequence:
CALL RSTI

(imod,isb[,iun])

Argument Descriptions:
imod

An
integer variable
counter to be read.

containing

the

number

the

isb

A two-word integer array to receive status and data
follows.
Status is returned to isb(l).

Function successfully completed.
isb(2).

+321

Nonexistent module specified.

Data is

returned

the

ICS/ICR

The following rqutine may be called by any task to revise the
value that is used to activate a counter.

initial

iun

Optional
integer variable
physical unit number.
SCTI:

specifying

Reset a Counter Initial Value

Calling Sequence:
CALL SCTI (imod, ival [, isb] [, lun] Ji
Argument Descriptions:
imod

Integer variable specifying the relative module
of the counter to be reset.

ival

Integer value specifying the new initial value.

isb

Optional 2-word integer array
to
follows.
isb{2) is always zero.

lun

receive

number

status

Function successfully completed.

Insufficient dynamic storage to allocate an I/O packet.

Unassigned LUN.

+99

Invalid LUN.

+303 -

Controller not ready.

+321 -

Nonexistent module specified.
Integer specifying the logical unit number.

18-55

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.11.7 DFTI: Disconnect a Buffer
following subroutine is called to
buffer from interrupts.

from Counter Interrupts - The
disconnect
the task's circular

Calling Sequence:
CALL OFT I

( [ i s b ] [ , 1u n ] )

Argument Descriptions:
isb

Optional 2-word integer array
to
follows.
isb(2) is always zero.

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.

lun

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 (Section 18.4.11.1).

those

buffer,

that

ibuf

An integer array making up the
receives interrupt data.

isz

Length of the circular buffer in words.

iev

Event flag to be set on each terminal interrupt.

circular

Buffer size is computed as
isz

= (8 + 4 * n)

where n is 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.

18-56

INDUSTRIAL CONTROL SUBSYSTEMS
+99

Invalid LUN.

+306

Part of buffer is out of the user's address space
buffer is too small to accommodate a single entry.

+316 -

Privilege violation fixed in memory.

and

not

+319 -

Buffer address not on a word boundary or length
odd number of bytes.

+321 -

Nonexistent module specified.

+322 -

Another task is already connected to interrupt.

+397 -

Invalid event flag specified.

lun

task is

checkpointable

Unit is ICSll.

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
error

buffer,

overrun,

The specific value of ind reflects the
was detected as follows:
-1 -2 -3 -

hardware

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
wi 11 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 zero.
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-57

INDUSTRIAL CONTROL SUBSYSTEMS
18.4.11.10 DFTY: Disconnect a
Circular
Input - The following routine disconnects
from terminal inputs.

Buffer
from
Terminal
a task's circular buffer

Calling Sequence:
CALL DFTY { [isb] [, lun])
Argument Descriptions:
isb

lun

Optional, 2-word integer array to receive status
isb{l) as follows.
isb{2) is always set to zero.

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 £allowing are excerpts from a
FORTRAN program that is to monitor· a remote terminal for input and
echo the received characters when a ca1rriage return is detected.

SPECIFY BYTE FORMAT FOR TERMINAL DATA
LOGICAL*! TCHR

c
C
C

c
c

c
c
c
c

c
C
C

ALLOCATE STORAGE FOR THE TERMINAL
BUFFER
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)
ALLOCATE STORAGE FOR A
2-WORD STATUS BLOCK
DIMENSION ISB ( 2)
INITIALIZE ICRll LOGICAL UNIT(7) AND
TRIGGER EVENT FLAG NUMBER(2)

c
DATA IEV, LUN/2, 7/

18-58

INDUSTRIAL CONTROL SUBSYSTEMS

c
c
c
c
C

CONNECT THE TASK TO TERMINAL
INPUTS. IF CONNECT FAILS--STOP l
CALL CTTY (IBUF,32,IEV,ISB,LUN)
IF (!SB ( l) • GE. 3) STOP l

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 = 1,80

c
c
c

20--WAIT FOR TRIGGER EVENT FLAG

CALL WAITFR (!EV)

c
c
c
c

30--PACK THE CIRCULAR BUFFER DATA
INTO THE BYTE ARRAY

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

50--REPORT OVERRUN CONDITION

CALL LOST (IVR)

GO TO 30

60--CHECK FOR CARRIAGE RETURN,
EXIT TO ECHO ROUTINE IF
PRESENT

IF (TCHR(I).EQ."15) GO TO 80

CONTINUE

80--FALL THROUGH TO ECHO A LINE

c
c
c
c

c
C

CALL RTOW (I,TCHR,,LUN)
DISCONNECT TERMINAL BUFFER, EXIT
CALL DFTY (, LUN)
CALL EXIT
END

18-59

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 !CSR register
contents
for
further
fault
analysis and warning as
appropriate.
In the event of such an error, the event flag
wi 11 not be set by the driver again unless norma 1 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 ail interrupts.

18.4.12.1 LNK:
Link a Task to Interrupts - This subroutine allows
any
installed task
to be activated on the occurrence of any
unsolicited interrupt.
Calling Sequence:
CALL LNK (tnam, iprm [, isb] [; lun])
Argument Descriptions:
tnam

Real variable containing task name in RADIX-SO format.

iprm

5-word integer array containing the following data:

iprm ( 1)

Interrupt class.

May be one of the following:

0 - Digital interrupts
1 - Counters
2 -

Remote terminal

(Control-C only)

3 -

Error interrupts.

18-60

INDUSTRIAL CONTROL SUBSYSTEMS
iprm(2)

Reserved

iprm ( 3)

Optional event flag set if task to be activated is
dormant when the interrupt occurs.

iprm(4)
iprm ( 5)

Hardware-dependent parameters as follows:

Interrupt Class

not

Parameter Contents

Digital

i prm ( 4)
i prm ( 5)

Point number
Change-of-state mask

Counter

iprm ( 4)
i prm ( 5)

Module number
Counter initial value

Remote Terminal

iprm(4)
iprm(S)

not used
not used

Error

iprm ( 4)
iprm(S)

not used
not used

isb

to
receive
isb(2)
is

Optional
2-word integer array
status
in isb(l)
as follows.
always set to zero.
+l -

Function successfully completed.

+3 - Unrecognized interrupt class specified.
+4 -

Insufficient dynamic
packet.

storage

allocate

I/O

+8 - Unassigned LUN.
+99 - Invalid LUN.
+301 - Task tnam not installed.
+303 - Controller not ready.
+317 - Resource in use.
interrupt.
+323