Digital PDFs

DEC-11-OMDRA-A-D

May 1974

250 pages

Original

10MB

Document:	RSX-11M I/O Drivers Reference Manual Version 1
Order Number:	DEC-11-OMDRA-A-D
Revision:	0
Pages:	250
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V1/RSX-11M-V1-I-O_Drivers_Reference_Manual.pdf

OCR Text

RSX-11M
I/O Drivers Reference Manual
Order No. DEC-II-OMDRA-A-D

RSX-IIM Version 1

11/74 - 14

Order additional copies as directed on the Software
Information page at the back of this document.

digital equipment corporation · maynard. massachusetts

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 manual.
The software described in this document is furnished to the purchaser
under a license for use on a single computer system and can be copied
(with inclusion of DIGITAL's copyright notice) only for use in such
system, except as may otherwise be provided in writing by DIGITAL.
Digital Equipment Corporation assumes no responsibility for the use
or reliability of its software on equipment that is not supplied by
DIGITAL.

Associated Manuals
Refer to the User's Guide to RSX-llM
Manuals, DEC-ll-OMUGA-A-D.
copyright ~ 1974 Digital Equipment Corporation

The HOW TO OBTAIN SOFTWARE INFORMATION page, located at the back of
this document, explains the various services available to DIGITAL
software users.
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:
CDP
COMPUTER LAB
COMSYST
COMTEX
DDT
DEC
DECCOMM
DECTAPE
DIBOL

DIGITAL
DNC
EDGRIN
EDUSYSTEM
FLIP CHIP
FOCAL
GLC-8
IDAC
IDACS

INDAC
KAlO
LAB-8
LAB-8/e
LAB-K
OMNIBUS
OS/8
PDP
PHA

PS/8
QUICKPOINT
RAD-8
RSTS
RSX
RTM
RT-Il
SABR
TYPESET 8
UNIBUS

CONTENTS
Page
xv

PREFACE

CHAPTER

0.1

MANUAL OBJECTIVES AND READER CLASS ASSUMPTIONS

0.2

STRUCTURE OF THE DOCUMENT

0.3

CONVENTIONS USED IN THIS MANUAL

xvii

RSX-llM INPUT/OUTPUT

1.1

OVERVIEW OF RSX-llM I/O

1-1

1.2

RSX-l1M DEVICES

1-2

1.3
1.3.1
1.3.2
1.3.3

LOGICAL UNITS
Logical Unit Number
Logical unit Table
Changing LUN Assignments

1-4
1-4
1-4
1-5

1.4
1.4.1
1.4.2
1.4.3

ISSUING AN I/O REQUEST
QIO Macro Format
Significant Events
Syst.em Traps

1-6
1-7
1-10
1-11

1.5

DIRECTIVE PARAMETER BLOCKS

1-12

1.6
1.6.1
1.6.2
1.6.3
1.6.4
1.6.5
1.6.6
1.6.7

I/O-RELATED MACROS
The QIO$ Macro: Issuing an I/O Request
The DIR$ Macro: Executing a Directive
The .MCALL Directive: Retrieving System Macros
The ALUN$ Macro: Assigning a LUN
The GLUN$ Macro: Retrieving LUN Information
The ASTX$S Macro: Terminating AST Service
The WTSE$ Macro: Waiting for an Event Flag

1-13
1-15
1-15
1-15
1-16
1-18
1-21
1-21

1.7
1.7.1
1.7.2
1.7.3
1.7.4
1.7.5
1.7.6
1.7.7

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

1-22
1-23
1-24
1-24
1-25
1-25
1-25
1-26

1.8

I/O COMPLETION

1-26

1.9
1.9.1
1.9.2

RETURN CODES
Directive Conditions
I/O Status Conditions

1-27
1-28
1-3n

iii

Page
CHAPTER

CHAPTER

TERMINAL DRIVER

2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6
2.1.7

INTRODUCTION
ASR-33/35 Teletypes
KSR-33/35 Teletypes
LA30 DECWriters
LA36 DECWriter
RT02 Alphanumeric Display Terminal and RT02-C
Badge Reader/Alphanumeric Display Terminal
VT05B Alphanumeric Display Terminal
VT50 Alphanumeric Display Terminal

2-3
2-3
2-3

2.2

GET LUN INFORMATION MACRO

2-3

2.3

QIO MACRO

2-5

2.4

STATUS RETURNS

2-6

2.5
2.5.1
2.5.2

CONTROL CHARACTERS AND SPECIAL KEYS
Control Characters
Special Keys

2-8
2-8
2-10

2.6

VERTICAL FORMAT CONTROL

2-10

2.7
2.7.1
2.7.2
2.7.3

TERMINAL INTERFACES
DHll Asynchronous Serial Line Multiplexer
DJll Asynchronous Serial Line Multiplexer
DLll Asynchronous Serial Line Interface

2-11
2-11
2-12
2-12

2.8
2.8.1
2.8.2
2.8.3

PROGRAMMING HINTS
Terminal Line Truncation
ESCape Code Conversion
RT02-C Control Function

2-12
2-12
2-12
2-12

DISK DRIVERS

3.1
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5
3.1.6

INTRODUCTION
RFll/RSll Fixed-Head Disk
RJP04 Pack Disk
RJS03 Fixed-Head Disk
RJS04 Fixed-Head Disk
RKll/RK05 Cartridge Disk
RPll-C/RP03 Pack Disk

3-2
3-2
3-2
3-2
3-2

3.2

GET LUN INFORMATION MACRO

3-3

3.3

QIO MACRO

3-3

3.4

STATUS RETURNS

3-4

DECTAPE DRIVER

4.1

INTRODUCTION

4-1

4.2

GET LUN INFORMATION MACRO

4-1

2-1
2-2
2-2
2-2
2-2

3-1
3~1

(
\

Page

CHAPTER

4.3
4.3.1
4.3.2

OIO MACRO
Standard OIO Functions
Device-Specific OIO Functions

4-2
4-2
4-4

4.4
4.4.1
4.4.2

STATUS RETURNS
DECtape Recovery Procedures
Select Recovery

4-4
4-7
4-8

4.5
4.5.1
4.5.2
4.5.3
4.5.4

PROGRAMMING HINTS
DECtape Transfers
Reverse Reading and Writing
Speed Considerations When Reversing Direction
Aborting a Task

4-8
4-8
4-8
4-8
4-9

MAGNETIC TAPE DRIVERS

5.1
5.1.1
5.1.2

INTRODUCTION
TM11 Magnetic Tape
TJU16 Magnetic Tape

5-1
5-2
5-2

5.2

GET LUN INFORMATION MACRO

5-2

5.3
5.3.1
5.3.2
5.3.2.1
5.3.2.2

OIO MACRO
Standard OIO Functions
Device-Specific QIO Functions
IO.RWU
IO.SEC

5-3
5-3
5.;.4
5-4
5-5

5.4
5.4.1
5.4.2

STATUS RETURNS
Select Recovery
Retry Procedures for Reads and'Writes

5-9
5-12
5-12

5.5
5.5.1
5.5.2
5.5.3
5.5.4

PROGRAMMING HINTS
Block Size
Importance of Resetting Tape Characteristics
Aborting a Task
Writing an Even-Parity Zero

5-12
5-12
5-13
5-13
5-13

CASSETTE DRIVER

6.1

INTRODUCTION

6-1

6.2

GET LUN INFORMATION MACRO

6-1

6.3
6.3.1
6.3.2

OIO MACRO
Standard QIO Functions
Device-Specific OIO Functions

6-2
6-3
6-3

6.4
6.4.1

STATUS RETURNS
Cassette Recovery Procedures

6-4
6-7

6.5

STRUCTURE OF CASSETTE TAPE

6-7

6.6
6.6.1

PROGRAMMING HINTS
Importance of Rewinding

6-8
6-8

Page

CHAPTER

6-9
6-9
6-9
6-9
6-9

6.6.2
6.6.3
6.6.4
6.6.5
6.6.6

End-of-File and IO.SPF
The Space Functions, IO.SPB and IO.SPF
Verification of write Operations
Block Length
Logical End-of-tape

LINE PRINTER DRIVER

7.1
7.1.1
7.1.2
7.1.3

INTRODUCTION
LPll Line Printer
LSll Line Printer
LVll Line Printer

7-1
7-2
7-2
7-2

7.2

GET LUN INFORMATION MACRO

7-2

7.3

QIO MACRO

7-3

7.4
7.4.1

STATUS RETURNS
Ready Recovery

7-4
7-5

7.5

VERTICAL FORMAT CONTROL

7-6

7.6
7.6.1
7.6.2
7.6.3

PROGRAMMING HINTS
RUBOUT Character
Print Line Truncation
Aborting a Task

CARD READER DRIVER

8.1

INTRODUCTION

8-1

8.2

GET LUN INFORMATION MACRO

8-1

8.3
8.3.1

QIO MACRO
Standard QIO Functions
Device-Specific QIO Function

8-2
8-2
8-3

8.4.2
8.4.3

STATUS RETURNS
Card Input Errors and Recovery
Ready and Card Reader Check Recovery
I/O Status Conditions

8-4
8-4
8-7

8.5
8.5.1

FUNCTIONAL CAPABILITIES
Control Characters

8-10
8-10

8.6
8.6.1
8.6.2

CARD READER DATA FORMATS
Alphanumeric Format (026 and 029)
Binary Format

8-11
8-11
8-12

8.7

PROGRAMMING HINTS
Input Card Limitation
Aborting a Task

8-13
8-13
8-13

8.3.2
8.4
8.4.1

8.7.1

8.7.2

7-6
7-7

7-7
7-7

8-8

Page
CHAPTER

CHAPTER

MESSAGE-ORIENTED COMMUNICATION DRIVERS

9.1
9.1.1
9.1.2
9.1.3

INTRODUCTION
DL11-E Asynchronous Line Interface
DP11 Synchronous Line Interface
DUll Synchronous Line Interface

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

9.2

GET LUN INFORMATION MACRO

9-3

9.3
9.3.1
9.3.2
9.3.2.1
9.3.2.2
9.3.2.3
9.3.2.4
9.3.2.5

QIO MACRO
Standard QIO Functions
Device-Specific QIO Functions
IO.HDX
IO.INL and IO.TRM
IO.RNS
IO.SYN
IO.WNS

9-4
9-4
9-5
9-5
9-6
9-6
9-6
9-6

9.4

STATUS RETURNS

9-7

9.5
9.5.1
9.5.2
9.5.3
9.5.4
9.5.5
9.5.6

PROGRAMMING HINTS
Transmission Validation
Redundancy Checking
Half-Duplex Considerations
Low-Traffic Sync Character Considerations
vertical Parity Support
Importance of IO.INL

9-8
9-8
9-9
9-9
9-9
9-9
9-10

9.6

PROGRAMMING EXAMPLE

9-10

ANALOG-TD-DIGITAL CONVERTER DRIVERS

10.1
10.1.1
10.1.2

INTRODUCTION
AFC11 Ana1og-to-Digita1 Converter
AD01-D Ana1og-to-Digita1 Converter

10-1
10-1
10-2

10.2

GET LUN INFORMATION MACRO

10-2

10.3
10.3.1
10.3.2

QIO MACRO
Standard QIO Function
Device-Specific QIO Function

10-2
10-2
10-2

10.4
10.4.1
10.4.2
10.4.3
10.4.4

10.4.6
10.4.7

FORTRAN INTERFACE
10-4
Synchronous and Asynchronous Process Control I/O 10-4
The ish Status Array
10-4
FORTRAN Subroutine Summary
10-5
AIRD/AIRDW: Performing Input of Analog Data
in Random Sequence
10-6
AISQ/AISQW: Reading Sequential Analog Input
Channels
10-6
ASADLN: Assigning a LUN to ADO:
10-7
ASAFLN: As~igning a LUN to AFO:
10-7

10.5
10.5.1

STATUS RETURNS
FORTRAN Interface Values

10.4.5

vii

10-8
10-10

Page

CHAPTER

10.6
10.6.1

FUNCTIONAL CAPABILITIES
Control and Data Buffers

10-10
10-10

10.7
10.7.1
10.7.2
10.7.3
10.7.4

PROGRAMMING HINTS
Use of A/D Gain Ranges
Identical Channel Numbers on the AFC11
AFC11 Sampling Rate
Restricting the Number of AD01-D Conversions

10-11
10-11
10-11
10-11
10-11

UNIVERSAL DIGITAL CONTROLLER DRIVER

11.1
11.1.1
11.1.2
11.1.2.1
11.1.2.2

INTRODUCTION
Creating the UDC11 Driver
Accessing UDC11 Modules
Driver Services
Direct Access

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

11.2

GET LUN INFORMATION MACRO

11-3

·11.3
11.3.1
11.3.2
11.3.2.1

QIO MACRO
Standard QIO Function
Device-Specific QIO Functions
Contact Interrupt Digital Input
(W733 Modules)
11.3.2.2 Timer (W734 I/O Counter Modules)
11.3.2.3 Latching Digital Output (M685, M803,
and M805 Modules)
11.3.2.4 Ana1og-to-Digita1 Converter (ADU01 Module)

11-3
11-3
11-4

DIRECT ACCESS
Defining the UDC11 Configuration
Assembly Procedure for UDCOM.MAC
Symbols Defined by UDCOM.MAC
Including UDC11 Symbolic Definitions in
the System Object Module Library
11.4.3
Referencing the UDC11 through a Common Block
11.4.3.1 Creating a Global Common Block
11.4.3.2 Making the Common Block Resident
11.4.3.3 Linking a Task to the UDC11 Common Block

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

11.4
11.4.1
11.4.1.1
11.4.1.2
11.4.2

11.5
11.5.1
11.5.2
11.5.3
11.5.4
11.5.5
11.5.6
11.5.7
11.5.8
11.5.9
11.5.10
11.5.11
11.5.12

11-5
11-7
11-8
11-8

11-12
11-12
11-12
11-14
11-14

11-14
FORTRAN INTERFACE
Synchronous and Asynchronous Process Control I/O 11-15
11-15
The isb Status Array
11-16
FORTRAN Subroutine Summary
AIRD/AIRDW: Performing Input of Analog
11-18
Data in Random Sequence
AISQ/AISQW: Reading Sequential Analog
11-19
Input Channels
11-19
AO/AOW: Performing Analog Output
11-20
ASUDLN: Assigning a LUN to UDO:
11-20
CTDI: Connecting to Contact Interrupts
11-21
CTTI: Connecting to Timer Interrupts
11-22
DFDI: Disconnecting from Contact Interrupts
11-23
DFTI: Disconnecting from Timer Interrupts
DI/DIW: Reading Several Contact Sense
11-23
Fields

viii

(

Page

11.5.18
11.5.19

DOL/DOLW: Latching or Unlatching Several
Fields
DOM/DOMW: pulsing Several Fields
RCIPT: Reading a contact Interrupt Point
RDDI: Reading Contact Interrupt Data
From a Circular Buffer
RDTI: Reading Timer Interrupt Data From
a Circular Buffer
RSTI: Reading a Timer Module
SCTI: Initializing a Timer Module

11-27
11-27
11-28

11.6
11.6.1

STATUS RETURNS
FORTRAN Interface Values

11-28
11-31

11.7
11.7.1
11.7.2
11.7.3

PROGRAMMING HINTS
Checkpointab1e Tasks
Numbering Conventions
Use of CTDI and RDDI for Processing
Circular Buffer Entries

11-31
11-31
11-31

11.5.13
11.5.14
11.5.15
11.5.16
11.5.17

CHAPTER

11-24
11-24
11-25
11-26

11-32

LABORATORY PERIPHERAL SYSTEM DRIVER

12.1

INTRODUCTION

12-1

12.2

GET LUN INFORMATION MACRO

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.3
12.3.3.1
12.3.3.2
12.3.3.3
12.3.3.4
12.3.3.5
12.3.4
12.3.4.1

QIO MACRO
Standard QIO Function
Device-Specific QIO Functions (Immediate)
IO.LED
IO.REL
IO.SDI
IO.SDO
Device-Specific QIO Functions (Synchronous)
IO.ADS
IO.HIS
IO.MDA
IO.1IDI
IO.MOO
Device-Specific QIO Function (IO.STP)
IO.STP

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

12.4
12.4.1
12.4.2
12.4.3
12.4.4
12.4.5
12.4.6
12.4.7

FORTRAN INTERFACE
The ish Status Array
Synchronous Subroutines
FORTRAN Subroutine Summary
ADC: Reading a Single A/D Channel
ADJLPS: Adjusting Buffer Pointers
ASLSLN: Assigning a LUN to LSO:
CVSWG: Converting a Switch Gain A/D Value to
Floating-Point
DRS: Initiating Synchronous Digital Input
Sampling
HIST: Initiating Histogram Sampling
IDIR: Reading Digital Input

12-9
12-9
12-30
12-31
12-]2
12-] 3
12-14

12.4.8
12.4.9
12.4.10

12-14
12-15
12-17
12-1~

Page

12.4.1S
12.4.16
12.4.17
12.4.18
12.4.19

12-19
IDOR: Writing Digital Output
12-20
IRDB: Reading Data from an Input Buffer
12-20
LED: Displaying in LED Lights
LPSTP: Stopping an In-Progress Synchronous
12-21
Function
PUTD: Putting a Data Item into an output Buffer 12-21
12-22
RELAY: Latching an Output Relay
RTS: Initiating Synchronous A/D Sampling
12-22
SDAC: Initiating Synchronous D/A Output
12-24
SDO: Initiating Synchronous Digital Output
12-26

12.S
12.S.1
12.S.2
12.S.3
12.S.4

STATUS RETURNS
IE.RSU:
Second I/O Status Word
IO.ADS and ADC Errors
FORTRAN Interface Values

12-27
12-30
12-31
12-32
12-32

12.6
12.6.1
12.6.2
12.6.3
12.6.4

PROGRAMMING HINTS
The LPS11 Clock and Sampling Rates
Importance of the I/O Status Block
Buffer Management
Use of ADJLPS for Input and Output

12-32
12-33
12-33
12-34
12-35

SUMMARY OF IO FUNCTIONS

A-1

A.1

ANALOG-TO-DIGITAL CONVERTER DRIVERS

A-2

A.2

CARD READER DRIVER

A-2

A.3

CASSETTE DRIVER

A-2

A.4

COMMUNICATION DRIVERS (MESSAGE-ORIENTED)

A-2

A.S

DECTAPE DRIVER

A-3

A.6

DISK DRIVERS

A-3

A.7

LABORATORY PERIPHERAL SYSTEM DRIVER

A-3

A.8

LINE PRINTER DRIVER

A-4

MAGNETIC TAPE DRIVERS

A-4

A.10

TERMINAL DRIVER

A-S

A.11

UNIVERSAL DIGITAL CONTROLLER DRIVER

A-5

I/O FUNCTION AND STATUS CODES

B-1

B.1
B.1.1
B.1.2

I/O STATUS CODES
I/O Status Error Codes
I/O Status Success Codes

B-1
B-1
B-3

B.2
B.2.1
B.2.2

DIRECTIVE CODES
Directive Error Codes
Directive Success Codes

B-3
B-3
B-3

12.4.11
12.4.12
12.4.13
12.4.14

APPENDIX

(

Page
B.3
B.3.1
B.3.2
B.3.3
B.3.4
B.3.S
B.3.6
B.3.7
B.3.8
B.3.9

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 LPS I/O Function Codes
Specific Magtape I/O Function Codes
Specific UDC I/O Function Codes

B-S
B-S
B-S
B-6
B-6

APPENDIX

RSX-llM PROGRM1MING EXAMPLE

C-l

APPENDIX

GLOSSARY OF RSX-llM TERMS

D-l

B-3
B-4
B-4
B-4
B-4

FIGURES
Page

Number
1-1

Logical Unit Table

1-5

1-2

QIO Directive Parameter Block

1-13

5-1

Determination of Tape Characteristics for the
TMll

5-7

5-2

Determination of Tape Characteristics for the
TJU16

5-8

6-1

Structure of Cassette Tape

6-7

TABLES
Page

Number
1-1

Directive Returns

1-29

1-2

I/O Status Returns

1-31

2-1

Standard Terminal Devices

2-1

2-2

Standard Conununication Line Interfaces

2-2

2-3

Standard QIO Functions For Terminals

2-5

2-4

Terminal Status Returns

2-6

2-5

Terminal Control Characters

2-9

2-6

Special Terminal Keys

2-10

2-7

Vertical Format Control Characters

2-11

3-1

Standard Disk Devices

3-1

3-2

Standard QIO Functions for Disks

3-4

3-3

Disk Status Returns

3-5

4-1

Standard QIO Functions for DECtape

4-3

4-2

Device-Specific Functions for DECtape

4-4

4-3

DECtape Status Returns

4-5

xii

(
\

TABLES
'Page

Number
5-1

Standard Magtape Devices

5-1

5-2

Standard QIO Functions for Magtape

5-3

Device-Specific QIO Functions for Magtape

5-4

Magtape Status Returns

5-9

6-1

Standard QIO Functions for Cassette

6-3

6-2

Device-Specific QIO Functions for Cassette

6·-4

6-3

Cassette Status Returns

6 -4

7-1

Standard Line Printer Devices

7-1

7-2

Standard QIO Functions for Line Printers

7-3

Line Printer Status Returns

7-4

Vertical Format Control Characters

7-6

8-1

Standard QIO Functi6nsforthe Card Reader

8-3

8-2

Device-Speci.fic QIO Function for the Card Reader 8·-3

8-3

Card Reader Switches and Indicators

8·-5

8-4

Card Reader Status Returns

8·-9

8-5

Card Reader Control Characters

8,-11

8-6

Translation from DEC026 or DEC029 to ASCII

8·-12

9-1

Message-Oriented Communication Interfaces

9--2

9-2

Standard QIO Functions for Conununication
Interfaces

9-4

Device-Specific QIO Functions for Communication
Interfaces

9-5

9-4

Communication Status Returns

9·-7

10-1

Standard Ana1og-to-Digita1 Converters

10-1

10-2

Standard QIO Function for t:le AID Converters

1<)-2

10-3

Device-Specific QIO Function for the A/))
Converters

10-3

10-4

AID Conversion Control Nord

111-3

10-5

Contents of First Word of ish

l!)-r

9-3

(

TABLES
Number
10-6

Page
FORTRAN Interface Subroutines for the AFC11
and AD01-D

10-5

10-7

AID Converter Status Returns

10-8

FORTRAN Interface Values

10-10

11-1

Standard QIO Function for the UDC11

11-3

11-2

Device-Specific QIO Functions for the UDC11

11-4

11-3

A/D Conversion Control Word

11-5

11-4

Contents of First Word of ish

11-16

11-5

FORTRAN Interface Subroutines for the UDC11

11-17

11-6

UDC11 Status Returns

11-29

11-7

FORTRAN Interface Values

11-31

12-1

Standard QIO Function for the LPS11

12-2

Device-Specific QIO Functions for the LPS1!
(Immediate)

12-3

Device-Specific QlO Functions for the LPS11
(Synchronous)

12-4

Device-Specific QIO Function for the LPS1l
(IO.STP)

12-fl

12-5

Contents of First Word of ish

12-9

12-6

FORTRAN Interface Subroutines for the LPS11

12-11

12-7

LPS11 Status Returns

12-29

12-8

Returns to Second Word of I/O Status Block

12-31

12-9

FORTRAN Interface Values

12-32

12-3

(

PREFACE

0.1

MANUAL OBJECTIVES AND READER CLASS ASSUMPTIONS

This manual is designed to provide all information necessary to
interface directly with the I/O device drivers supplied as part of the
RSX-llM system.
It is intended for use by experienced RSX-llM
programmers who want to take advantage of the time and/or space
savings which result from direct use of the I/O drivers.
The orientation of this manual is tutorial, but it does not attempt to
introduce the reader to all areas of RSX-llM input/output operations.
Readers are expected to be familiar with the RSX-llM Executive
Reference Manual (DEC-II-OMERA-A-D) and to have some experience with
the Task Builder and either FORTRAN IV or MACRO-ll assembly language.
Readers should also be familiar with the PDP-ll terminology presented
in the PDP-ll Processor Handbook and the PDP-ll Peripherals Handbook.
Users of RSX-1IM who do not require s~ch detailed knowledge of the I/O
drivers can use the device independent services provided by File
Control Services (FCS) as documented in the RSX-ll I/O Operations
Reference Manual (DEC-II-OMFSA-A-D).
'

0.2

STRUCTURE OF THE DOCUMENT

This manual has three basic components:

(

Chapter 1 provides an overview of RSX-llM input/output
operations.
It introduces the reader to the use of logical
unit numbers, directive parameter blocks, and macro calls.
It describes all of the 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 12 describe the use of all device
supported by RSX-IIM. These include the following:
Chapter

drivers

Device

Terminals and terminal
communications line interfaces

Disks

DECtape

l.fagnetic tape

Cassette

Line printer

Card reader

Message-oriented communications
line interfaces

Analog-to-digital converters

universal digital controller

Laboratory peripheral system

Each of these chapters is structured in similar fashion and focuses on
the following basic .eletnents:
.·Description of the device, including physical information
speed, capacity, access, and usage

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

and

the

devices

(

• Discussion of special characters, carriage control codes, and
functional characteristics, if relevant
• Summary of error and status conditions returned on acceptance
or rejection of I/O requests
• Description of programming hints
under RSX-lIH

for

users

the

device

(

0.3

Appendixes A through D provide quick reference material on
I/O functions and status codes, a glossary of RSX-IIM terms,
and an example of RSX-IIM I/O operations. These include the
following:
Appendix

Contents

Summary of I/O
by device

I/O function
codes

Programming example

Glossary of RSX-IIM terms

functions
and

status

CONVENTIONS USED IN THIS MANUAL

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

Brackets
([])
parameters.

syntactic

models

enclose

optional

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

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

[err]
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.4. This is
illustrated below:
IO.RLV, ••• ,(stadd,size)
null

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

DOM }
(inm,icont,idata, [idx] , [isb] , [lun])
{ DOMW

QIO$C

one

IO.ATT,6""ASTOI

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

IO.KIL,9.

optional

arguments

may

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

QIO$C
7.

IO.WLB,B.,EV"IOSB,ASTX,<IOBUF,NBUF)

With the exception of MACRO-ll 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
DECtape. The number exceeds 577 (1101 octal).

for

In MACRO-ll 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
B.

IO.RDB,14.",IOSB,,<IOBUF,BO.)

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

(

xviii

CHAPTER 1
RSX-llM INPUT/OUTPUT

1.1

OVERVIEW OF RSX-llM I/O

The RSX-llM real-time Executive supports a wide variety of PDP-II
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
RSX-llM system software. This manual describes all of the device
drivers supported by RSX-llM and the characteristics, functions, error
conditions, and programming hints associated with each.
PDP-II
devices not described in this manual can be added to basic RSX-llM
configurations, but users must develop and maintain their own drivers
for these devices.
Input/output operations under RSX-IlM 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 tile
tasks which issued them. I/O requests can be issued from MACRO-II or
FORTRAN tasks by means of the File Control Services (for appropriate
devices), or can be interfaced directly to an I/O driver by means of
the 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 task's exclusive use of a physical
device unit
• reading or writing a logical or virtual block of data
• canceling a task's I/O requests
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

CHAPTER 1.

1.2

RSX-llM INPUT/OUTPUT

RSX-11M DEVICES

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

A variety of terminals; including the following:
• ASR-33 and ASR-35 Teletypes (1)
• KSR-33 and KSR-35 Teletypes (1)
• LA30 DECwriters (serial and parallel)
• LA36 DECwriter
• VTOSB Alphanumeric Display Terminal
• VTSO 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 Communications Line Interface Multiplexer
• DHll and DHll-DMll-BB
Interface Multiplexer

Asynchronous

• DLll-A,
DLll-B,
DLll-C,
and
Communications Line Interfaces
2.

Communications
DLI1-D

(,!
\

Line

Asynchronous

A variety of disks, including the following:
• RFll/RSll Fixed-Head Disk

(1) Teletype is a re~istered trademark of the Teletype Corporation.

1-2

(

CHAPTER 1.

RSX-IlM INPUT/OUTPUT

• RJP04 Pack Disk
• RJS03 Fixed-Head Disk
• RJS04 Fixed-Head Disk
• RKll/RK05 Cartridge Disk
• RPII-C/RP03 Pack Disk
3.

TCI1-G DECtape

Two types of magnetic tape:
• TJU16 Magnetic Tape
• TM11/TU10 Magnetic Tape

TAll Tape Cassette

Three line printers:
• LP11 Line Printer
• LSll Line Printer
• LV11 Line Printer

CRll Card Reader

Synchronous and asynchronous line interfaces:
• DL11-E Asynchronous Communication Line Interface
• DP11 Synchronous Communication Line Interface
• DUll Synchronous Communication Line Interface

Two ana1og-to-digita1 converters:
• AFC11 Ana1og-to-Digital Converter
• ADOl-D Analog-to-Digit.a1 Converter

10.· UDCll Universal Digital Controller
11.

LPS11 Lru)oratory Peripheral System

1-3

CHAPTER 1.

1.3

RSX-llM INPUT/OUTPUT

LOGICAL UNITS

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

1.3.1

and

Logical Unit Number

A logical unit number or LUN is a number which is associated with a
physical device unit during RSX-llM 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 any
time.
The flexibility of this association contributes heavily to
RSX-llM 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 wh~never 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 I/UN
is associated with another physical device unit.

1.3.2

Logical unit Table

There is one logical unit table (LUT) for each task running in an
RSX-llM 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.
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, RSX-llM matches the appropriate physical ~evice 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, &SX-llM accesses the sixth 2-word entry in the LUT and associates
the I/O request with the physical device unit to '¥Thich 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-~

(

CHAPTER 1.

RSX-llM INPUT/OUTPUT
Number of LUNs

LUN 1
LUN 2
LUN 3

.... _------------------------ -- ------

- - - - - - - -- - - - - - - - ----------0

---------- - - - - - -----0

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

LUN 4

(

UCB

)

(

UCB

)

(

UCB

)

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 HCR command, REDIRECT.
Word 2 of
each entry is reserved for mountable devices.

1.3.3

Changing LUN Assignments

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

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
.HCR;
this corrnnand reassigns a LUN to another physical
device unit and thus changes the LUN-physical device unit
correspondence.
Note that this reassignment has no effect
on the in-core image of a task.

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

1-5

CHAPTER 1.
1.4

RSX-llM INPUT/OUTPUT

(

ISSUING AN I/O REQUEST

User tasks perform I/O in the RSX-llM system by submitting requests
for I/O service in the form of QIO system directives. See Chapte~ 2
of the RSX-llM Executive Reference Manual for a complete description
of RSX-llM system directives.
In RSX-llM, 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
effecti vely multiplex the use of physical device units ove"r many
users. The RSX-llM 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-llr-1 system.
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.4.1 and 1.4.2) in the QIO
request and should issue a WAITFOR system directive which specifies
the same event flag at the point where synchronization must ()ccur.
The task then waits for completion of I/O by waiting for the specified
event flag to be set.
Each QIO directive must supply sufficient information to identify and
queue the I/O request. The user may also want to include parameters
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
o

7'Jogical unit m.un!.>er associated with the physical device
to be accessed

• Optional event flag number for synchronizing
processing

I/O

unit

completion

• Optional address of the I/O status block to which information
indicatin~ successful or unsuccessful completion is returned
• Optional address of an asynchronous system "trap service
routine to be entered on completion of the I/O request
• Optional device- and function-dependent parameters specifying
such items as the starting address of a data buffer, the size
of the buffer", and a block number
A set of system macros which fac.ilitate the issuing of QIO directives
is supplied with the RSX-ll~ll system. These macros, which reside in
the System Hacro Library (SY: [1,1] RSXIlAC.SHL), must be made availahle
to the invoking task by means of the MACRO-II Assernbler directive
.J'vlCALL. The function of .BeALL is described in section 1.6.3.

CHAPTER 1.

RSX-IIM INPUT/OUTPUT

Several of the first six parameters in the QIO directive are optional,
but space for these parameters must be reserved.
During expansion of a QIO macro, a value of 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 hold places 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.5 describes the
three legal forms of the macro.
For conyenience, 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.4.1

QIO Macro Format

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

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

where brackets ([]) enclose optional or function-dependent parameters.
If function-dependent parameters
(pl, ••• ,p6) are required, these
parameters must be enclosed within angle brackets
~he following
paragraphs sluumarize the use of each QIO parameter. Section 1.5
discusses differAnt forms of the QIO$ macro itself.

«».

The fnc parameter is a symbolic name representing 'I;he I/O function
be performed. This name is of the form:

IO.xxx
wllere xxx identifies the particular I/O operation. For example, a QIO
request to attach the physiGal device unit associated with a LUN
specifies the function code:
IO.ATT

1-7

CHAPTER 1.

RSX-IIM INPUT/OUTPUT

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

IO.KIL, •••

The fnc parameter specified in the QIO request is stored internally as
a 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 throl1gh 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. 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 p.xample, the DECtape read logical
forward and read logical reverse functions have the same function
code. Only the modifier bits for these two operations are stored
differently.
The lun parameter represents the logical unit number (LUN) of the
associated physical device unit to be accessed by the I/O request.
The association between the physical device unit and the LUN 1S
specific to the task which issues the I/O request, and the LUN
reference is usually device-independent. An attach request to the
physical device uni t
associated ''lith LUN 14 begins in the following
WRy:
QIO$C

IO.ATT,14., •••

Because each task has its own logical unit table (LUT)
in which the
physical devic(-~ uni t-LUN correspondences are established, the legality
of a 1un parameter is specific to the task w'hich includes this
parameter in a QIO request.
In general, the lun must be in the
fo1lowi.ng range:

o ~ lun ~ length o.f task's LUT (if nonzero)
The number of LUNs specified in the logical unit table of a particular
task cannot exceed 255.
The efn parcuneter is a number representing the t-~vent flag to be
associated ~rith the I/O operr.ttion. It may optionally be included in a
QIO request. The event flag is cleared when the I/O request is queued
and is set when the I/O operation has cornpleted. This allows the task
to use the WAITFOR system directive to synchronize I/O programming by
suspending execution to wait for an I/O operation to complete and efn
to be set; however, if the task continues to execute, it may test the
event flag whenever it chooses by using the READ ALL EVENT FLAGS
system directive. If the user specifies an event flag number, this
number must be in the range 1 through 64.
If an event flag
specification is not desired, efn can be omitted or can be supplied
with a value of zero. Event flags 1 through 32 are local (specific to

1-8

CHAPTER 1.

RSX-llM INPUT/OUTPUT

the issuing task); event flags 33 through 64 are global (shared by
all tasks in the system). Flags 25 through 32 and 57 through 64 are
reserved for use by system software. within these bounds, the user
can specify event flags as desired to synchronize I/O completion and
task execution. Section 1.4.2 provides a more detailed explanation of
event flags and significant events.
The optional pri parameter is supplied only to make RSX-llM QIO
requests compatible with RSX-llD.
A specific priority cannot be
associated solely with the I/O request specified in the QIO macro
call.
An
RSX-llM I/O request automatically assumes the priority of
the requesting task. For consistency with RSX-llD, it is recomMended
that pri be valid, but the user should be aware that RSX-IlM does not
use this specification in any way.
RSX-llD priorities must be in
range 1 through 250, and zero can be supplied to indicate the priority
of the requesting task. A value of zero or a null specification is
recommended for all RSX-1IM use.
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, lOST, to determine if a bad parameter has been detected.
QIO$C
WTSE$C

Cl'-lPB

BEQ

(

IO.ATT,14.,2"IOST, •••
2

#IE.BAD,IOST
ERROR

The correspondence between global symbolic names and I,IO completion
codes is defined in the system object module library. Local sym})olic
definitions, which are summarized in Appendix B, may also be obtained
via the IOERR$ macro which resides in the System Hacro JJibrary.
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 ~lRo
significant.
For example, in the case of a read func!Lion on c3
terminal, the number of bytes typed before a carriage return is
returned ~n the Recond word of isb. If a l\1agtape unit i~ th~ dp.vlce
and a write function is specified, this number represents tIle number
of bytes actually trCl.ns farred.
The status block can be oNi i;ten from a
QIO request if the user does not int.end to tes't fOT stlcc:essful
completion of the request.

1-J

CHAPTER 1.

RSX-llM INPUT/OUTPUT

The optional ast parameter specifies the address of a service routine
to be entered when an asynchronous system trap occurs. section 1.4.3
discusses the use of asynchronous system traps, and section 2.2.5 of
the RSX-llM 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. tVhen 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. 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.4.2

Significant Events

"Significant event" is a term used in real-time systems to indicate a
change in system status. In RSX-llM, a significant event is declared
when an I/O operation completes.
This signals the system th.t a
change in status has occurred and indicates that the Executive f;hould
review the eligibility of all tasks in the system to determine which
task should run next. The use of significant events helps cooperating
tasks in a real-time system to communicate with each other and thus
a1lO'..,s these tasks to control their own sequence of execution
dynamically.
Signi.ficani: 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 ha::; occurred. Of the 64 event flags available in R..SX-l1M, the
flags numbere(l 1 through 32 are local to an individual task and are
s\~t
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 RSX-llM system software
use.
An example of the use of significant events follows. A task issues a
QIO di.rective "lith an efn parameter specified. A WAITFOR directive
follows the QIO and specifies as an argument the same event flag
nlillher.
The event flag is cleared when the I/O request is queued by
the Executiv~, and the task is suspended when it executes the WAITFOR
dir.ective until the event flag is set and a sigriificant event is
declared at tha completion of the I/O request. The task resumes when
thp. avprorr:i.rtte event flag is set, and execution resumes at the
insi:-. r.uction following tlH~ WAITFOR directive. During the time that the
ta£':l<.. is SilBiH~nde,'i, task::; with priori ties lo,..;er than that of the
8uspp.nded t..a81c have a chanGf> to run, thus increasing throughput in the
sYfi7.e i .1.

1-1')

(

CHAPTER 1.

1.4.3

RSX-IIM INPUT/OUTPUT

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 RSX-IlM 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 autom~tically 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.
Asynchronous traps signal the
completion of an external event such as an I/O operation.
An
asynchronous system trap (&qT) 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 are the end result of I/O-related activity, they
cannot be controlled directly by the task which receives them.
However, the task may, under certain circumstances, block honoring an
AST to prevent simultaneou; access to a critical data region. When
access to the critical data region has been completed, the queued ASTs
may again be honored. The DSAR$S (DISABLE AST RECOGNITION) and ENAR$S
(ENABLE AST RECOGNITION) system directives provide the mechanism for
accomplishing this.
An example of an asynchronous trap condition is
the completion of an I/O request. The timing of such an operation
clearly cannot be predicted by the requesting task. If an AST service
routine is not specified in an I/O request, a trap does not occur and
normal task execution continues.
Asynchronous system traps associated with I/O requests enable the
requesting task to be truly event-driven. The ~ST service routine
contained in the initiating task is executed as soon as possible,
consistent with the system's priority structure. The use of the AST
routine to service I/O related events provides a response time which
is consider.ably better than a polling mechanism, ann rrovides for
better overlap processing than the simple QIO and WAITFOR sequencA.~
l\~~"'nchronous
system traps also provide an ideal mechanism for use in
multiple buffering of I/O operations.
All AST's are inserted in a first-in-first-out queue on a per task
basi.!::; 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 AST' s disabled and is not already in the process of exer!uting an
AST service routine. The process of effecting an AST involves storing
certain information on the task's stack, including the task's four
WAITFOR mask words, the Directive Status Word (DSW) I 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 b~e
AST service routine to save and restore the registers it uses. After

I.-Il

CHAPTER 1.

RSX-llM INPUT/OUTPUT

(

\
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.6.6 of this manual
is used to issue the AST SERVICE EXIT directive. On AST service exit,
control is returned to another queued AST, the executing task, or
another task which has been waiting to run. Section 2.2.5 of the
RSX-llM Executive Reference Manual describes in detail the purpose of
AST service routines and all system directives used to handle them.

1.5

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)
The second byte contains the size of the
- always 1 for QIO.
directive parameter block in words - always 12 for QIO.
During
assembly of a user task containing QIO requests, the MACRO-ll
Assembler generates a directive parameter block 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 RSX-llM 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/O request with
the highest priority capable of being executed.
This request is
de-queued (removed from the queue) and the I/O operation is performed.
The process ~s then repeated until the queue is emptied of all
requests.
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.

~-12

CHAPTER 1.

Word

RSX-llM INPUT/OUTPUT

size of DPB +

Byte

DIC for QIO
directive

I/O function

lun

logical unit number

efn

event flag number

fnc

modifiers

~r' ,

~reserved
///////h

priority

pri

isb

address of I/O
status block

ast

address of
asynchronous trap
service routine

devicedependent
parameters

•

11
Figure 1-2
QIO Directive Parameter Block

1.6

I/O-RELATED MACROS

There are several system macros supplied with the RSX-llM system which
are used 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 MACRO-II assembler directive • MCALL.

(

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 ALUN$, GLUN$,
and other system directive macros described below.
1.

QIO$ generates a directive parameter block for the I/O
request
at
assembly
time, but does not provide the
instructions necessary to execute the request. This form of
the request is actually executed using the DIR$ macro.

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.

1--1.1

CHAPTER 1.

RSX-llM INPUT/OUTPUT
/

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",AST01, •••

QIO$C

IO.RLB,6,2",AST01, •••

QIO$S

#IO.RLB,#6,#2",#AST01, •••

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

described

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

and

supply

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 lmit 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 suspend execution of the
issuing task until a specified event flag is set.

with

(

CHAPTER 1.
1.6.1

RSX-llM INPUT/OUTPUT

The QIO$ Macro:

Issuing an I/O Request

As described in section 1.6, 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.6.2) to
execute an I/O request. In the following example, the DIR$ macro
actually generates the code to execute the QIO$ directive. It
provides no QIO parameters of its own, but references the QIO
directive parameter block at address QIOREF by supplying this label as
an argument.
QIOREF:

QIO$

READl:

DIR$

READ2 :

DIR$

1.6.2

•

IO.RLB,6,2",AST01, •••

CREATE QIO DPB

iQIOREF

ISSUE I/O REQUEST

;

iQIOREF

The DIR$ Macro:

ISSUE I/O REQUEST

Executing a Directive

The DIR$ (execute directive) macro has been implemented to allow a
task to reference a previously defined directive parameter block
without requiring that it specify all of the parameters of that macro
again. It is issued in the form:
DIR$
where:

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

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.

(
\

1.6.3

The .MCALL Directive:

Retrieving System Macros

.MCALL is a MACRO-II assembler directive which is used to retrieve
macros from the System Macro Library (SY:[l,l]RSXMAC.SML) for use
during assembly. It must be included in every user task which invokes
system macros.
.MCALL is usually placed at the beginning of a user
task and specifies, as arguments in the call, all system macros which
must be made available from the library.

I-I!)

CHAPTER 1.

RSX-llM INPUT/OUTPUT

The following example illustrates the use of this directive:
.MCALL

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

MAKE MACROS AVAILABLE

QIOREF: QIO$

IO.RLB,6,2",ASTOl, • • • i CREATE ONLY QIO DPB

READl:

DIR$

#QIOREF

READ2:

QIO$S

ISSUE I/O REQUEST

#IO.ATT,#14.,#8.",#AST02 .i CREATE DPB ON STACK
; AND ISSUE REQUEST

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

The ALUN$ rtlacro:

Assigning a LON

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

lun

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

associated

dev

is the device name of the physical device.

unt

is the unit number of that physical device.

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

10.,TT,2

~-- ] .. ~

the

with

the

following

CHAPTER 1.

RSX-llM INPUT/OUTPUT

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.
The following list contains device names, listed alphabetically, that
may be included as dev parameters for all standard devices supported
by RSX-lIM.
Device

(

ADOI-D Analog-to-Digital Converter

AFCII Analog-to-Digital Converter

CRII Card Reader

TAll Tape Cassette

RJP04 Pack Disk

RFII/RSII Fixed-Head Disk

RKII/RKOS Cartridge Disk

RPII-C/RP03 Pack Disk

RJS03 and RJS04 Fixed-Head Disks

TCII-G DECtape

LPII, LSII, and LVII Line Printers

LPSII Laboratory Peripheral System

TJUI6 Magnetic Tape

TMII/TUIO Magnetic Tape

Terminals

UDCII Universal Digital Controller

DLII-E Asynchronous Communication Line Interface

DPII Synchronous Communication Line Interface

DUll Synchronous Communication Line Interface

A pseudo-device is a logical device 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 by RSX-IIM:

1-17

CHAPTER 1.

RSX-llM INPUT/OUTPUT

Code

Device

Console listing, normally the line printer

Console output, normally the main operator's console

Pseudo-input terminal, normally the terminal from which
a task was requested

System default device, normally the disk from which the
system was bootstrapped

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).
The example included below illustrates the use of the three
the ALUN$ macro.

forms

; DATA DEFINITIONS
ASSIGN: ALUN$

lO.,TT,2

GENERATE DPB

(
EXECUTABLE SECTION
DIR$

•

ALUN$C

#ASSIGN

., EXECUTE DIRECTIVE

lO.,TT,2

; GENERATE DPB IN SEPARATE PROGRAM

SECTION, THEN GENERATE CODE TO

ALUN$S

1.6.5

; EXECUTE THE DIRECTIVE

#lO.,I"TT,12

The GLUN$ Macro:

GENERATE DPB ON STACK, THEN

,. EXECUTE DIRECTIVE

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 is~uing task. All three forms of the macro call may
be used. It is issued from a MACRo-ll program in the following way:

I-IP

(

CHAPTER 1.

RSX-1IM INPUT/OUTPUT
lun,buf

GLUN$
where:

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

The 6-word buffer contains the following indicators on
the directive:

(

1-19

completion

CHAPTER 1.
Word

RSX-l1M INPUT/OUTPUT
Byte

Bit

o
1

contents
Name of device associated with 1un

unit number of associated device

Driver flag value, indicating that the driver
is resident (always returned as 128 (200
octal) in RSX-llM)

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

Carriage-control device (e.g.,
terminal) (1 = yes)

Terminal device (1 = yes)

Directory
(1 = yes)

Single directory device (1 = yes)

Sequential device (1 = yes)

6-12

device

(e.g.,

card

(e.g.,
line

printer,

disk)

DECtape,

Reserved

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

Device mountable as a FILES-II
disk) (1 = yes)

device

Device mountable (logical OR of
14) (1 = yes)

bits

(e.g.,
13

and

Undefined (included for RSX-l1D compatibility)

Undefined (included for RSX-11D compatibility)

Default buffer size for device
of line for terminal)

(e.g.,

The example included below illustrates the use of the three
the GLUN$ macro.

1-20

length

forms

CHAPTER 1.

RSX-llM INPUT/OUTPUT

,.
; DATA DEFINITIONS
GETLUN: GLUN$

6,DSKBUF

GENERATE DPB

EXECUTABLE SECTION
DIR$

#GETLUN

•

GLUN$C

6,DSKBUF

GLUN$S

1.6.6

EXECUTE DIRECTIVE

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

#6,#DSKBUF

The ASTX$S Macro:

GENERATE DPB ON STACK, THEN
EXECUTE DIRECTIVE

Terminating AST Service

The AST SERVICE EXIT macro is used to terminate execution of an
asynchronous system trap (AST) service routine. Only the ASTX$S form
of this macro is provided; ASTX$ and ASTX$C are unsupported forms of
the macro call. The macro is issued in the following way:
ASTX$S
where:

err

[err]

is an optional argument which specifies the address of
an error routine to which control branches if the
directive is rejected.

On comvletion of the operation specified in this macro call, if
another AST is queued and asynchronous system traps have not been
disabled, tilen the next AST is immediately entered.
Otherwise, the
task's state before the AST was entered is restored (it is the AST
ser"ice routine's responsibility to save and restore the registers it
uses).
1.6.7

The WTSE$ Hacro:

Waiting for an Event Flag

The WAIT FOR SINGLE EVENT FLAG macro instructs the system to suspend
execution of the issuing task until the event flag specified in the
macro call is set. This macro is extremely useful in synchronizing
activity on completion of an I/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

CHAPTER 1.

RSX-llM INPUT/OUTPUT
(

WTSE$ causes the task to be suspended 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 1n that call.
The following example illustrates task
suspension pending setting of the specified event flag. This example
also illustrates the use of the three forms of the macro call.
DATA DEFINITIONS
WAIT:
IOSB:

WTSE$
.BLKW

1 GENERATE DPB

I/O STATUS BLOCK

•

EXECUTABLE SECTION
ALUN$S
QIO$C
DIR$
WTSE$C

•

QIO$S

WTSE$S

QIO$C

•
•

WTSE$C
QIO$C

1.7

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

ASSIGN LUN 14 TO MAGTAPE UNIT ZERO

1 ATTACH DEVICE
1

EXECUTE DIRECTIVE

1 WAIT FOR EVENT FLAG 5 TO BE SET

#IO.RLB,#14.,#2,,#IOSB,#ASTX,<#BUF,#80.)
1 READ RECORD
#2

WAIT FOR EVENT FLAG 2

IO.WLB,14.,3"IOSB,AST01,<BUF,80.)
1 WRITE RECORD
3
IO.DET,14.

WAIT FOR WRITE TO COMPLETE
DETACH DEVICE

STANDARD I/O FUNCTIONS

There are a large number of input/output.. operations that can be
specified by means of the QIO macro. 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-depennent 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
1-22

CHAPTER 1.

RSX-llM INPUT/OUTPUT

• 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 IS.SUC 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 parameters represented by the ellipsis ( ••• ) are as
explained in section 1.4.1.

1.7.1

IO.ATT:

Attaching to an I/O Device

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

IO.ATT, •••

Successful completion of an IO.ATT request causes the specified
physical device unit to be dedicated for exclusive use by the issuing
task. This enables' the task to process input or output in an unbroken
stream and is especially useful on sequential, non-file-oriented
devices such as terminals, card readers, and line printers.
An
attached physical device unit remains under control of the issuing
task until it .is explicitly detached by that task. The same LUN must
be sp~cified for both the attach and detach functions.
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.
If the task which issued an' attach function exits or is aborted before
it issues a corresponding detach, the RSX-IlM Executive automatically
detaches the physical device unit.

1-?3

CHAPTER 1.
1.7.2

RSX-llM INPUT/OUTPUT

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

IO.DET, •••

The LUN specifications of both IO.ATT and IO.DET must be the same, as
in the following example, which also illustrates the use of nSn forms
of several macro calls.
• MCALL
ALUN$S

ALUN$S,QIO$S
#14.,#nCR

ASSOCIATE CARD READER WITH LUN 14

#IO.ATT,#14.

ATTACH CARD READER

QIO$S

•
LOOP:

1.7.3

QIO$S

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

QIO$S

#IO.DET,#14.

IO.KIL:

Canceling I/O Requests

READ CARD

DETACH CARD READER

The function code IO.KIL is issued by a task to cancel all of that
task's I/O requests for a particular physical device unit, including
all pending and active requests. This results ~n the status code
IE.ABO being returned in the I/O status block and the event flag being
set (if specified) for the respective requests, but does not initiate
any asynchronous system trap (AST) service routine that may have been
specified. Whether the current request is actually cancelled depends
on the device.
Because file-structured devices (disk and DECtape)
operate quickly, IO.KIL is a NOP for these devices and simply causes
the return of IS.SUC 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.RIL is useful in such special cases as canceling an I/O request on
a physical device unit from which a response is overdue (i.e., a read
on a terminal).

1-24

(
~

CHAPTER 1.

1.7.4

RSX-llM INPUT/OUTPUT

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

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

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

IO.RVB:

Reaning 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 \'d thin a file and is
identical to a "logical" block for such sequential devices as
terminals and card readers. 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 or DECtape), the user must
ensure that a file is open on the specified physi.cal device unit.
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 buffer size in bytes.

1.7.6

IO.RVB, ••• ,(stadd,size,pn)

IO.WLB:

reprp.sents one to four optional parameters, used ·to
specify such a(1di tional information as block numbers
for certain devices.

Writing a Logical Block

The function code IO.WLB is specified by a task to writ~ a block of
data to the physical device unit specified in th(~ macro call. Thi:function code is included as the first: pararnetex- 0:1: a QIOnacrc call
in the follo\'Ting way:
QIO$C
where:

stadd

IO.WLB,~ •• ,<stadd,size,pn)

is th8 starting addre~:; of the c}ata b~.J.ff""r.

CHAPTER 1.

RSX-IIM INPUT/OUTPUT

size
pn

1.7.7

IO.WVB:

is the data buffer in bytes.
represents one to four optional parameters, used to
specify such additional information as block numbers or
format 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 "virtual" block indicates a relative block
position within a file and is identical to a "logical" block for such
sequential devices as terminals and line printers. 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 or
DECtape), 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 follm"ing way:
QIO$C
where:

stadd

is the starti.ng address of the data buffer.

size

is the data buffer size in bytes.

1.8

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

represents one to four optional parameters, used to
specify such a(~di tional information as block numbers or
format control characters for certain devices.

I/O COMPJ.JETION

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 ~i~nificant event is
declared on completion of an I/O
operation.
If an efn parameter \>la,s includec'l. in the I/O
request, the corresponding event flag is set.

If an isb parameter WCl,.s specifiej in the QIO macro call, a
code identifying the type of. success or failure is returned
in the lcy",,-order byte of the first word of t!1e I/O status
block at the location represent~d hy isb.
This status retllrn code is of the form IS.xxx (success) or
IE.x><:x
(error) •
For example, if the device accessed by the
I/O r~quest is not ready, a status code of IE.DNR is returned
in isb. The section belo~.., (Return Codes) summarizes general
("o,~e~ :-:-etu:r.ned b 1' most
of the drivers described in this
T1dnlvll.

CHAPTER 1.

RSX-llM INPUT/OUTPUT

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

1. 9

If an ast parameter was specified in the QIO rflacro 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.4.3 for a
detailed description of AST service routines.

RETURN CODES

There are t\,10 kinds of status conditions
RSX-llM when they occur in I/O requests:

recognized

• Directive condi. tions , which indicate
rejection of the QIO directive itself

-the

and

handled

acceptance

• I/O sta.tus conditions, which indicate the success or
of the I/O operation
Directive conditions relevant to I/O operations may
the following:

(

indicate

failure

nny

• directive acceptance
• invalid buffer specification
• invalid

~fn

parameter

• invalid lun parameter
invalid

(

nrc number or DPB size

• insufficient memory
A code indicating thA aCCE~I!tanc;~ or rejection of a dir.ective L.:{
returned to the directi V~ status 1-'lord at symbolic: locat.ion $DSW. This
location can be tested to determine th€ type of clire.ctive condition.
I/O conditions indicate the SUC(:RS~ or failure of the I/O op{~.ration
specified in the QIO directive.
1/0 driver errors incl~ie such
condi tions as device not ready, pri vilego v5..o1Rtion, file alrr.>~7.(.1.y
open, or i",rite-locked device.
If an isb para.rn8ter is includ~d i'-l t.r~p.
QIO directive, identifyinc; the R\.ldr>7.~ss of a 2-,'lord I/O st.atus hlnck I
an I/O status code is retur.ned in the lovJ-crdp.r byt~ ("If thp. first word
of this block on complet.ion of the 1/0 operation.
Thi.s C'o·le is a
binary value Ylhich corresronas to ~ :=:yFlbolic naMe of the forll1 rs . xxx

CHAPTER 1.

RSX-11M INPUT/OUTPUT

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 sYlnho1ic 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, and the driver has not yet
serviced the request.

1.9.1

Directive Conditions

Tah1e 1-1 summarizes the directive conditions which may be encountered
in QIO directives.
The acceptance condition is firs·t, followed by
error codes indicating various reasons for rejection, in alphabetical
order.

:-:2

CHAPTER 1.

RSX-llM INPUT/OUTPUT
Table 1-1
Directive Conditions

Code
IS.SUC

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 directiv13 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 was less
zero or greater thRn 64.

IE.ILU

(

than

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

IE.SDP

Invalid DIC number or DPB size
The directive identification code (DIC) or the size of
the directive parameter block (DPR) 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.

(

IF..ULN

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

IE.UPN

Insufficient dynamic memory
There was not enough dynarrlic memorv to allocate an I/O
packet for the I/O request. The user can try again
later by suspending the task with a WAITFOR SIGNIFICN~T
EVF.NT directive.
note that WAITFOR SIGNIFICANT EVENT
.is the onlv effective wav for the issuing ta~k to
suspend e;Cecution, since"'other suspend-type directives
that could be used for this purpose themselves require
dynamic memory for their execution (e.g., MARK TIME).

1-29

CHAPTER 1.
1.9.2

RSX-llM INPUT/OUTPUT

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 writing.
If the isb parameter of the QIO directive is omitted, this information
is not returned.
The following illustrates a sample 2-word
completion of a terminal read operation:

Word 0
1

-10

I/O

status

block

Byte

(

Number of bytes read

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

#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 either of these codes, the user
should first test the low-order byte of the first word of the block
for IS.SUC and then test the full word for IS.CR or IS.ESC.
Note that all three of the following comparisons will test equal since
the low-order byte in all cases is +1.

1-3~

CHAPTER 1.

RSX-llM INPUT/OUTPUT

CMPB

#IS.CR,IOSB

CMPB

#IS.ESC,IOSB

CMPB

#IS.SUC,IOSB

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

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

the

status

The codes described in Table 1-2 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 1-2
I/O Status Conditions
Code
IS.SUC

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.

I-Jl

CHAPTER 1.

RSX-IIM INPUT/OUTPUT
(
Table 1-2 (Cont.)
I/O Status Conditions

Code
IE.ABO

Reason
~peration

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.

IE. BAD

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

IE.BLK

Illegal block number

illegal block
number
was
specified
for
a
file-structured physical device unit.
This code is
returned, for example, if block 4800 is specified for
an RKOS 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 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.

{
\

CHAPTER 1.

RSX-llM INPUT/OUTPUT
Table 1-2 (Cont.)
I/O Status Conditions

Code
IE.DNA

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

IE.DNR

Device not ready
The physical device unit specified in the QI9 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

character

was

recognized on the input device.
IE.IFC

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

IE.NLN

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

IE.NOD

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

1-.3.3

CHAPTER 1.

RSX-llM INPUT/OUTPUT
Table 1-2 (Cont.)
I/O Status Conditions
Reason

Code
IE.OFL

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

IE.OVR

Illegal read overlay request
A read overlay wa~ requested and the physical device
unit specified ~n 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 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.WLK

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

1-34

physical

CHAPTER 2
TERMINAL DRIVER

2.1

INTRODUCTION

The terminal driver provides support for a variety of terminal devices
under RSX-11M.
Table 2-1 summarizes the terminals supported, and
subsequent sections describe these devices in greater detail.
Table 2-1
Standard Terminal Devices
Model

Column width

Character Set

Baud Range

ASR-33/35

110

KSR-33/35

110

LA30-P

300

LA30-S

110-300

LA36

80-132

64-96*

110-300

RT02

110-1200

RT02-C

110-1200

VTOSB

110-2400

VTSO

110-300

{

* The LA36 transmits a set of 64 characters, but can print
96.

2-1

set

CHAPTER 2. TERMINAL DRIVER
Where appropriate terminals must be strapped to transmit
only
upper-case alphabetic characters.
Input lines can be at most 80
bytes, and longer input lines are truncated.
The terminal driver
supports the communication line interfaces summarized in Table 2-2.
These interfaces are described in greater detail in section 2.7.
Programming is identical for all.
Table 2-2
Standard Communication Line Interfaces
Model

Type

DHll

l6-line multiplexer or

DHll-DMll-BB

l6-line multiplexer with modem control

DJll

l6-line multiplexer

DLll-A/B/C/D

Single-line interfaces

2.1.1

ASR-33/35 Teletypes

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

2.1.2

terminals.

KSR-33/35 Teletypes

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. It is particularly
appropriate for systems requiring large numbers of printer-terminals.
The LA30-P is a parallel model and the LA30-S is a serial model.

2.1.4

LA36 DECWriter

The LA36 DECwriter is a high-speed asynchronous terminal which
produces hard copy and operates in serial mode. It has an impact
printer capable of generating multipart and special preprinted forms.
Both upper-case and lower-case characters can be printed.

2-2

(

CHAPTER 2. TERMINAL DRIVER

2.1.5

RT02 Alphanumeric Display Terminal

and

RT02-C

Badge

Reader/

Alphanumer~c D~splay Term~nal

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 feature provides
a reliable method of identifying and controlling access to the PDP-Il
or to a secure facility. Furthermore, data in a format corresponding
to that of a badge (22-column fixed data) can be entered very quickly.

2.1.6

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

(

VTSO Alphanumeric Display Terminal

The VT50 is an alphanumeric display terminal that consists of a CRT
display and a keyboard. It is similar to the VT05B in capacity and
operation, but is restricted under RSX-llM to a lower maximum baud
rate and does not offer direct cursor addressing.

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.

2-3

CHAPTER 2. TERMINAL DRIVER
Bit

Setting

Meaning

Record-oriented device

Carriage-control device

Terminal device

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-ll 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.

(

2-~

(

CHAPTER 2. TERMINAL DRIVER
2.3

OIO MACRO

Table 2-3 lists the standard functions of
valid for terminals.

the

QIO

macro

that

are

Table 2-3
Standard QIO Functions for Terminals
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 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)

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

than

The effect of IO.KIL on an in progress request depends upon whether
the request is for input or output. If rt is for input (i.e., IO.RLB
or IO.RVB), the request is forced to terminate. IE.ABO is returned,
and the second word of the I/O status block contains the number of
bytes already typed. If the request is for output (i.e., IO.WLB or
IO.WVB), the transfer is terminated, and IS.SUC is returned.
The terminal driver supports no device-specific functions.

2-5

CHAPTER 2. TERMINAL DRIVER
2.4

STATUS RETURNS

Table 2-4 lists error and status conditions that are returned
terminal driver described in this chapter.

the

Table 2-4
Terminal Status Returns
Code

Reason

IE.EOF

Successful completion on a read with End-of-file
The line of input read from the terminal was terminated
with the end-of-file character CTRL/Z.

IS.SUC

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

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

IS.ESC

Successful completion on a read
The line of input read from the terminal was terminated
by an ESCape or ALTMODE character.

IS.PND

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

IE.ABO

Operation abo);'ted
The specified I/O operation was cancelled via
while in progress or while in the I/O queue.

IE.DAA

IO.KIL

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

2-6

(

CHAPTER 2. TERMINAL DRIVER
Table 2-4 (Cont.)
Terminal Status Returns
Reason

Code
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

• An attempt was made to perform a transfer on
a remote DRII line without carrier present.
IE.IFC

Illegal function
A function code was specified in an
was illegal for terminals.

IE.NOD

I/O

request

that

Buffer allocation failure
Dynamic storage has been depleted, and there was
insufficient space available to allocate a buffer for
an input request (i.e., all input is buffered 'in the
terminal driver).

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.

7-7

CHAPTER 2. TERMINAL DRIVER
The following illustrates the contents of
return of an IS.ESC code:

Word 0
1

/+1

the

I/O

status

block

Byte

Number of bytes read

where 33 is the octal representation of the ESCape or ALTMODE
character, and +1 is the status code for successful completion
(IS.SUC). The contents of this block on return of IS.CR are the same,
except that the high-order byte of word 0 contains 15, the octal code
for carriage return. Unlike other RSX-llM return codes, IS.CR and
IS.ESC are word values, rather than byte values. The low-order byte
simply indicates successful completion, and the high-order byte is
required to show the specific type. To test for an IS.ESC or IS.CR
code, the user can first test the low-order byte of the first word of
the I/O status block for IS.SUC, and then test the full word for
IS.ESC or IS.CR.

2.5

CONTROL CHARACTERS AND SPECIAL KEYS

This section describes the particular meaning
control characters and keys for RSX-I1M.

2.5.1

special

terminal

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 2-5, CTRL/U and CTRL/Z, are echoed on
the termin~l printer as tu and tz respectively.
Other control
characters are recognized by the terminal driver but are not printing
characters and are therefore not echoed.

.....

,..

/.-n

(

CHAPTER 2. TERMINAL DRIVER
Table 2-5
Terminal Control Characters
Character

Meaning

CTRL/C

Typing CTRL/C on the terminal causes unsolicited input
on that terminal to be earmarked for the Monitor
Console Routine (MCR).
When the unsolicited input
completes, it is passed to the MCR dispatcher. "MCR)"
is echoed when the terminal is ready to accept the
unsolicited input.

CTRL/I

Typing CTRL/I initiates a horizontal tab, and the
terminal spaces to the next tab stop. Tabs are set at
every eighth character position.

CTRL/J

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

CTRL/K

Typing CTRL/K ini tia tes a vertical
terminal performs four line feeds.

CTRL/L

Typing CTRL/L initiates a form feed, and the terminal
performs eight line feeds. Paging is not performed.

CTRL/M

Typing CTRL/M is equivalent to typing the carriage
RETURN key on the terminal (See section 2.5.2).

CTRL/O

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

(

•
•

tab,

and

the

The terminal is detached
Solicited input is entered
Unsolicited input is entered
Another CTRL/O character is typed

For unattached terminals, CTRL/O suppresses output
only the current output buffer.

for

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 tU, followed by a carriage return and a
line feed. This allows the line to be retyped.

CTRL/Z

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

CHAPTER 2. TERMINAL DRIVER
2.5.2

Special Keys

The ESCape, carriage RETURN, and RUB OUT keys have special significance
for terminal input, as described in Table 2-6.
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 (i.e., 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.
Table 2-6
Special Terminal Keys
Key

Meaning

ESC

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 since the carriage or cursor is not returned to
the first column position.

RETURN

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

RUB OUT

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 which has been deleted. Subsequent RUBOUTs
cause only the deleted character to be echoed.
The
next character typed which is not a RUB OUT causes
another \ followed by the new character to be echoed.
The following example illustrates rubbing out ABC and
then typing CBA:
ABC\CBA\CBA
The second backs lash is not displayed if a line
terminator is typed after rubbing out the characters on
a line, as in the following:
ABC\CBA

2.6

VERTICAL FORMAT CONTROL

Table 2-7 below summarizes the meanings of all characters used for
vertical format control on the terminal. Anyone of these characters
can be specified as the value of the vfc parameter in an IO.WLB or
IO.WVB function.

2-1f)

(
\

CHAPTER 2. TERMINAL DRIVER
Table 2-7
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 buffer, and output a carriage
return. Normally, the buffer contents are printed
two lines below the previously printed line.

061

one

PAGE EJECT - Output eight line feeds, print the
contents of the buffer, and output a carriage
return.

053

plus

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

044

dollar
sign

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

000

null

INTERNAL VERTICAL FOru~T - The buffer contents are
printed
without
addition of vertical format
control characters. In this mode, more than one
line
of guaranteed contiguous output can be
printed per I/O request.

Meaning

All other vertical format control characters are interpre~ed as blanks
(octal 040).

2.7

TERMINAL INTERFACES

This section summarizes the characteristics of the three types
standard communication line interfaces supported by RSX-llM.

2.7.1

DRll Asynchronous Serial Line Multiplexer

The DRll multiplexer interfaces up to 16
asynchronous
serial
communications lines for terminal use. As many as 16 DRlls can be
interfaced to the PDP-II, and the total capacity is therefore 256

2-11

CHAPTER 2. TERMINAL DRIVER
lines. The DHll supports programmable baud rates with no parity. The
DMIl-BB option may be included to provide modem control for dial-up
lines.
These lines must be interfaced via Bell 103 or equivalent
modems.

2.7.2

DJ11 Asynchronous Serial Line Multiplexer

The DJll multiplexer interfaces as many as 16 asynchronous serial
lines to the PDP-II for local terminal conununications. As many as ~6
DJlls can be interfaced to the PDP-II, and the total capacity ~s
therefore 256 lines. The DJll does not provide a dial-up capability
but supports jumper selectable baud rates.

2.7.3

DLll Asynchronous Serial Line Interface

The DLll supports a single asynchronous serial line and handles
full-duplex communication between the PDP-II and a terminal. There
are 13 standard baud rates available to DLll users
(40-9600 baud).
Four versions of the DLll interface are supported by RSX-llM for
terminal use: DLII-A, DLII-B, DLII-C, and DLII-D.
The DLII-E is
supported only for message-oriented communications and is described in
Chapter 9. A total of 16 DLll interfaces can be supported on a single
system for terminal use.

2.8

PROGRAMMING HINTS

This section contains information on important considerations relevant
to users of the terminal driver described in this chapter.

2.8.1

Terminal Line Truncation

If the number of char~cters to be printed exceeds the line length of
the physical device unit, the terminal driver discards the excess
characters. The user can determine that this will happen by examining
word 5 of the information buffer returned by the GET LUN INFORMATION
system directive.
2.8.2

ESCape Code Conversion

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.

2.8.3
\~len

RT02-C·Control Function

sending a control character (e.g., vertical tab) to the RT02-C
Badge Reader and Data Entry Tenoinal, the high-order bit (bit 7) of
the byte must be set to one. This causes the terminal driver not to
recognize the character.
In the case of a vertical tab, 213 octal
must b,3 output rather thfu"'l 13 octal.

(

CHAPTER 3
DISK DRIVERS

3.1

INTRODUCTION

The RSX-llM disk drivers support the disks summarized in Table
Subsequent sections describe these devices in greater detail.

3-1.

Table 3-1
Standard Disk Devices

(

CYLINDERS WORDS/
TRACK

WORDS/
DRIVE

MODEL

RPM

SURFACES

RFll/RS1l

1800

128

2048.

262,144.

RJP04

3600

411

5632.

43,980,288.

RJS03

3600

4096.

262,144.

RJS04

3600

8192.

524,288.

RKll/RK05

1500

200

3072.

1,228,800.

RPllC/RP03

2400

400

2560.

20,480,000.

All of the disks described in this chapter are accessed in essentially
the same Manner. Up to eight disks of each type 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.

3.1.1

RFl1/RSll Fixed-Head Disk

The RFll controller/RSll fixed-head disk provides random-access bulk
storage. It features fast track-switching time and a redundant set of
timing tracks. The RF11/RSll is unique because ,the hardware can
automa'tically perform a spiral read across disk platters.

~"'·l

3.1.2

RJP04 Pack Disk

The RJP04 (RHll controller/RP04 pack disk) pack disk consists of 19
data surfaces and a moving read/write head. It is similar to the
RPll-C/RP03, but has twice the capacity.
The RJP04 offers large
capacity storage with rapid access time.

3.1.3

RJS03 Fixed-Head Disk

The RJS03 (RHll controller/RS03 fixed-head disk) is a fixed head disk
which offers speed and efficiency. With 64 tracks per cylinder, the
RJS03 has a capacity of 262,144 words.

3.1.4

RJS04 Fixed-Head Disk

The RJS04(RHll controller/RS04 fixed-head disk) is similar to the
RJS03 disk, and interfaces to the same controller but provides twice
the number of words per track and twice the capacity.

3.1.5

RKll/RK05 Cartridge Disk

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.

3.1.6

RPll-C/RP03 Pack Disk

The RPll-C controller/RP03 pack disk consists of 20 data surfaces and
a moving read/write head.
Only an even number of words can be
transferred in an RP03 read/write operation.
(

1-2

CHAPTER 3.
3.2

DISK DRIVERS

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

Setting

Record-oriented device

Carriage-control device

Terminal device

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-II volume

Device mountable

Meaning

Words 3 and 4 of the buffer are undefined;
word
default buffer size, which is 512 for all disks.

3.3

indicates

the

QIO l>1ACRO

Table 3-2 lists the standard functions of the QIO macro that are valid
for disks.

3-3

CHAPTER 3.

DISK DRIVERS
,(
\

Table 3-2
Standard QIO Functions for Disks
Format

Function

QIO$C IO.ATT, •••

Not applicable (NOP)

QIO$C IO.DET, •••

Not applicable (NOP)

QIO$C IO.KIL, •••

Not applicable (NOP)

QIO$C IO.RLB, ••• ,<stadd,size"blkh,blkl)

Read logical block

QIO$C IO.RVB, ••• ,<stadd,size"blkh.blkl)

Read virtual block

QIO$C IO.WLB, ••• ,<stadd,size"blkh,blkl)

Write logical block

QIO$C IO.WVB, ••• ,<stadd,size"blkh,blkl)

Write virtual block

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

(

IO.RVB and IO.WVB are associated with file operations (see the RSX-ll
I/O Operations Reference Manual). For these functions to be executed,
a file must be open on the specified LUN.
The disk drivers support no device-specific functions.
{

\
3.4

STATUS RBTURNS

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

are

returned

3-A

CHAPTER 3.

DISK DRIVERS

(
Table 3-3

Disk Status Returns
Reason

Code
IS.SUC

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

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

IE.BLK

Illegal block number
An illegal logical block number was specified.
This
code would be returned, for example, if block 4800 were
specified for an ID<05 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 alignment is legal for disk. Alternately, the
length of a buffer is not an appropriate number of
bytes.
For example, all RP03 disk transfer must be a
multiple 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. IFC Illegal ,function
A function code was specified in an I/O request that is
illegal for disks.

1-5

CHAPTER 3.

DISK DRIVERS
/

Table.3-3 (Cont.)
Disk Status Returns
Reason

Code
IE.NLN

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

IE.NOD

IE.OFL

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

IE.OVR

Illegal read overlay request

('
\

A read overlay wa~ requested, and the physical device
unit specified ~n 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 disk, this code is returned
if a nonprivileged task attempts to read or write a
mounted volume directly (i.e., IO.RLB or IO.WLB).

3-6

(
\

CHAPTER 3.

DISK DRIVERS

Table 3-3 (Cont.)
Disk Status Returns
Reason

Code
IE.SPC

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

IE. VER

Unrecoverable error
After the system's standard number of retries has been
attempted upon encountering an error, the operation
still could not be completed. For disk, unrecoverable
errors are usually parity errors.

IE.WLK

Write-locked device
The task attempted to
physically write-locked.

write

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.

(

3-7

CHAPTER 4
DECTAPE DRIVER

4.1

INTRODUCTION

The RSX-llM DECtape driver supports the TCll-G dual DECtape controller
with up to three additional dual DECtape transports. The TCll-G is a
dual-unit, bidirectional, magnetic-tape transport system for auxiliary
data storage.
DECtape is formatted to store data at fixed positions
on the tape, rather than at unknown or variable positions as on
coventional magnetic tape. The system uses redundant recording of the
mark, timing, and data tracks to increase reliability.
Each reel
contains 578 logical blocks. As with disk, each of these blocks can
be accessed separately, and each contains 256 words.

4 .2

GET LUN INFORJvlATION HACRO

Word 2 of the buffer filled by the GET LUN INFORMATION sy~tem
directive
(the first characterics word) contains ~che following
information for DECtapes. A bit setting of 1 indicates that the
described characteristic is true for DECtapes.

4.-1

CHAPTER 4.

DECTAPE DRIVER

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-ll volume

Device mountable

Meaning

Words 3 and 4 of the buffer are undefined;
default buffer size, for DECtape 512 bytes.

4.3

word

indicates

the

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the DECtape driver.

4.3.1

Standard OIO Functions

Table 4-1 lists the standard functions of the QIO macro that are valid
for DECtape.

4-2

CHAPTER 4.

DECTAPE DRIVER
Table 4-1
Standard QIO Functions for DECtape

Format

Function

QIO$C IO.ATT, •••

Not applicable (NOP)

QIO$C IO.DET, •••

Not applicable (NOP)

QIO$C IO.KIL, •••

Not applicable (NOP)

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)

where:

(

stadd

is the starting address of the data buffer (must be
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

IO.RVB and IO.WVB are associated with file operations (see the RSX-llM
I/O Operations Reference Manual). For these functions to be executed,
a file must be open on the specified LUN.

CHAPTER 4.
4.3.2

DECTAPE DRIVER

Device-Specific QIOFunctions

The device-specific functions of the QlO
DECtape are shown in Table 4-2.

macro

that

are

valid

for

Table 4-2
Device-Specific Functions for DECtape
Function

Format
QlO$C lO.RLV, ••• ,<stadd,size",lbn)

Read logical block (reverse)

QlO$C lO.WLV, ••• ,<stadd,size",lbn)

Write logical block (reverse)

Where:

4. 4

stadd

is the starting address of the data buffer (must be
a word boundary) •

size

is the data buffer size
greater than zero).

even

and

lbn

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

the

byte

(must

STATUS RET,URNS

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

are

returned

CHAPTER 4.

DECTAPE DRIVER
Table 4-3
DEC tape Status Returns
Reason

Code
IS.SUC

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

File already open
The task attempted to open a file on the physical
device unit associated with specified LUN, put 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.

!-s

CHAPTER 4.

DECTAPE DRIVER
Table 4-3 (Cont.)
DECtape Status Returns
Reason

Code
IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for DECtape.

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

IE.OFL

IE.OVR

Illegal read overlay request
A read overlay was requested and the physical device
unit specified ~n 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 (i.e., IO.RLB, IO.RLV,
IO.WLB, or IO.WLV). 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.

(

CHAPTER 4.

DECTAPE DRIVER
Table 4-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.
• A parity error was encountered.

IE.WLK

• The task attempted a forward
past block 577 (1101 octal).

multi-block

transfer

• The task attempted a
past block zero.

multi-block

transfer

backward

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

4.4.1

was

DECtape Recovery Procedures

When a DECtape I/O error condition is detected, RSX-1lM 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 98, 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 98, 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.

4-7

CHAPTER 4.
4.4.2

DECTAPE DRIVER

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.

4.5

PROGRAMMING HINTS

This
section
considerations
this chapter.

4.5.1

contains
information
on
important
programming
relevant to users of the DECtape driver described in

DECtape Transfers

If the transfer length on a write is less than 256 words, a partial
block is transferred with zero fill for the rest of the physical
block. If the transfer length on a read is less than 256 words, only
the number of words specified is transferred. If the transfer length
is greater than 256 words, more than one physical
block
is
transferred.

4.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 0, and 254 becomes word 1). If this occurs, the
user must then reverse the data within memory.

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

(

CHAPTER 4.

DECTAPE DRIVER

writing can be performed, a tape block cannot be accessed immediately
after reversing direction. Two blocks must be bypassed before a read
or write function can be executed, to give the tape unit time to build
up to normal access speed. Furthermore, when a request is issued to
read or write in a certain direction, the tape first begins to move in
that direction, then starts detecting block numbers. The following
examples illustrate these principles.
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.

4.5.4

Aborting a Task

If the user attempts to abort a task which is waiting for a DECtape
unit to be selected, the unit must actually be selected before the
task will actually be aborted.

(

4-9

CHAPTER 5
MAGNETIC TAPE DRIVERS

5.1

INTRODUCTION

RSX-llM supports two magnetic tape devices, the TMll and the TJU16.
Table 5-1 sununarizes these devices and subsequent sections describe
them in greater detail.
Table 5-1
Standard Magtape Devices

(

TMll

TJU16

Number of channels

7 or 9

Recording density, in frames
per inch

For 7-channel:
200, 556,
800;
for 9-channel:
800

800 or 1600

Tape speed, in inches per
second

Maximum data transfer rate,

36,000

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

NRZI

NRZI or
Phase
Encoding

in bytes per second

Recording Method

Programming for Magtape is quite similar to programming for the
magnetic tape cassette
(see Chapter 6). Unlike cassette, however,
Magtape can handle variable-length records and allows the user to
select a parity mode.
RSX-llM does not support a file structure for Magtape.

5-1

CHAPTER 5.
5.1.1

MAGNETIC TAPE DRIVERS

TMll Magnetic Tape

The TMll consists of a TMll controller with a TU10 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).

5.1.2

TJU16 Magnetic Tape

The TJU16 consist of an RHll,controller, a TM02 formatter, and a 'TU16
transport.
It is quite similar to the TMll but is a Massbus device,
with a common controller, a specialized formatter, and a drive.
Recording is either 800 bpi NRZI or 1600 bpi phase-encoded (PE).
5.2

GET LON INFORMATION MACRO

Word 2 of the buffer filled by the GET LUN INFORMATION system
directive (the first characteristics word) contains the following
information for 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

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-ll volume

Device mountable

Meaning

Words 3 and 4 of the buffer are undefined;
default buffer size, for Magtapes 512 bytes.

5-2

word

indicates

the

CHAPTER 5.
5.3

MAGNETIC TAPE DRIVERS

QIO MACRO

This section sununarizes standard and device-specific QIO functions for
the Magtape drivers.

5.3.1

Standard QIO Functions

Table 5-2 lists the standard functions of the QIO macro that are valid
for Magtape.
Table 5-2
Standard QIO Functions for Magtape
Function

Format
QIO$C IO.ATT / •••

Attach device

QIO$C IO.DET, •••

Detach device

QIO$C IO.KIL, •••

Cancel I/O requests

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

Read logical block
(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 (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.

5-3

select

error

CHAPTER 5.
5.3.2

MAGNETIC. TAPE DRIVERS

Device-Specific QIO Functions

Table 5-3 lists the device-specific functions of the QIO macro that
are valid for Magtape. Additional details on certain functions appear
below.
Table 5-3
Device-Specific QIO Functions for Magtape
Format

Function

QIO$C IO.EOF, •••

Write end-of-file mark (tape mark)

QIO$C IO.RWD, •••

Rewind unit

QIO$C IO. RWU, •••

Rewind and turn unit off-line

QIO$C IO.SEC, •••

Read tape characteristics

QIO$C IO.SMO, ••• ,<cb)

Mount tape and set tape characteristics

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

Space blocks

QIO$C IO.SPF, ••• ,<nes)

Space files

QIO$C IO.STC, ••• ,<cb)

Set tape characteristics

where:

represents the characteristic bits to set.

nbs

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

past

(positlve

nes

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

(positive

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

5-.1

CHAPTER 5.

MAGNETIC TAPE DRIVERS

5.3.2.2 IO.SEC - This function returns the tape characteristics in
the second I/O status word. The tape characteristic bits are defined
as follows:
Can Be Set by
IO.SMO and IO.STC

13it

Meaning When Set

For TM11, 556 bpi density
(seven-channel). For
TJU16, reserved

For TMll, 200 bpi density
(seven-channel). For
TJU16, reserved.

For TMll, core-dump mode
(seven-channel, see below).
For TJU16, reserved.

Even parity (default is odd).

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

Select error on unit (reserved
for driver; always 0 when read
by user).

Unit is rewinding (reserved for
driver; always 0 when read by
user).

Tape is physically write-locked.

For TMll, reserved.
1600 bpi density.

For TMll, drive is seven-channel.
For TJU16, reserved.

Tape is at load point (BOT).

Tape is at end-of-volume (EOV).

Tape is past EOV.

For TJU16,

5-5

CHAPTER 5.

MAGNETIC TAPE DRIVERS

In core-dump mode (TM11 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.
The effect of these settings is illustrated in Figure 5-1 for the TM11
and in Figure 5-2 for TJU16.

5-6

(

CHAPTER 5.

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

(
SET 800 BPI,
SEVEN-CHANNEL

Figure 5-1
Determination of Tape Characteristics
for the TM11
5-7

CHAPTER 5.

MAGNETIC TAPE DRIVERS

yes

SET 1600 BPI 1.4-------<.

SET 800 BPI

yes

SET
-EVEN PARITY

Figure 5-2
Determination of Tape Characteristics
for the TJU16

5-8

CHAPTER 5.
5.4

MAGNETIC TAPE DRIVERS

STATUS RETURNS

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

are

returned

Table 5-4
Magtape 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
bytes processed, if 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 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.

IF..BBE

Bad block
A had 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 TMIl, IE.BBE may also
indicate that a bad tape error (BTE)
has
been
encountered while reading or spacing.

(
IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a buf.fer, but only
word alignment is legal for Magtape. Alternately, the
length of a buffer is not an even number of bytes.

IE.DAA

Device already attached
The physical device tmit specified in a~
IO.ATT
function was already attached by the issuing task.
This code indic~tes that the i~suing task has already
attached the desired physical devicp. unit, not that the
unit was attached by another task •

.3-9

CHAPTER 5.

MAGNETIC TAPE DRIVERS
Table 5-4 (Cont.)
Magtape Status Returns
Reason

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

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 occurred on the physical device unit (i.e.,
an interrupt was lost).
• A vacuum failure occurred on the Magtape drive.
• While trying to read or space,
blank tape.

IE.EOF

the

driver

detected

• The "LOAD" switch on the physical drive was
to the off position.

switched

End-of-file encountered
An end-of-file (tapemark) was encountered.

IE.EOT

End-of-tape encountered
The
end-of-tape
(physical
end-of-volume)
was
encoun tered while the tape was moving in the fon-Tard
direction. A ten-foot length of tape is provided past
EaT to be used for writing data and markers, such as
volume trailer lru)els. The IE.EOT code will continue
to be returned in the I/O status block until the EaT
marker is passed in the reverse direction.

5-10

CHAPTER 5.

MAGNETIC TAPE DRIVERS
Table 5-4 (Cont.)
Hagtape status Returns

Code
IE.EOV

Reason
End-of-volume encountered
On
a
forward
spacing
function",
the
logical
end-of-volume
(two
consecutive
EOF
marks)
was
encountered. The tape is normally left positioned
between the two EOF marks.

IE.FHE

Fatal hardware error
Fatal hardware malfunction.

IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for Magtape.

IE.OFL

IE.SPC

Illegal address space
The buffer specified for a read or \oTrite 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 \Olas less than 14 bytes
long.

IE.VER

Unrecoverable error
After the system's standard number of retries has been
attempted upon encountering an error, the opt-1ration
still could not be completed. For Magtape, this code
is returned in the case of eRe or checksum errors or
when a tape block could not be read.

IE.WLK

Write-locked device
The task attempted to write on a Hagtape unit that was
physically
write-locked.
Alternately,
tape
characteristic bit 6 was set by the software to
w'rite-lock the unit logically.

5-11

CHAPTER 5.

MAGNETIC TAPE DRIVERS

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 of 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 contai~ an octal two.

5.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 trni t is made available. In the
latter case, the driver then proceeds with the request.

5.4.2

Retry Procedures for Peads and writes

If an error occurs during a read (e.g., vertical parity error), the
recovery procedure depends on the. type of j..fagtape in use. A bad tape
error on a TMll results in an immediate return of the error code
IE. BBE. All other read errors for both the Tf1ll and TJU16 are retried
by backspacing one record and then rereading the record in question.
If the error persists after nine retries, IE.BBE is returned.
Wri te recovery is the same for both the THll and TJUl6. ltfuen 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.BBE is returned.
The requesting task can use IO.STC to prohibit
~.,riting with an extended interrecord gap.
In this case, IE.BBE is
returned as soon as a write fails.

5.5

PROGHAI1L'1ING HINTS

section
This
considex-ations
this chapter.

5.5.1

Block Size

E~ch tlo(;}.
·i~e
Cin{~

•...l1...

Vliti~

information
on
important
programming
contains
relevant to users of the .i'1agtape c1ri vers described in

nm:;t. contain <l.'1 even number of: bytes, at l~ast 14
for a
at.: 11-,\'S-:' n51'53~1.
It. is more reasor~able: 11m-lever, to''lork

blocl~

s::'.ze of

(1~proximCl-f:81y

2,048 bytes.

5-1"

(
\

(

CHAPTER 5.

5.5.2

MAGNETIC TAPE DRIVERS

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 the previous task left these characteristics.
It is also possible that an operator might have changed the Magtape
unit selection. If the selection switch is changed, the new physical
device unit may not correspond to the characteristics of the unit
described by the respective unit control block.

5.5.3

Aborting a Task

If a task is aborted while waiting for a Magtape unit to be selected,
the lvlagtape driver recognizes this fact ,\,li thin 15 seconds. It is not
necessary to select the Magtape unit before aborting the task, as is
the case for DRCtape.

5.5.4

(

Writing an Even-Parity Zero

If an even-parity zero were written normally, it would appear to the
If
drive as blank tape.
It is therefore converted to 20 (octal).
no
this conversion is undesirable, the user must ensure that
even-parity zeros are output on the tape.

(

5-13

(

CHAPTER G
CASSETTE DRIVER

G.l

INTRODUCTION

RSX-llf.1 supports the TAll magnetic tape cassette (a TAll controller
with a TUGO dual transport).
Programming for cassette is quite
similar to pro<]ramroing for l-1agtape (see Chapter 5). 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 cassett?s.
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 per inch, depencling on tape position.

(
6.2

GET LUN INFORMATION lvtACRO

Word 2 of the buffer filled by the GET LUN INFORMATION system
directive (the first characteristics word) contains the following
information for cassettes. A bit setting of I indicates that the
described characteristic is true for cassettes.

6-1

CHAPTER 6.

CASSETTE DRIVER

Bit

Setting

Meaning

Record-oriented device

Carriage-control device

Terminal device

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-II volume

Device mountable

Words 3 and 4 of the buffer are undefined;
default buffer size, for cassettes 128 bytes.

6.3

word

indicates

the

OIO MACRO

This section summarizes standard and device-specific QIO functions for
the cassette driver.

CHAPTER 6.

6.3.1

CASSETTE DRIVER

Standard QIO Functions

Table 6-1 lists the standard functions of the QIO macro that are valid
for cassette.
Table 6-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

QlO$C lO.RLB, ••• ,(stadd,size)

Read logical block
(read tape into buffer)

QIO$C lO.RVB, ••• ,(stadd,size)

Read virtual block
(read tape into buffer)

QlO$C lO.WLB, ••• ,(stadd,size)

write logical block
(write buffer contents to tape)

QIO$C lO.WVB, ••• ,(stadd,size)

write virtual block
(write buffer contents to 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 than
zero).

lO.KlL does not affect in progress requests.

(

6.3.2

Device-Specific 010 Functions

Table 6-2 lists the device-specific functions of the QlO macro that
are valid for cassette.
The section on programming hints below
provides more detailed information about certain functions.

6-3

CHAPTER 6.

CASSETTE DRIVER
Table 6-2
Device-Specific QIO Functions for Cassette

Format

Function

QIO$C IO.EOF, •••

write end-of-file gap

QIO$C IO.RWD, •••

Rewind unit

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

Space blocks

QIO$C IO.SPF, ••• ,<nes)

Space files

where:

6.4

nbs

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

past

(positive

nes

is the number 6f EOF gaps to space
forward, negative if reverse).

past

(positive

are

returned

STATUS RETURNS

The error and status conditions listed in Table 6-3
the cassette driver described in this chapter.
Table 6-3
Cassette Status Returns
Reason

Code
IS.SUC

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

IS.PND

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

IE.ABO

Op(~ration

aborted

The specified I/O operation was
while still in the I/O queue.

6-4

cancelled

via

lO.KIL

CHAPTER 6.

CASSETTE DRIVER
Table 6-3 (Cont.)
Cassette Status Returns
Reason

Code
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.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 attachmeht status of other
tasks.

IE.DNR

Device not ready
The physical device unit specified in the QIO directive
was not ready to perform the desired I/O operation.
This code is returned to indicate one of the following
conditions:
• The cassette has not been physically inserted.
• The unit is off-line.
• A timeout occurred on the physical device unit (i.e.,
an interrupt was lost).

(

IE.EOF

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.

6-5

CHAPTER 6.

CASSETTE DRIVER
Table 6-3 (Cont.)
Cassette Status Returns

Code
IE.EOT

Reason
End-of-tape encountered
While reading or writing, clear trailer at end-of-tape
(EOT) 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 se,ction of tape.
If IE.EOT is
returned
during
a write, the cassette head has
encountered EOT before finishing the writing of the
last block.
It is recommended that the user rewrite
the block on another cassette in its entirety.

IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for cassette.

IE.OFL

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

Unrecoverable error
This code is returned when a block check error occurs
(see section 6.6.5).
The cyclic redundancy check
(CRC), a two-byte value located at the end of each
block, is a checksum that is tested during all read
operations to ensure that data is read correctly.
If
an unrecoverable 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 ~ay be returned
after an IO.VlLB, IO.Wv"'B, or IO.EOF function.

6-6

CHAPTER 6.
6.4.1

CASSETTE DRIVER

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 place. More than three retries of a write .operation may destroy
previously written data. For example, to retry a write, it is best to
space two blocks in reverse, then space one block forward.
This
insures the tape is in the proper position to rewrite the block that
encountered the error.
After read and write functions, the second I/O status word contains
the number of bytes actually processed by the function. After spacing
functions, it contains the number of blocks or files actually spaced.

6.5

STRUCTURE OF CASSETTE TAPE

Figure 6-1 illustrates a general structure for cassette
different structure can be employed if the user wishes.

tape.

Here the tape consists of blocks of data interspersed with sections of
clear tape that serve as leader, trailer, interrecord gaps (IRGs), and
end-of-file gaps.

(

The logical end-of-tape in this case consists of a sentinel label
record, rather than the conventional group of end-of-file gaps. Each
file must contain at least one block. The size of each block depends
upon the number of bytes the user specifies when vlri ting the block.

IRGs

BOT

,.......

FILE 1
\

FILE 2
150'"FEET

Figure 6-1
Structure of Cassette Tape

6-7

)

EOT

'---'
LEOT
I

CHAPTER 6.

CASSETTE DRIVER

Abbreviation

6.6

Clear leader

BOT

Physical beginning-of-tape

LPG

IJoad point gap (blank tape written by driver before the
.f.irst retrievable record)

File label record

REC

Fixed-length record (data)

EOF

End-of-fi1e gap

IRG

Interrecord gap

SLR

Sentinel label record

LEOT

Logical end-of-tape

EOT

Physical end-of-tape

Clear trailer

PROGRAHMING HINTS

This
section
considerations
this chapter.

6.6.1

r.1eaning

contains
information
on
important
programming
relevant to users of the cassette driver described in

Importance of Rewinding

The first cassette operation performed on a tape must always be a
rewind to ensure that the tape is positioned to a known place. When
it is positioned in clear tape there is no way to determine whether it
is in leader at the beginning-of-tape
(BOT) or in trailer at the
end-of-tape (EOT).

6-8

{

CHAPTER 6.
6.6.2

CASSETTE DRIVER

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, follo\'led by IO.SPB in reverse for one block.

6.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 are encountered. For
example, suppose the tape is positioned in clear leader at BOT nnd t~e
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 cOITlJnand 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.

(
\

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

6.6.5

(

Block Length

The user must specify the exact number of bytes per block \07hen
requesting read or write operations. An attempt to read a block with
an incorrect byte count causes an unrecoverable error (see section
6.4) to occur.

6.6.6

Logical Rnd-of-Tape

The conventional method of signaling logical end-of-tape by multiple
EOF gaps is inadequate for cassettes. This is because multiple ROF
gaps are not distinguishable from each other.
For example, two
sequential EOF gaps would be read as three instead of two. Also
spacing fWlctions, since they are triggered by encountering data, can
not recognize mUltiple EOF gaps. Consequently, ~le use of a sentinel
or key record to signal logical end-of-tape is recommended.

~-9

(

CHAPTER 7
LINE PRINTER DRIVER

7.1

INTRODUCTION

The RSX-111-1 line printer driver supports the line printers summarized
in Table 7-1.
Subsequent sections of this chapter describe these
printers in greater detail.
Table 7-1
Standard Line Printer Devices

Model

(

Column width

Character Set

Lines per Hinute

LP11-F

170-1110

LP11-H

170-1110

LP11-J

132

170-1110

LPI1-K

132

170-1110

LP11-R

132

1110

LPII-S

132

1110

LSI1

132

60-200

LVII

132

500

7-1

CHAPTER 7.
7.1.1

LINE PRINTER DRIVER

LPII Line Printer

The l,PIl is a high-speed line printer available in a variety of
models.
The entire LPII line consists of impact printers, using one
h~~er per column and a revolving drum with
upper-case and optional
lower-case characters.
The LPll-R and IJPll-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 print line is no
longer than 20 characters.
Lines which exceed this maxiMum are
printed at a slo'Vler rate. Forms with up to six parts may he used for
multiple copies.

7.1.2

LSII Line Printer

The LSII is a mediuM-speed line printer.
It has a 20-character print
buffer, and lines of 20 characters or less are printed at a rate of
200 lines per minute. Longer lines are printed at a slO'Vler rate.
RSX-IlM does not support the LSII expanded character set feature.

7.1.3

LVII I.line Printer

The LVII is R fully-buffered electrostatic printer-plotter which
operates at a standard rate of 500 lines per mi.nute.
RSX-IlM supports
only the LVII print capabili t:y, not the plotter Mode.

7.2

GET LUN INFOHNATION' HACRO

Word 2 of
di.rp.cti..~,e

the buffer fi lIed hy thE=: GET LUN INFO";Uiffi.TION syster'l
(the first charncteriRt.ics word)
contains the following
infoTJYlation for line printers. A bit settin<] of J. indicates that the
described characteristic is true for line printers.
(

Bit

3p.tting

Record-oriented device

Carriage-control device

Terminal Clevice

Dir(~cto:ry

"
,;

Sinule-directory de'\.T.ir.e

Se<:Ill~ntia.l

r1eaning-

device

devic\-:')

7-2

CHAPTER 7.

LINE PRINTER DRIVER

Bit

Setting

6-12

Reserved

Device mountable as
channel

Device mO'llnt.::ilile as a FILES-II volUP1e

Device mountable

I'-1eaning

;;t

cOF\Inunications

Words 3 and 4 of the buffer are undefined;
word 5 indicates the
default buffer size for the device, .for line printers the width of th(~
printer carriagp. (i.e., 80 or 132).
7.3

QIO MACRO

Table 7-2 lists the sta.ndarcl functions of the QIO macro that are valid
for line printers.
Table 7-2
Standard QIO Functions for Line Printers
Format

Functi.on

QIO$C IO.ATT, •••

Atta.ch device

QIO$C IO.DET, •••

Dei.:acl1 devicp.

QIO$C IO.KIL, •••

Can.cel I/O requests

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

Write logic~J block
contents)

(print

buffer

QIO$C IO.'''1VB, ••• ,<stadd,siz~,'7fc)

~lrite

(print

hn:fEer

where:

virtual hlock.
content.s)

stadd

is the starting address oft:1e data buffer (nay be on a
byte boundary).

size

is the data buffer. size in by·te~ (must be gr,=>ater
zp.ro).

vfc

is a vert.ical format control char.acte:r: fror 1 '?ablp. 7-4.

thaI!

IO.KIL does not cancel an in progress request unless the line ~rinter
is in an offline condition becaune of B p()wt'~r failure or a pnp~~r j~.l!!
or because it is out of paper.

':'he line printer driver supports no c1evi("!e-speci.fir.

7-1

fn~lc·l:io:rls.

CHAPTER 7.
7•4

LINE PRINTER DRIVER

STATUS RETURNS

Table 7-3 lists the error and status conditions that are
the line printer driver described in this chapter.

returned

Table 7-3
Line Printer Status Returns
Code

Reason

IS.SUC

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 canceled
progress or while in the I/O queue.

IE.DAA

while

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 alre~dy
attached the desired physical device unit, not that the
unit was attached by another task.

IE. DNA

Device not attached
f

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

7-,1

CHAPTER 7.

LINE PRINTER DRIVER
Table 7-3 (Cont.)
Line Printer Status Returns

Code

Reason

IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for line printers.

IE.OFL

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.

7.4.1

(

Ready Recovery

If any of the following conditions occur:
Paper jam
Printer out of paper
Printer turned off-line
Power failure

(

the driver determines that the line printer is off-line,
following message is output on the operator's console:

and

the

*** LPn: -- NOT READY
where 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 15
seconds until the line printer is readied. If a power failure occurs
while printing a line, the entire line is reprinted from the beginning
when ~ower is restored.

7-5

CHAPTER 7.
7.5

LINE PRINTER DRIVER

VERTICAL FORMAT CONTROL

Table 7-4 summarizes the meaning of all characters used for vertical
format control on the line printer. Anyone of these characters can
be specified as the vfc parameter in an IO.WLB or IO.WVB function.
Table 7-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 buffer, and output a carriage
return. Normally, the buffer contents are printed
two lines below the previously printed line.

061

one

PAGE EJECT:
output a form feed, print
the
contents of the buffer, and output a carriage
return. Normally, the contents of the buffer are
printed on the first line of the next page.

053

plus

OVERPRINT: print the contents of the buffer and
perform a carriage return, normally overprinting
the previous line.

044

dollar
sign

PROMPTING OUTPUT: output a line
print the contents of the buffer.

000

null

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

Meaning

feed

and then

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

7.6

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the line printer driver described
in this chapter.

7-6

{
\

CHAPTER 7.
7.6.1

LINE PRINTER DRIVER

RUB OUT Character

The line printer driver discards the ASCII character code 177 during
output, because a RUBOUT on the LSll printer causes a RUB OUT of the
hardware print buffer.

7.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 exam1n1ng
word 5 of the information buffer. This word contains the width of the
print carriage in bytes.

7.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. It is
not necessary to ready the printer before aborting the task, as is the
case for DECtape.

(

7-7

CHAPTER 8
CARD READER DRIVER

8.1

INTRODUCTION

The RSX-llM card reader driver supports the CRII 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.

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

~-J.

CHAPTER 8.

CARD READER DRIVER

Bit

Setting

Record-oriented device

Carriage-control device

Terminal device

Directory device

Single-directory device

Sequential device

6-12

Reserved

Device mountable as a communications
channel

Device mountable as a FILES-ll 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.

8.3

the

(
\

OIO MACRO

This section summarizes standard and device-specific OIO functions for
the card reader driver.

8.3.1

Standard OIO Functions

Table 8-1 lists the standard functions of the OIO macro that are valid
for the card reader.

8-2

CHAPTER 8.

CARD READER DRIVER
Table 8-1
Standard QIO Functions for the Card Reader

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

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

Read virtual block (alphanumeric)

where:

(alphan~eric)

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

than

lO.KlL does not cancel an in progress request unless the card reader
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.

8.3.2

Device-Specific QlO Function

The device-specific function of the QlO macro that is
card reader is shown in Table 8-2.

valid

for

the

Table 8-2
Device-Specific QIO Function for the Card Reader
Format

Function

QlO$C IO.RDB, ••• ,<stadd,size)
where:

Read logical block (binary)

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

8-3

than

CHAPTER 8.
8.4

CARD READER DRIVER

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

Lights and indicators on the card reader panel are turned on
or off to indicate particular operational problems such as
read, pick, stack, or hopper checks. Switches are available
to turn the reader power on and off and to allow the user to
reset after correcting an error condition.

A message is output on the operator's console if
checks or power problems occur.

An I/O completion code is returned in the low-order byte of
the first word of the I/O status block specified in the QIO
macro to indicate success or failure on completion of an I/O
function.

operational

The following subsections describe each of these returns in detail.

8.4.1

Card Input Errors and Recovery

The table included below describes all external lights and switches
used to indicate to the operator that a hardware problem has occurred
and must be corrected. There are two classes of hardware errors:
Those requiring the operator to ready the reader and try
operation again.

•

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

8-4

CHAPTER 8.

CARD READER DRIVER
Table 8-3
Card Reader 'Switches and Indicators

Indicator

Description

POWER
switch

pushbutton
indicator
switch
(alternate
action:
pressed for
both ON and
OFF)

Action
controls application
of all power to the
card reader.
When indicator is
off, depressing switch
applies power to
reader and causes
associated indicator to light.
When indicator is
lit, depressing
switch removes all
power from reader and
causes indicator to
go out.

READ

CHECK
indicator

(

white light

When lit, this light
indicates that the
card just read may be
torn on the leading or
trailing edges, or
that the card may
have punches in
column positions 0
or 81.
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.

8-5

Recovery
Card may have been
read incorrectly;
restore power if
possible by depressing the POWER
switch; insert the
card again as the
first card in the
input hopper, and
press the RESET
switch; in some
cases, it may be
necessary to
restart the program.

Card .was read incorrectly; duplicate if
necessary, insert
the card again as
the first card in the
input hopper and
press the RESET
switch.

CHAPTER 8.

CARD READER DRIVER

(

Table 8~3 (Cont.)
Card Reader Switches and Indicators
Indicator

Description

PICK
CHECK
indicator

white light

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

Recovery
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.
STACK
CHECK
indicator

white light

When lit, this light
indicates that the
previous card was not
properly seated in
the output stacker
and therefore may be
badly mutilated.
stops card reader
operation and extinguishes RESET
indicator.

HOPPER
CHECK
indicator

white light

When lit, this light
indicates that either
the input hopper is
empty or that the output stacker is full.

8-(i

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 car~ in
the input hopper and
press the RESET
switch.
Card may have been
read incorrectly;
empty the stacker or
fill the hopper; insert the card again
as the first card in
the input hopper and
press the RESET
switch.

CHAPTER 8.

CARD READER DRIVER
Table 8-3 (Cont.)
Card Reader Switches and Indicators

Indicator

Description

STOP
switch

momentary
pushbutton/
indicator
switch
(red light)

Action
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
Greleased, 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 s~li tch is depressed or whenever
an error indicator
lights (READ CHECK,
PICK CHECK, STACK
CHECK, or HOPPER
CHECK).

(

8.4.2

Ready and Card Reader Check Recovery

If any of the following conditions occurs:
POWER failure
reset switch not pressed (reader offline)

8-7

CHAPTER 8.

CARD READER DRIVER

the driver determines that the card reader is not ready,
following message is output on the operator's console:

and

the

and

the

*** CRn: -- NOT READY
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:

*** 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 15 seconds 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 8.4.1.

8.4.3

I/O Status Condition

The error and status conditions listed in Table 8-4
the card reader driver described in this chapter.

are

returned

CHAPTER 8.

CARD READER DRIVER
Table 8-4
Card Reader status Returns

Code
IS.SUC

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 canceled
progress or while still in the I/O queue.

IE.DM

while

(
IE. DNA

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

IE.EOF

(

End-of-file encountered

An end-of-file control card was recognized.
IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for card readers.

IE.NOD

Buffer allocation failure
Dynamic storage space has been depleted, and there was
insufficient buffer space available to allocate a card
buffer (i.e., cards are read into a driver baffer
translated and then moved to the user buffer).

8-1

CHAPTER 8.

CARD READER DRIVER
Table 8-4 (Cont.)
Card Reader Status Returns

Code

Reason

IE.OFL

IE.SPC

Illegal address space
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.

8.5

FUNCTIONAL CAPABILITIES

The card reader driver can perform ~1e 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
interprets 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.RDB, the driver interprets all data,
including 026 and 029 control characters, as binary.

8.5.1

Control Characters

Table 8-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 bytp-s in
alphanumeric mode.
In binary mode the only control card recognized is
binary EOF.

CHAPTER 8.

CARD READER DRIVER
Table 8-5
Card Reader Control Characters

Punches
12-11-0-1-6-7-8-9
12-11-0-1-6-7-8-9

Co1wnns

Meaning

End-of-file (alphanumeric)

(all 8 punches in
End-of-file (binary)
the first 8 columns)

12-2-4-8

026-coded cards follow

12-0-2-4-6-8

029-coded cards follow

DEC026 is the default translation mode
when
the
system
is
bootstrapped. This mode remains in effect until explicitly changed by
a control card indicating that DEC029 cards will follow.
After
encountering a DEC029 control card, the driver translates all cards in
DEC029 format unless another DEC026 control card is encountered. This
card
overrides
the 029 mode specification and indicates that
subsequent cards are to be translated in 026 format.
Control
characters are addressed to the card reader itself, and remain in
effect even when the reader is attached and subsequently detached.

(

8.6

CARD READER DATA FORMATS

The card reader reads data in either alphanumeric or binary format.

8.6.1

Alphanumeric Format (026 and 029)

Table 8-6 summarizes the translation from DEC026 or DEC029 card
to ASCII.

(

-:>-1.1

codes

CHAPTER 8.

CARD READER DRIVER
Table 8-6
Translation from DEC026 or DEC029 to ASCII

Character
[
]

SPACE
1
n

#
$
%

AND

•

(
)

•
/

1
2
3
4
5
6
7
8
9
;

<
=
>
8.6.2

NonParity
ASCII

DEC029

DEC026

Character

173
175
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075
. 076

12 0
11 0
none
12 8 7
8 7
8 3
11 8 3
084
12
8 5
12 8 5
11 8 5
11 8 4
12 8 6
o8 ~
11
12 8 3
o1
0
1
2
3
4
5
6
7
8
9
8 2
11 8 6
12 8 4
8 6
086

12 0
11 0
none
12 8 7
085
086
11 8 3
087
11 8 7
8 6
08 4
12 8 4
11 8 4
12
083
11
12 8 3
o1
0
1
2
3
4
5
6
7
8
9
11 8 2
082
12 8 6
8 3
11 8 6

?
@

A
B

C
D
E
F
G

I
J
K
L

M
N
0

P
Q

R
S
T
U
V
W

X
y
Z
[

]

or -

NonParity
ASCII

DEC029

DEC026

077
100
101
102
103
104
105
106
107
110
111
112
113
114
115
116
117
120
121
122
123
124
125
126
127
130
1·31
132
133
134
135
136
137

087
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
11 4
11 5
11 6
11 7
11 8
11 9
o2
o3
o4
o5
o6
o7
o8
o9
12 8 2
082
11 8 2
11 8 7
085

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
11 4
11 5
11 6
11 7
11 8
11 9
o2
o3
o4
o5
o6
o7
o8
o9
11 8 5
8 7
12 8 5
8 5
8 2

Binary Format

In ~X-11M 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.

8-J?

CHAPTER 8.
8.7

CARD READER DRIVER

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the card reader driver described
in this chapter. Section 8.4 contains information on operational
error-recovery procedures which might be important from a programming
point of view.

8.7.1

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 ~o be read.

8.7.2

Aborting a Task

If a task which is waiting for the card reader to be readied is
aborted, the card reader driver recognizes this fact within one
second. It is not necessary to ready the reader before aborting the
task, as is the case for DECtape.

(

?'-13

CHAPTER 9
MESSAGE-ORIENTED
COMMUNICATION DRIVERS

9.1

INTRODUCTION

RSX-llM supports a variety of communication
line
interfacessynchronous
and
asynchronous,
single-line
and
multiplexers,
character-oriented and message-oriented. These are used for terminal
communications,
remote job entry, multicomputer interfaces, and
laboratory and industrial control communications. communications line
interfaces can be roughly divided into two categories:
Terminal (character-oriented) communications devices
Multicomputer (message-oriented) communications devices
Chapter 2 describes the character-oriented asynchronous communications
line interfaces used primarily for terminal communications. The
PDP-ll PERIPHERALS 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, DJ11,
DLll-A, DLll-B, DLll-C, and DLll-D interfaces. These are asynchronous
multiplexers and single-line interfaces which are
used
almost
exclusively for t.erminal communications. Transfers on all of these
interfaces are performed one character at a time.
None of the
interfaces in this category have drivers of their 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 9-1.

9-1

CHAPTER 9.

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 9-1
Message-Oriented Communication Interfaces

Model

Type

Function

DLll-E

Asynchronous

Single-line interface

DPll

Synchronous

Single-line interface

DUll

Synchronous

Single-line interface

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 DLll-E, DPll, and DUll
allow I/O requests to be queued directly for them. These devices have
drivers of their own and can be accessed by means of the logical
device names listed in Table 1-1.
These names can be used in
assigning LUNs via the ASSIGN LUNsystem directive, at task build or
via the REASSIGN MCR command.
The following subsections briefly
discuss the message-oriented interfaces supported for RSX-llM.

9.1.1

DLll-E Asynchronous Line Interface

The DLll-E is an asynchronous, serial-bit, single-line interface.
It
is a block-transfer device used for remote terminal and multicomputer
communications. Baud rates are selectable between 50 and 9600, and
full data set control is supported. A single PDP-II can support as
many as 16 DLll-E interfaces.

9.1.2

DPll Synchronous Line Interface

The DPll provides a program interrupt interface between a PDP-II and a
serial synchronous line.
This interface facilitates the use of the
PDP-II 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. A single PDP-II
can support up to 16 DPll interfaces.

9-2

CHAPTER 9.

MESSAGE-ORIENTED COMMUNICATION DRIVERS

DUll Synchronous Line Interface

9.1.3

The DUll synchronous line interface is' a single-line communications
device which provides a program-controlled interface between the
PDP-1l 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 DP11.
A single PDP-11 can support as many as 16 DUll interfaces.
9.2

GET LUN INFORMATION MACRO

Word 2 of the buffer filled by the GET LUN INFORMATION system
directive (the first characteristics word) contains the following
information for 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

Directory device

Single-directory device

Sequential device

6-12

Reserved

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
DPl1 and the DUll interfaces. Byte 0 of word 5 contains the number of
sync characters to be transmitted before a synching message (e.g.,
after line turn around in half duplex operation), and byte 1 is used
as a sync counter.

9-3

CHAPTER 9.
9.3

MESSAGE-ORIENTED COMMUNICATION DRIVERS

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.

9.3.1

Standard QIO Functions

Table 9-2 lists the standard functions of the QIO macro that are valid
for the communication devices.
Table 9-2
Standard QIO Functions for Communication

Interfaces

Function

Format
QIO$C IO.ATT, •••

Not applicable (NOP)

QIO$C IO.DET, •••

Not applicable (NOP)

QIO$C IO.KIL, •••

Not applicable (NOP)

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

Read logical block (stripping sync)

QIO$C IO.WLB, ••• ,<stadd,size)

Write logical block (preceded by
syncs)

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

9-4

than

(

CHAPTER 9.
9.3.2

MESSAGE-ORIENTED COMMUNICATION DRIVERS

Device-Specific OIO Functions

The specific functions of the OIO macro that are
communication line interfaces are shown in Table 9-3.

valid

for

the

Table 9-3
Device-Specific OIO Functions for Communication Interfaces
Format

Function

OIO$C IO.HDX, •••

Set device to half-duplex mode

QIO$C IO.INL, •••

Initialize device
characteristics

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

Read
logical
block,
without
characters
stripping
sync
(transparent mode)

QIO$C IO.SYN, ••• ,<syn>

Specify sync character

OIO$C IO.TRM, •••

Terminate
communication,
disconnecting from physical channel

OIO$C IO.WNS, ••• ,<stadd,size>

Write
logical
block
without
preceding
sync
characters
(transparent mode)

where:

and

set

device

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.

The device-specific functions listed in Table
greater detail below.

9-3

are

described

than

9.3.2.1 IO.HDX - The lO.HDX OlO function is used to set the mode on a
DLll-E, OPll, or DUll 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.

9-5

CHAPTER 9.

MESSAGE-ORIENTED COMMUNICATION DRIVERS

9.3.2.2 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 it is a dial-up interface, it also hangs up the line.

9.3.2.3 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 syre cLaracters 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:
S
1

I S I H I H I H I H I cs I cs
2

where:

DATA

I cs

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
later character which happens to have the same binary value as a sync
character to be read without stripping. IO.RLB is used to read a
logical block with leading sync characters stripped; IO.RNS is used
to
read
the block without stripping leading sync characters.
Generally, IO.RLB should be used.

9.3.2.4 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 to
set the characteristics of the physical device unit.

9.3.2.5 IO.WNS - This QIO function causes a logical block to be
written with no preceding sync characters. To ensure that the two
systems involved in a communication are synchronized, two or more sync
characters are transmitted by one system and received by the other
before any other message can be sent. IO.WLB is used to write a block
of data, preceded by sync characters; IO.WNS is used to perform a
block transfer without sending sync characters first.
Generally,
IO.WLB should be used.

9-6

CHAPTER 9.
9.4

MESSAGE-ORIENTED COMMUNICATION DRIVERS

STATUS RETURNS

The error and status conditions listed in Table 9-4 are
the communication drivers described in this chapter.

returned

Table 9-4
Communication status Returns
Code
IS.SUC

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

Device not ready
The physical device unit specified in the QIO directive
was not ready to perform the desired I/O operation.
This code is returned to indicate one of the following
conditions:
• The physical device unit could not be initialized
(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 receiving 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.

9-7

CHAPTER 9.

MESSAGE-ORIENTED COMMUNICATION DRIVERS
Table 9-4 (Cont.)
Communication Status Returns

Code

Reason

IE.IFC

Illegal function
A function code was specified in an I/O request that is
illegal for message-oriented communication devices.

IE.OFL

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.

9.5

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the message-oriented communication
interfaces described in this chapter.

9.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 thqt any message which is
clocked out on the line (without line or device outage) has been
successfully transmitted. As soon as the receiver is able to satisfy
a read request, it returns a successful status code (IS.SUC) in the
I/O status block. Of course, 'Only the task which receives the message
can determine whether 'Or net the message has actually been transmitted
accurately.
The receiving device sheuld be ready te receive
request) at the time the transmission is sent.

9-8

data

(with

read

(
\

CHAPTER 9.
9.5.2

MESSAGE-ORIENTED COMMm~ICATION DRIVERS

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 (CRe). A CRC can be computed in software or
with a hardware device, such as the KG-ll communications arithmetic
option.

9.5.3

Half-Duplex Considerations

Only half-duplex mode is
supported
for
the
message-oriented
communication interfaces described in this chapter. A unit must be
explicitly declared half-duplex by setting the mode with an IO.HDX QIO
function.
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.

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

(

9.5.5

Vertical Parity Support

Vertical parity is not supported by the DLll-E, DPll, and DUll.
are assumed to be eight-bit only.

9-9

Codes

CHAPTER 9.
9.5.6

MESSAGE-ORIENTED COMMUNICATION DRIVERS

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.

9.6

PROGRAMMING EXAMPLE

The following example illustrates the initialization,
device
parameters, and transmission of a block of
me~sage-oriented communication device •
• MCALL

ALUN$S,QIO$S

.•

ALUN$S
QIO$S
QIO$S
QIO$S

TXAST:

CMPB
BEQ

setting of
data on a

#l,#"XP,#O
#IO.HDXIIO.SYN,#1"",<#226)
#IO.INL,#l

USE LUNl FOR DPll
SET DEVICE PARAMETERS
; PUT DEVICE ON LINE
#IO.WI~,#l",#TXSTS,#TXAST,<#TXBUF,#lOO); SEND A BLOCK

WAS DATA CLOCKED OUT
SUCCESSFULLY?
IF SO, SET UP FOR NEXT
; BLOCK

#IS.SUC&377,@(SP)+

10$

9-10

CHAPTER 10
ANALOG-To-DIGITAL CONVERTER DRIVERS

10.1

INTRODUCTION

The AFCll and ADOl-D analog-to-digital (A/D) converters are used for
the acquisition of industrial and laboratory analog data. Although
each has its own driver, programming for both is quite similar and
both are multichannel, programmable gain devices. The AD01-D should
not be confused with the ADU01, a UDC module, which is described in
Chapter 11. Table 10-1 compares the AFCll and the AD01-D briefly, and
subsequent sections describe these devices in greater detail.
Table 10-1
Standard Analog-to-Digital Converters
AFCll

(

AD01-D

Maximum sampling rate (points
per second)

200 (20 per single)
channel

Approximately
10,000

Number of bi ts

13 or 14

10 or 11

Maximum number of analog channels
that can be multiplexed

1024

10.1.1

AFCll Analog-to-Digital Converter

. The AFCll is a differential analog input subsystem for industrial
data-acquisition and control systems. It multiplexes signals, selects
gain, and performs a 13- or l4-bit analog-to-digital conversion under
program control.
With the use of appropriate signal-conditioning
modules, the system can in termix . :.nd accept low-level, high-level, and
current inputs, with a high degree of noise immunity.

10-1

CHAPTER 10.
10.1.2

ANALOG-TO-DIGITAL CONVERTER DRIVERS

AD01-D Analog-to-Digital Converter

The AD01-D is an extremely fast analog data-acquisition system.
It
multiplexes signals, selects gain, and performs a 10- or ll-bit
analog-to-digital conversion und(!r program control.
The AD01-D is
normally unipolar, but an optional sign-bit facilitates bipolar
operation.

10.2

GET LUN INFORMATION MACRO

If a GET LUN INFOru1ATION 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 analog-to-digital converters.

10.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
analog-to-digital converters.

10.3.1

Standard QIO Function

The standard function that is valid for
is shown in Table 10-2.

analog-to-digital

converters

(
\

Table 10-2
Standard QIO Function for the A/D Converters
Format
QIO$C IO.KIL, •••

Function

(

Cancel I/O requests

Since all requests are processed with a small amount of time, no in
progress request is ever canceled. This function simply cancels all
queued requests.

10.3.2

Device-Specific OIO Function

The device-specific function of the QIO macro that
analog-to-digital converters is shown in Table 10-3.

10-2

valid

for

CHAPTER 10.

ANALOG-To-DIGITAL CONVERTER DRIVERS

Table 10-3
Device-Specific QIO Function for the AID Converters
Format

Function

QIO$C IO.RBC, ••• ,<stadd,size,stcnta)

where:

Initiate multiple AID
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
greater than zero); the data buffer i~ 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 10-4.
Table 10-4

AID Conversion Control Word

(

Bits

Meaning

0-11

Channel number

Range:

12-15

Gain value for this
sample, expressed as
a bit pattern as
follows

Gain:

0
0
0
0
0
0

0
0
0
0
1
1
1
1

0
0
1
1
0

0
1

0
1
1
1
1
1
1
1
1

a
0

1
1
1
1

ADOl-D

AFCll

1
1
0
0

1
1
0
0
1
1

1
0
1
0

1
0

0-1023

1
2
illegal
illegal
10
20
illegal
illegal
50
100
illegal
illegal
200
1000
illegal
illegal

10-3

Range:
Gain:

1
2
4
8

illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal
illegal

0-63

CHAPTER 10.

ANALOG-To-DIGITAL CONVERTER DRIVERS
(

10.4

FORTRAN INTERFACE

A collection of FORTRAN-callable sUbroutines provide FORTRAN programs
access to the AFCll and the AD01-D. These are described in this
section. All are reentrant and may be placed in a resident library.

10.4.1

Synchronous and Asynchronous Process Control I/O

The ISA standard provides for synchronous and asynchronous I/O.
Synchronous I/O is indicated by appending a "w" to the name of the
subroutine (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.

10.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
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 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 the contents of isb varies, depending on the FORTRAN
call that has been executed, but Table 10-5 lists certain general
principles that apDly.
The section describing each
subroutine
provides further details.

(
\

10-4

CHAPTER 10.

ANALOG-TO-DIGITAL CONVERTER DRIVERS
Table 10-5
Contents of First Word of isb

Contents

Meaning

isb(l) = 0

Operation pending;

isb(l) = 1

Successful completion

isb(l) = 3

Interface subroutine unable to generate
QIO directive or number of samples is
zero

< isb(l) < 300

isb (1)

> 300

I/O in progress

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 suhroutines depend on asynchronous system traps to
set their status.
Thus, if the trap mechanism is disabled, proper
status cannot be set.

10.4.3

FORTRAN Subroutine Summary

Table 10-6 lists the FORTRAN in~erface subroutines supported
AFCll and ADOl-D under RSX-1IM.

for

the

Table 10-6
FORTRAN Interface Subroutines for the AFCll and AD01-D
Subroutine

Function

AIRD/AIRDW

Perform input of analog data
sequence

AISQ/AISQW

Read a series of sequential analog input
channels

ASADLN

Assign a LUN to ADO:

ASAFLN

Assign a LUN to APO:

10-5

random

CHAPTER 10.

ANALOG-TO-DIGITAL CONVERTER DRIVERS

The following subsections briefly describe the function and format of
each FORTRAN subroutine call. Note the use of ASADLN and ASAFLN to
assign a default logical unit number.

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

!1
AIRD
AIRDW

Random
data

(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 gain (bits 12-15), as shown in Table 10-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 10.4.2.
If
inm = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

10.4.5

AISQ/AISQW:

Reading Sequential Analog Input Channels

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of
sequential analog input channels. These calls are issued as follows:

CALI. . {AISQ
AISQW ~
where:

(inm,icont,idata, [isb], [lun])

inm

specifies the nwnber 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 10-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.
10-6

array

which

the

subroutine

CHAPTER 10.

ANALOG-To-DIGITAL CONVERTER DRIVERS

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 10.4.2.
If
inm = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

10.4.6

ASADLN:

Assigning a LUN to ADO:

The ASADLN FORTRAN subroutine assigns the specified LUN to ADO:
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] )
where:

lun

is the logical unit number to be assigned to ADO:
defined as the default unit.

and

isw

is an integer variable to which the result
ASSIGN LUN system directive is returned.

the

Only the LUN specified in the last call to ASADLN or ASAFLN is defined
as the default unit.

10.4.7

(

ASAFLN:

Assigning a LUN to AFO:

The ASAFLN FORTRAN subroutine assigns the specified LUN to AFO:
and
defines it as the default logical unit number to be used whHnever a
LUN specification is omitted from an AIP~(W)/AISQ(W) subroutine call.
It is issued as follows:
CALL ASAFLN (lun, [isw])

10-7

CHAPTER 10.
where:

ANALOG-To-DIGITAL CONVERTER DRIVERS

lun

is the logical unit number·to be assigned to AFO:
defined as the default unit.

and

isw

is an integer variable to which the status
ASSIGN LUN system directive is returned.

the

from

Only the LUN specified in the last call to ASAFLN or ASADLN is defined
as the default unit.

10. 5

STATUS RETURNS"

The error and status conditions listed in Table 10-7 are returned
the analog-to-digital converter drivers described in this chapter.

Table 10-7
A/D Converter Status Returns
Code
IS.SUC

IS.PND

I/O request pending
The operation specified in the QIO directive has not
yet been executed. The I/O status block iG 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 analog-to-digita1
converters,
this
code
indicates that a bad channel number or gain code P;IS
~ .•}ecified in the control buffer.

10-8

CHAPTER 10.

ANALOG-To-DIGITAL CONVERTER DRIVERS

(

Table 10-7 (Cont.)

AID Converted Status Returns
Code
IE.BYT

Reason
Byte-aligned buffer specified
Byte alignment was specified for a data or control
buffer,
but
only
word
alignment is legal for
analog-to-digital convertors. Alternately, the length
of the data and control buffer is not an even number of
bytes.

IE.DNR

Device not ready
The physical device unit specified in the QIO directive
was not ready to perform the desired I/O operation.
For the APell, this code is returned if an interrupt
timeout occurred or the power failed.
In th~ 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-digital convertors.

(

IE.OFL

IE.SPC

(

Illegal address space
The data or control buffer specified for a conversion
reqUt1st was partially or totally outside the address
space of the issuing task. Alternately, a byte count
of zero was specified.

FORTRAN interface
section 10.5.1.

values

for

these

10-9

subroutines

are

presented

CHAPTER 10.
10.5.1

ANALOG-To-DIGITAL CONVERTER DRIVERS

FORTRAN Interface Values

The values listed in Table 10-8 are
calls.

returned

FORTRAN

subroutine

Table 10-8
FORTRAN Interface Values
Status Return

FORTRAN Value

IS.SUC
IS.PND
IE.ABO
IE.ADP
IE.BAD
IE.BYT
IE.DAO
IE.DNR
IE.IEF
IR.IFC
IE.ILU
IE.NOD
IE.ONP
IR.PRI
IE.RSU
IR.SDP
IE.SPC
IE.ULN
IE.UPN

10.6

+01
+00
+315
+101
+301
+319
+313
+303
+100
+302
+99
+323
+305
+316
+317
+102
+306
+08
+04

FUNCTIONAL CAPABILITIES

The AFCll and ADOl-D operate only in multi-sample mode, because the
user can simulate single-sample mode by simply specifying one sample.
Multi-sample mode permits many channels to be sampled at approximately
the same time without requiring the user to queue multiple I/O
requests.
The maximum number of channels in the configuration is specified at
system-generation time. This value is stored in the respective AFCll
and ADOI-D unit control blocks.

11.6.1

Control and Data Buffers

The user must define two buffers of equal size, the control buffer and
the data buffer.
The former contains the control words needed to
perform one A/D conversion per channel specified. Each control word
indicates the channel to be sampled and the gain to be applied (see
Table 10-4).

10-10

CHAPTER 10.

ANALOG-To-DIGITAL CONVERTER DRIVERS

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.

10.7

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the analog-to-digita1 converter
drivers described in this chapter.

10.7.1

Use of AID Gain Ranges

Note that the AID gain ranges overlap. The key to successful use of
the AID converters is to change to a higher gain whenever a full-scale
reading is imminent and to change to a lower gain whenever the last
AID value recorded was less than half of full scale. This method
maintains maximum resolution while avoiding saturation.

10.7.2

Identical Channel Nlmilierg on the AFCll

When requesting sampling of more than one channel, the user should not
specify multiple sampling of a single channel without 10 or more
intervening samples on other channels. This ensures 50 milliseconds
between samples on a single channel. If sampling occurs more often
than this on a single channel, partial results are returned (see
10.7.3 below).

10.7.3

(

APCll Sampling Rate

Although the APCll can sample a maximum of 200 points per second, a
single channel can only be sampled at 20 points per second. Because
the channel capacitor needs 50 milliseconds to recharge after each
conversion, more frequent sampling may result in partial readings. If
this occurs, the user will receive no indication that information is
being lost.
To ensure that information is not lost on anyone
channel, the user should sample ap[>roximately ten other channels
before returning to the first one.

10.7.4

Restricting the Numhe.:r. of ADOI-D Conversions

Th~

'iD01-D is an extrelfLely fas·t device, provIding a 25-nlicroser:ond
cOI,version rate, .:'lnd is d1.·i V8n prograrnmab1y to minimize system
overhead. Hmvever, an excesHive number of conversions in a single
request essentially locks out the rest of tht:1 system because the
driver does not return con·trol to 1:he ~ystem until it has fini.shed all
the specified conversions. no othHr t.as~< ca,n. run, although interrupts
can still occur c?.nd are proc~~ss(?(l.

10-11

{

CHAPTER 11
UNIVERSAL DIGITAL CONTROLLER DRIVER

11.1

INTRODUCTION

The UDCll is a digital input/output system for industrial and process
control applications.
It interrogates and/or drives up to 252
directly addressable digital sense and/or control modules. The UDCII
operates under program control as a high-level digital -multiplexer,
interrogating digital inputs and driving digital outputs.

(

While performing analog-to-digital conversions, the UDCll driver can
handle other functions, such as contact or timer interrupts or
latching output. These functions are performed immediately, without
requiring any in progress analog-to-digital conversions to first be
completed.
Unlike other RSX-IlH I/O device drivers, the UDCll driver is neither a
multicontroller nor a multiunit driver.

11.1.1 Creating the UDCll Driver

(

Since different installations have different
configurations
of
modules, no preassembled driver. is supplied with the RSX-llM system.
Each installation must assemble the driver source module with a prefix
file that defines the particular hardware configuration.
The prefix file is. created at system generation according to the
user's response to questions relating to the UDCll. This file is
named RSXHC.MAC and includes symbolic definitions of the UDCll
configuration.
These definitions encode the relative module nuru)er
ancl, the number of modules for each generic type specified in the
system generation dia.log. The encoding has the following format:
number of modules
One or more of the following symbols is generated:

11-1

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER
Symbol

Module Type

U$$ADM
U$$AOM
U$$CIM
U$$CSM
U$$LTM
U$$SSM
U$$TIM

Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

Note that all modules of a given type must be
sequential slots.

11.1.2

installed

together

Accessing UDCll Modules

RSX-llM provides two methods of accessing the UDCll:
1.

A QIO macro call issued to the driver

Restricted direct access by any task to
dedicated to the UDCll

I/O

page

registers

The first method, access through the driver, is required to service
interrupting modules and to set and record the state of latching
digital output modules.
The second method, direct access, is a high-speed, low-overhead way to
service noninterrupting modules.
The following functions may be
performed:
• Analog output
• Contact sense input
• Single-shot digital output
• Read a contact interrupt module
• Read a timer module

11.1.2.1
modules:

Driver Services - The driver services the following types of

Contact interrupt

Timer (I/O counter)

Analog input

Latching digital output

11-2

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

Contact and timer interrupts need not be serviced by a single task.
One task may be connected to contact interrupts, and another to timer
interrupts. A nonprivileged task can connect to either or both of
these classes by providing a circular buffer to receive interrupt
information and an event flag to allow triggering of the task whenever
a buffer entry is made.

11.1.2.2 Direct Access - A global common block within the I/O page
provides restricted direct access to the UDCll device registers. In a
mapped system, the length of the block is set to prevent access to
other device registers. In an unmapped system, the use of the common
block is optional. Section 11.4 explains direct access more fully.

11.2

GET LUN INFORMATION 1-1ACRO

If a GET LUN INFORMATION system directive is issued for a LUN
associated with the UDCll, word 2 (the first characteristics word)
contains all zeros, words 3 and 4 are undefined, and word 5 is not
significant, since there is no concept of a default buffer size for
universal digital controllers.

11.3

QIO MACRO

This section summarizes standard and device-specific QIO functions for
the UDCll driver.
In issuing them, note the numbering conventions
described in 11.7.2.

11.3.1 Standard QIO Function

(

The standard function that is valid for the UDCll is
11-1.

shown

Table

Table 11-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 progress.

11-3

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

11.3.2 Device-Specific OIO Functions
Table 11-2 summarizes device-specific OIO functions that are supported
for the UDCll.
Table 11-2
Device-Specific OIO Functions for the UDCll
Format

Function

OIO$C IO.CCI, ••• ,<stadd,sizb,tevf)

Connect a buffer to contact
interrupts

OIO$C IO.CTI, ••• ,<stadd,sizb,tevf,arv)

Connect a buffer to timer
interrupts

QIO$C IO.DCI,...

Disconnect a buffer from
contact interrupts

QIO$C IO.DTI,...

Disconnect a buffer from timer
interrupts

QIO$C IO.ITI, ••• ,<ron,ic)

Initialize a timer

QIO$C IO.MLO, ••• ,<opn,pp,dp)

Open or close latching digital
output points

OIO$C IO.RBC, ••• ,<stadd,size,stcnta)

Initiate multiple A/D
conversions

where:

stadd

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

sizh

is the data buffer size in bytes (must be even pnd
large enough to include a 2-word buffer header plus one
data entry; the buffer may cross a 4K boundary).

tevf

is the trigger event flag number (in
64) •

range

arv

is the starting address of the table
values (must be on a word boundary).

ron

is the module number.

is the initial count.

opn

is the first latching digital output point number,
which must be on a module boundary (evenly divisible by
16).

is the 16-bit mask.

11-4

through

initial/reset

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

is the data pattern.

size

is the control buffer size i~ bytes (must be even and
greater 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 11-3.
The following sections describe the functions listed in Table 11-2.
Table 11-3

AID Conversion Control Word

(

ADUOI

Bits

Meaning

0-11

Channel number

Range:

12-15

Gain value for this
sample, expressed as
a bit pattern as
follows

Gain:

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

1
2

illegal
illegal
10
20
illegal
illegal
50
100
illegal
illegal
200
1000
illegal
illegal

11.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:
driver index
1
2

user index

entry

11-5

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

Whenever a change of state occurs in one or more contact points an
interrupt is generated.
The UDCll driver gains control, determines
whether the change of state is of interest (i.e., a contact closure
and point closing (PCL) is set on the module), and then optionally
makes an entry in the data area of the buffer, updates the index words
and-sets the trigger event flag of the connected task.
Each entry consists of five words in the following format:
Word

Contents

Entry existence indicator

Change of state (COS) indicator

Module data (current point values)

Module number (interrupting module)

Generic code (interrupting module)

The driver enters data in the location currently indicated by the
driver index. This pointer can be considered as a FORTRAN index into
the buffer, i.e., the first location of the buffer is associated with
the index 1.
The beginning of the data area is the location of the
first ent~l (index 3).
Entries are made in a circular fashion,
starting at the beginning of the data area, filling in order of
increasing memory address to the end of the data area, and then
wrapping around from the end to the beginning of the data area. If,
near the end of the data area, only part of the entry (e.g., the first
two words) can fit, the remainder (the other three) is placed at the
beginning of the data area.
It is expected that the connected task will maintain its own pointer
(the user index) to the location in the buffer where it is next to
retrieve contact interrupt data. When a task is triggered by the
driver, it should process data in the buffer starting at the location
indicated by its pointer and continuing in a circular fashion until
the two pointers are equal or a zero entry existence indicator is
encountered. Equality of pointers means that the connected task has
retrieved all the contact interrupt information that the driver has
entered into the buffer.
The entry existence indicator is set 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
are discarded and a count of data overruns is incremented. The
nonzero entry existence indicator also serves as an overrun indicator.
A positive value
(+1)
indicates no overruns between entries; a
negative value is the two's complement of the number of times data
have been discarded between entries.

11-6

(
\,

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

The module number indicates a module on which a change of state in the
direction of interest has been recognized for one or more discrete
points. The direction of the change may be from 0 to 1 or 1 to 0,
depending on the PCL (point closing) and POP (point opening) module
jumpers. The change of state (COS) indicator specifies which point or
points of the module have changed state.
The bit position of an on-bit in the COS indicator provides the
low-order bits (3-0) of a point number and the module number provides
the high order bits (15-4). The module data indicates the logical
value (polarity) of each point in the module at the time of the
interrupt.
Contact interrupt data can be reported to only one task.
The
functions IO.CCI and IO.DCI in Table 11-2 are provided to enable a
task to connect and disconnect from contact interrupts.
If the
connection is successful, the second word of the I/O status block
contains the number of words passed per interrupt in the low-order
byte and the initial FORTRAN index to the beginning of the data area
in the high-order byte.

11.3.2.2 Timer (W734 I/O Counter Modules) - A timer (I/O counter)
module is a clock that is initialized (loaded), counts up or down, and
then causes an interrupt. The UDCll driver treats such modules in a
way similar to that in which it handles contact interrupts. The
requester provides a circular buffer similar to that for contact
interrupts.
Each entry consists of four words in the following
format:
Contents

Word

(

Entry existence indicator

Module data (current value)

Module number (interrupting module)

Generic code (interrupting module)

The IO.CTI function in Table 11-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 is used to load the first module, and so forth. .If a timer has a
nonzero value when it interrupts, it is not reloaded, so that
self-clocking modules and modules that interrupt on half count can
continue counting from the initial value.
The IO.DTI function in Table
interrupts, and the IO.ITI
initialize a single timer.

11-2 disconnects a task from timer
function provides the capability to

11-7

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

11.3.2.3 Latching
Digital
Output
(M68S,
M803,
and
M80S
Modules) - Each mOdule has 16 latching digital output points. The
IO.MLO function in Table 11-2 opens or closes a set of up to 16
points.
Bit n of the mask and data pattern corresponds to the point
opn + n. -If a bit in the mask is set, the corresponding point is
opened or closed, depending on whether the corresponding bit in the
data pattern is clear or set. If a bit in the mask is clear, the
corresponding point remains unaltered.

11.3.2.4 Analog-to-Digital Converter (ADUOI Module) - Each
ADUOI
module has eight analog input channels. The IO.RBC function in Table
11-2 initiates AID conversions on multiple ADUOI input channels.
Restrictions on maximum sampling rates are the same as defined for the
AFCll in Chapter 10.

11.4

DIRECT ACCESS

Section 11.1.2 describes UDell functions that may be performed by
referencing a module through its physical address in the I/O page.
Under RSX-llt-t such access is accomplished by one.. of the following
methods:
1.

A privileged task or any task running in an unmapped system
has unrestricted access to the I/O page and may therefore
access each module by absolute address.

Using the Task Builder, a task may link to a global common
area whose physical address limits span a set of locations in
the I/O page. This method applies to either a mapped or
unmapped system.

The latter method allows a task to be transported. to any other system
simply
by relinking.
Further, in a mapped system the memory
management hardware will abort all references to device registers
outside the physical address limits of the common block.
The operations required to
follows:
1.

imple~ent

each method may be summarized

Unrestricted access to the I/O page
a.

An object module

The object module is included in the system library file.

A task is created containing the appropriate global
references.
Such references are resolved when the task
builder automatically searches the system library file.

is created which defines the UDCll
configuration through a list of absolute global addresses
and addressing limits for each module type.

11-8

(

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

Steps a and b are executed once. Step c is performed each time a task
is created that references the UDCll.
2.

Access to the I/O page through a Global Common Block:
a.

An object module

is created which defines the UDCll
configuration
through a list of relocatable global
addresses and addressing limits for each module type.

The object module is linked, using the Task Builder,
create an image of the Global Common block on disk.

The INSTALL HCR command is used to make the Global Common
Block resident in memory.

A task is created containing the appropriate global
references.
Such references are resolved by directing
the Task Builder to link the Task to the common block.

The following paragraphs describe each step in detail.

11.4.1

Defining the UDCll Configuration

The source module UDCOM.MAC*, when assembled with the proper prefix
file, provides global definitions for the following parameters:
The starting address of each module type.
The highest point number within a given module type.
The highest module number within a given module type.
The last two parameters are absolute quantities that may be used to
prevent a task from referencing a module that is non-existent or out
of limits.

(

By means of conditional assembly the list of addresses may be created
as absolute symbols defining locations in the I/O page or as symbols
within a relocatable program section to be used when building and
linking to the UDCll Global Common area.

11.4.1.1 .;..;N.=s-=s,,:,,:e:-mb-::-:l~Y-=--P.....r..;...o_c..;...e-=-d-:-u=r_e--:-f-:-o_r_...;U__D_C;...O...;M_.;:;...MA~C_ - UDCOM. MAC is assembled
with the RSX-llM configuration parameters contained in the file
RSXL\1C • MAC •

To create relocatable module addresses either the parameter 'U$$DCM'
or 'M$$MGE' must be defined. 'M$$l>1GE' will be included in RSXMC.MAC
* This module resides on the RKOS cartridge
of
the
RSX-llM
distribution bit labeled SOURCE MASTER. 'It is under UIC [11,10].

11-9

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

if memory management was specified when the system was generated.
If
not,
the user should edit the file to include the following
definition:
U$$DCM=O
The file may then be assembled using the MCR command:
)MAC UDCOM,UDLST=[ll,lO]RSXMC,UDCOM
This command invokes the MACRO-II assembler which processes the input
files RSXMC.MAC and UDCOM.~1AC to create UDCOM.OBJ and UDLST.LST.
To create absolute module addresses, both of the above parameters must
be undefined. Edit RSXMC.MAC, if necessary, to remove definitions and
then invoke the MACRO-II assembler with the following MCR command:
)MAC UDCDF,UDLST=[ll,lO]RSXMC,UDCOM
In this sequence the files UDCDF.OBJ and UDLST.LST are created from
the specified source modules. UDCDF.OBJ contains the module addresses
in absolute form.

11.4.1.2

Symbols Defined by UDCOM.MAC - This
symbolic definitions created by UDCOM.~mC.

The following symbols define the absolute or
the first module of a given type:

section

relocatable

Symbol

Module Type

$.ADM
$.AOM
$.CIM
$.CSM
$.LTM
$.SSM
$.TIM

Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

11-10

lists

the

address

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

The addresses in relocatable form are defined
named 'UDCOM' having the attributes:
REL OVR I
GBL -

program

section

relocatable
overlaid
instruction
global scope

Note that these attributes correspond to those
common block within a Fortran program.
In either the absolute or relocatable case,
referenced by the corresponding symbolic
module index.

attached

named

individual modules are
address plus a relative

The following symbols define the highest digital point within a module
type:
Symbol

Module Type

P$.CIM
P$.CSM
p$ .LTlvl
P$.SSM

Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output

The highest point number is defined relative to the first point on the
first module of a specific type.
For example if two contact interrupt modules are installed, ~le symbol
'P$.CIM' will have an octal value of 37.
The following symbols define the highest module number within a
module type.

(

,symbol

Module Type

M$.ADM
M$.AOr4
M$.CIM
M$.CSM

Analog input
Analog output
Contact interrupt
Contact sense input
Latching digital output
Single-shot digital output
Timer (I/O counter)

f4$. LTr-t

M$.SSM
14$ .TIM

given

The highest module number is defined relative to the first module of a
given type.
Thus, based on the previous example, 11$.CD'I will have a
value of 1.

11-11

CHAPTER 11.
11.4.2

UNIVERSAL DIGITAL CONTROLLER DRIVER

Including UDCll Symbolic
MOdule Library

Definitions

the

System

Object

As described in 11.4, a task having unrestricted access to the I/O
page may reference a UDCll module by absolute address. The object
module UDCDF contains symbolic definitions of
absolute
module
addresses and may be included in the System Object Module Library:

SY:[l,l]SYSLIB.OLB
The Task Builder automatically searches this file to resolve any
undefined globals remaining after all input files have been processed.
The following example illustrates the procedure for including the file
'UDCDF.OBJ' in the library.
>SET /UIC= [1 ,1]
>LBR SYSLIB/IN=[200,200]UDCDF
The SET MCR command is issued to establish the current UlC as
[1,1].
Next, the RSXllM Librarian is invoked and instructed, through the use
of the /IN switch to include the object module UDCDF.OBJ in the file
SYSLIB.OLB.

11.4.3

Referencing the UDCll through a Global Common Block

The following sections define the procedure for creating a Global
Common block in the I/O PAGE, making the block resident in memory, and
creating a task which references UDCll modules within the block.
Examples are given for both mapped and unmapped systems.

11.4.3.1 Creating a Global Common Block - The following sequence
illustrates the use of the object file UDCOM.OBJ to create a disk
image of the global common area in a mapped system.
>SET /UIC=[l,l]
>TKB
_
TKB>UDCOM/MM,LP:,SY:UDCOM/PI/-HD=[200,200]UDCOM
TKB>/
ENTER OPTIONS:
TKB>STACK=O
TKB>/
In the above example, a current UIC of [1,1] is established and the
Task Builder is initiated. The initial input line to the Task Builder
specifies the following files:
A core image output file to be named UDCOJl1. TSK
A memory map output to the line pr.inter

11-12

(

CHAPTER 11.

(

UNIVERSAL DIGITAL CONTROLLER DRIVER

A symbol table file to be named UDCOM.STB
All files reside on SY: under UIC [1,1].
UDCOM.OBJ containing the UDCll address
values, constitutes the input.
The switches specified for the output
information to the Task Builder:

The single input file,
definitions as relocatable

files

convey

the

following

/MM

indicates that the core image of the common block
reside on a system with Memory Management.

/PI

indicates that the core image is position independent 1
that is the virtual address of the common block may
appear on any 4K boundary within a task's address
space.

/-HD

indicates that the core image will not contain a
header.
A header is only required for a core image
file that is to be installed and executed as a task.

will

A single line of option input must be entered to eliminate the default
memo~J allocation for the stack area.
The following sequence illustrates the corresponding procedure for
unmapped system:

)5ET /UIC= [1,1]
)TKB
TKB)UDC011/-MH,LP: ,SY:UDCOM/PI/-HD= [200,200] UDCOM
TKB)/
ENTER OPTIONS:
TKB)STACK=O
TKB)PAR=UDCOM:17l000:l000
TKB)/

(

Again the task builder is requested to produce a core image and symbol
table file under the UIC [1,1] and a map file on the line printer from
the input file UDCOM.OBJ.
The output file switches convey the
following information:

/-MM

indicates that the core image of the common block
reside on an unmapped system.

/PI

Indicates that the core image is position independent.
In an unmapped system the core image is fixed in the
same address space for all tasks: however, the global
symbols defined in the symbol table file retain the
relocatable attribute.

/-HD

indicates that a core image without a header is
created.

11-13

will

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

The PAR option specifies the base and length of the common area to
coincide with the standard UDCll addresses in the I/O page. All
references to the common block by tasks will be resolved within this
region.

11.4.3.2 Making the Cornmon Block Resident - The following SET command
creates a UDCII common block residing in the I/O page for a mapped
system:
)SET /MAIN=UDCOM:77l0:l0:DEV
The corresponding command in an unmapped system is:
)SET /MAIN=UDCOM:17l0:l0:DEV
The preceding sequence specifies the allocation of a common block in
the I/O page whose physical'address limits correspond to the UDCII
standard locations. Note that the address bounds and length are
defined in units of 32 words.

11.4.3.3 Linking a Task to the UDCll Common Block - A task may access
UDell modules by linking to the common block as follows:
TKB)TASK,LP:=TASK.OBJ
TKB)/
ENTER OPTIONS:
)TKB COMl-ION=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 relocating the Global symbol definitions contained in UDCOM.STB.
If
memory
management is present, the Executive will map the
appropriate physical locations into the tasks virtual addressing space
when the task is made active.

11.5

FORTRAN INTERFACE

A collection of FORTRM~-callable subroutines provide FORTRAN programs
access to the UDCll. 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 FORTR&~ program may use the global common feature described
in section 11.4 to reference UDCll modules directly in the I/O page,
as shown in the following example:

11-14

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

UDCll GLOBAL COMMON

C
CO~ll10N

/UDCOM/ ICSM(lO) ,IAO(lO)

READ CONTACT SENSE MODULE 1 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

11.5.1 Synchronous and Asynchronous Process Control I/O
The ISA standard provides for synchronous and asynchronous process
I/O.
Synchronous I/O is indicated by appending a "W" to the naJlle 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-llH.
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.

(

11.5.2

The isb Status Array

The ish (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:

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
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 the contents of isb varies, depending on the FORTRAN
call that has been executed, but Table 11-4 lists certain general
principles that apply. The section describing each subroutine gives
more details.

11-15

CHAPTER 11.

UNIVERSAL· DIGITAL CONTROLLER DRIVER
Table 11-4
Contents of First Word of isb

Contents
isb(l)

Meaning

Operation pending;

I/O in progress

isb(l) = 1

Successful completion

, ish (1) = 3

Interface
subroutine
unable
to
generate QIO directiv& or number of
points requested is zero

< 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 (1)

In some cases, the values or states of points being read,
latched are returned to isb word 2.

pulsed,

FORTRAN interface subroutines depend on asynchronous system traps to
set their status.
Thus, if the trap mechanism is disabled, proper
status cannot be set.
For direct access calls (indicated in Table 11-5 below), errors are
detected and returned by the FORTRAN interface subroutine itself,
rather than 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 RSX-llD. Errors of this type that may be
returned are:
ish (1) = 3
isb(l)

Number of points requested is
zero

= value of IE.MOD

Invalid UDCll module

11.5.3 FORTRAN Subroutine Summary

Table 11-5 lists the FORTRAN interface subroutines supported for the
UDell 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.

11-16

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 11-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
(D)

ASUDLN

Assign a LUN to UDO:

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

Read several l6-point contact sense

analog

data

sequential

random

analog

input

several

channels

receive
timer

fields

(D)

(
"

DOL/DOLW

I .. atch or unlatch several l6-point fields

DOM/DOMW

Pulse several l6-point fields (D)

RCIPT

Read the state of
interrupt point (D)

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

RSTI

Read a single timer module (D)

SCTI

Set a timer module to an initial value

single

contact

The following subsections briefly describe the function and format of
each FORTRAN subroutine call.
Note the use of &SUDLN to specify a
default logical unit number. Also consider the numbering conventions
described in 11.7.2.
The following FORTRAN functions do not perform
facilitate conversions between BCD and binary.

11-17

I/O

directly,

but

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

Convert four BCD digits to a binary number:
IBIN = KBCD2B(IBCD)
Convert a binary number to four BCD digits:
IBCD = KB2BCD(IBIN)

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

Random
data

AIRD
CALL

(inm,icont,idata,[isb],lun)
AIRDW

where:

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 11-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
1un is a required parameter
(

The ish array has the standard meaning defined in section 11.5.2.
If
inrn = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

11-18

(

CHAPTER 11.
11.5.5

UNIVERSAL DIGITAL CONTROLLER DRIVER

AISQ/AISQW:

Reading Sequential Analog Input Channels

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of
sequential analog input channels. These calls are issued as follows:
CALL

where:

AISQ }
{ AISQW

(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 gain (bits 12-15), as shown in Table 11-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
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 11.5.2.
If
inm = 0, then isb(l) = 3. The contents of idata are undefined if an
error occurs.

11.5.6

AO/AOW:

Performing Analog Output

The ISA standard AO/AOW FORTRAN subroutines initiate analog output
several channels. These calls are issued as follows:
(inm,icont,idata,[isb],[lun])

11-19

CHAPTER 11.
where:

UNIVERSAL DIGITAL CONTROLLER DRIVER

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 11.5.2

11.5.7

ASUDLN:

Assigning a LUN to UDO:

The ASUDLN FORTRAN subroutine assigns the specified LUN to UDO:
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])
where:

11.5.8

lun

is the logical unit number to be assigned to UDO:
defined as the default unit.

and

isw

is an integer variable to which the result
ASSIGN LUN system directive is returned.

the

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

11-20

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

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

(

array

that

is an integer
interrupt data.

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

contact

ibuf

words,

receive
with

which

the

minimum

subroutine

The isb array has the standard meaning defined in section 11.5.2.
11.5.9

CTTI:

Connecting to Timer Interrupts

The CTTI FORTRAN subroutine connects a task to timer interrupts and
specifies a circular buffer to receive timer interrupt data. The
length of this buffer can be computea 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
follows:
isz = (8 + 4 * n)
where n is the number of entries in the buffer and isz is expressed in
words.

11-21

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER 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 11.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-l.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

words,

which

with

the

interrupt
a

minimum

subroutine

The isb array has the standard meaning defined in section 11.5.2.

11.5.10

DFDI:

Disconnecting from Contact Interrupts

The DFDI FORTRAN subroutine disconnects
interrupts. It is issued as follows:

task

from

contact

CALL DFDI ([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 11.5.2.

11-22

CHAPTER 11.
11.5.11

UNIVERSAL DIGITAL CONTROLLER DRIVER

OFTI:

Disconnecting from Timer Interrupts

The OFTI FORTRAN subroutine disconnects a task from timer
It is issued as follows:

interrupts.

CALL DFTI ([isb],[lun])
where:

isb

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

which

the

subroutine

The isb array has the standard meaning defined in section 11.5.2

11.5.12

DI/DIW:

Reading Several Contact Sense Fields

The ISA standard DI/OIW FORTRAN subroutines read several
contact sense fields. These calls are issued as follows:

l6-point

(inm,icont,idata,isb, [lun])

where:

(

inrn

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 (ignored if present).

array

which

the

subroutine

The isb array has the standard meaning defined in section 11.5.2.

11-23

data,

CHAPTER 11.
11.5.13

UNIVERSAL DIGITAL CONTROLLER DRIVER

DOL/DOLW:

Latching or Unlatching Several Fields

The ISA standard DOL/DOLW FORTRAN subroutines latch or unlatch one
more l6-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.

array

1un

is the logical unit number.

fields

which

the

latched

subroutine

(

The isb array has the standard meaning defined in section 11.5.2.

11.5.14

DOM/DOMW:

Pulsing Several Fields

The ISA standard DOM/DOMW FORTRAN subroutines pulse several l6-bit
fields
(one-shot digital output points). These calls are issued as
follows:
CALL

f DOM }
~

(inm,icont,idata,[idx],[isb],[lun])

DO!vlW

11-24

(
I
\

CHAPTER 11.
where:

UNIVERSAL DIGITAL CONTROLLER DRIVER

inm

specifies the number of fields to be pulsed.

icont

is an integer array containing the initial point number
of each l6-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 ISA standard FORTRAN process control calls.

isb

is a 2-word

lun

is the logical unit number (ignored if present).

integer
status is returned.

array

which

the

subroutine

The isb array has the standard meaning defined in section 11.5.2.

11.5.15

RCIPT:

Reading a Contact Interrupt Point

The RCIPT FORTRAN subroutine reads the state
interrupt point. It is issued as follows:

single

contact

CALL RCIPT (ipt,isb, [lun])
where:

(

ipt

is the number of the point to be read;
points are
numbered sequentially from 0, 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:
Meaning

Setting
• FALSE.

(0)

Point is open

.TRUE.

(-1)

Point is closed

11-25

11.5.2.
values,

CHAPTER 11.
11.5.16

UNIVERSAL DIGITAL CONTROLLER DRIVER

RDDI:

Reading Contact Interrupt Data From a Circular Buffer

The RDDI FORTRAN subroutine reads contact interrupt data from a
circular buffer that was specified in a CTDI call (see 11.5.8 above).
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 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
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 overrlID 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 RDDI call is issued as follows:
CALL RDDI (ipt,ival,[ict])
where:

ipt

is a variable to which the digital input
is returned; it may be set as follows:

point

ipt < 0 if no valid entry is found
interrupt data currently in buffer)

(i.e.,

ipt .~ 0 if the value indicated is a point
the state is returned to ival
ival

is a variable to which the state of
returned; it may be set as follows:
• FALSE. (0) if the point is open
.TRUE. (-1) if the point is closed

11-26

the

number

number;

point

CHAPTER 11.

11.5.17

UNIVERSAL DIGITAL CONTROLLER DRIVER

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.

ROTI:

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 11.5.9 above). 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 11.5.19).
The RDTI call is issued as follows:
CALL RDTI (imod,itm,[ivvn])
where:

imod

is a variable to which the module number
it may be set as follows:

• imod < 0 if no valid entry is found
interrupt data currently in buffer)
• imod > 0 if the
module nwnber;
returned in itm

(i.e.,

entry is valid, indicating a
the value of the timer module is

itm

is a variable to which the timer value is returned.

ivvn

is a variable to which the overrun count may be
returned;
a nonzero positive count indicates that the
driver was unable to store the nlmIDer of values
indicated.

RSTI:

Reading a Timer Module

(
11.5.18

returned;

The RSTI FORTRAN subroutine reads a single timer module.
as follows:
CALL RSTI (imod,isb,[lun])

11-27

It is issued

CHAPTER 11.
where:

UNIVERSAL DIGITAL CONTROLLER DRIVER

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

11.5.19

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.

ivaI

is the initial timer value.

isb

is a 2-word integer
status is returned.

lun

is the logical unit number.

array

which

the

subroutine

The isb array has the standard meaning defined in section 11.5.2.

11.6

STATUS RETURNS

Table 11-6 lists the error and status conditions that are returned
the UDCll driver described in this chapter:

11-28

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 11-6
UDCll Status Returns

Code
IS.SUC

Reason
Sucessful completion
The operation specified in the 010 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 010 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 010 parameters (words 6-11).
For the UDCll, this code indicates an illegal channel
number or gain code for the ADU01.
IE.BYT

Byte-aligned buffer specified
Byte alignment was specified for a buffer but only word
alignment is legal for the UDCll. Alternately, the
length of a buffer was not an even number of bytes.

IE.CON

Connect error
The task attempted to connect to contact or timer
interrupts, but the interrupt was already connected to
another task. Only one task can be connected to a
timer or contact interrupt. Alternately a task which
was not connected attempted to disconnect from contact
or timer interrupts.

(

IE.DNR

Device not ready
The physical device unit specified in the 010 directive
was not ready to perform the desired I/O operation.
For the ADU01, this code is returned if an interrupt
timeout occurred or the power failed.

11-29

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER
Table 11-6 (Cont.)
UDCll Status Returns

Code
IE.IEF

Reason
Invalid event flag number
The trigger event flag number specified
function was not in the range 1 to 64.

IE.IFC

connect

Illegal function
A function code was included in an I/O request that is
illegal for the UDCll. 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

IE .PRI

Privilege violation
The task which issued the request was not privileged to
execute
that request.
For the UDCll, this code
indicates that a checkpointable task attempted to
connect to timer or contact interrupts.

IE.SPC

Illegal address space
The specified control, data, or interrupt buffer was
partially or totally outside the address space of the
issuing task. Alternately, the interrupt buffer was
too small for a single data entry (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 11.6.1.

11-30

returns

are

presented

CHAPTER 11.
11.6.1

UNIVERSAL DIGITAL CONTROLLER DRIVER

FORTRAN Interface Values

The values listed in Table 11-7 are
calls.

returned

FORTRAN

subroutine

Table 11-7
FORTRAN Interface Values

11.7

Status Return

FORTRAN Value

IS.SUC
IS.PND
IE.ABO
IE.ADP
IE.BAD
IE.BYT
IE.DAO
IE.DNR
IE.IEF
IE.IFC
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

PROGRAMMING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the UDCll driver described in this
chapter.

(
11.7.1

Checkpointable Tasks

Since checkpointable tasks are not allowed to have more than one
outstanding I/O request, a task that issues a request to connect to
timer or contact interrupts Inust not be checkpointable.

11.7.2

Numbering Conventions

Numbering is relative. Module numbers start at 0, beginning with
first module of a given type.

11-31

the

CHAPTER 11.

UNIVERSAL DIGITAL CONTROLLER DRIVER

Channel numbers also start at 0, with channel 0 as the first channel
on the first module of a given type. For instance, channel 10 (octal)
is the first channel on the second analog output module.
Point numbers start at 0, with point 0 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).

11.7.3

Use of CTDI and RDDI for Processing Circular Buffer Entries

Circular buffer entries should be processed in the following sequence.
1.

Execute a WAITFOR system directive predicated on the
trigger event flag specified in the CTDI subroutine call.

Repeatedly call RDDI until all
read and ipt is negative.

Perform any other processing and return to step 1.

11-32

valid

points

have

been

CHAPTER 12
LABORATORY PERIPHERAL SYSTEM DRIVER

12.1

INTRODUCTION

The LPSll Laboratory Peripheral System
sub-system that includes the following:

• 12 bit analog-to-digital converter, with
circuitry and an eight-channel multiplexer
• Programmable real-time
intervals or events

clock

for

• Display controller to display data in
. matrix
• Digital input/output
programmable relays)

option

(16

modular,
sample

measuring
a

4096

digital

real-time
and

hold

and

counting

4096

dot

points

and

Built in a compact size and designed for easy interfacing with outside
instrumentation, the LPSll is suited to a variety of applications,
including biomedical research, analytical
instrumentation,
data
collection
and
reduction, monitoring, data logging, industrial
testing, engineering, and technical education.

(

At system generation, the user can specify the following:
• Number of A/D channels
• Whether the gain-ranging option (LPSAM-SG) is present and the
polarity of each channel (uni- or bi-polar)
Whether the external D/A option (LPSVC and LPSDA) is present,
and if so, the number of D/A channels
• Clock preset value

12-1

CHAPTER 12.
12.2

LABORATORY PERIPHERAL SYSTEM DRIVER

GET LUN INFORMATION MACRO

If a GET LUN INFORMATION system directive is issued for a LUN
associated with an LPSll, word 2 (the first characteristics word)
contains all zeros, words 3 and 4 are undefined, and word 5 contains a
l6-bit buffer preset value that controls the rate of LPSll clock
interrupts, as explained in section 12.6.1.

12.3

QIO MACRO

This section summarizes standard and device-specific OIO functions for
the LPSll driver.

12.3.1

Standard OIO Function

Table 12-1 lists the standard function of the OIO macro that is
for the LPSll.

valid

Table 12-1
Standard QIO Function for the LPSll
Format
QIO$C IO.KIL, •••

Function
Cancel I/O requests

IO.KIL cancels all queued and in progress I/O requests.

12.3.2

Oevice-Specific QIO Functions (Immediate)

Except for IO.STP (see section 12.3.4), all device-specific functions
of the OIO macro that are valid for the LPSll are either immediate or
synchronous. Each immediate function performs a complete operation,
whereas each synchronous function simply initiates an operation.
Table 12-2 lists the immediate functions.

12-2

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

Table 12-2
Device-Specific QIO Functions for the LPS11 (Immediate)
Format

Function

QIO$C IO.LED, ••• ,<int,num>

Display nmnber in LED lights

QIO$C IO.RF.L, ••• ,<re1,po1>

Latch output relay

QIO$C IO.SDI, ••• ,<mask>

Read digital input register

QIO$C IO.SDO, ••• ,<mask,data>

Write digital output register

where:

int

is the 16-bit signed binary integer to display.

num

is the LED digit number where the decimal point
be placed.

re1

is the relay number (zero or one).

pol

is the polarity (zero for open, nonzero for closed).

mask

is the mask word.

data

is the data word.

The following subsections describe the functions listed above.

12.3.2.1 IO.LED - This 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
tha~ 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.

12.3.2.2 IO.REL - This 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.

12-3

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

12.3.2.3 IO.SDI - This function reads data qualified by a mask word
from the digital input register. The mask word contains a 1 in each
bit position from which data is to be read.
All other bits are
zero-filled and the resulting value is returned in the second I/O
status word.
The operation performed is:
RETURN VALUE=MASK.AND.INPUT REGISTER

12.3.2.4 IO.SDO - This function writes data qualified by a mask word
into the digital output register. The mask word contains a 1 in each
bit position that is to be written. The data word specifies the data
to be written in corresponding bit positions.
The operation performed is:
NEW REGISTER=<l1ASK.AND.DATA).OR.« • NOT.MASK) • .Al.~D.OLD REGISTER)

12.3.3

Device-Specific QIO Functions (Synchronous)

Table 12-3 lists the synchronous, device-specific functions of the QIO
macro that are valid for the LPS1l.

(

Table 12-3
Device-Specific QIO Functions for the LPS11 (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

QIO$C IO.MDA, ••• ,<stadd,size pnt,
ticks,bufs,chnd)

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

(

12-4

CHAPTER 12.
where:

LABORATORY PERIPHERAL SYSTEM DRIVER

stadd

is the starting address of the data buffer (must be
a word boundary) •

size

is the data buffer size in bytes (must be greater
zero and a multiple of four bytes).

than

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 LPSll clock ticks between
data transfers, as appropriate.

bufs

is the number of data buffers to transfer.

chna

is the A/D conversi.on specification (byte 0 starting
A/D channel number, which must be in the range 0-63.
If the gain ranging option is present the channel
number Must be in the range 0-15 and bits 4 and 5
specify the gain code. Byte 1 - number of consecutive
A/D channels to be sampled, which must be in the range

samples

1-64).
chnd

is the D/A output channel specification (byte 0
starting D/A channel number, which must be in the range
0-9; byte I
number of consecutive channels to
output, which must be in the range 1-10).

mask

is the mask word.

The following subsections describe the functions listed above.

(

12.3.3.1 IO.ADS - This function reads one or more A/D channels at
precisely timed intervals, with or without auto gain-rangi.ng. If t\o,ro
or more channels are specified, all are sampled at approximately the
same time, once per interval. The auto gain-ranging algorithm causeR
a channel to he sn.mpled at the highest gain at which saturation doe'S
not occur.
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 prograrrt request (IO.STP or IO.KIL), by the cleRring of
a digital input point, or by the collection o:f a specified numher of
buf.fers 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 not,ified
(via the setting of an event flag)
that data is available to be
processed \OThi1e the driver fills the other half of the buffer.

12-5

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

The subfunction modifier bits are identical to those described in
section 12.3. 3.2';
in addition, setting bit 3 to 1 means auto
gain-ranging is requested. 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 auto gain-ranging is used, the LPSAM-SG hardware option must be
present and specified at system generation.
If the gain-ranging
option is present and auto gain-ranging is not specified in bit 3 of
the sub-function 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
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

value

If the LPSAM-SG option is present, then the band pass filter jumpers
must not be clipped.
Also, each channel must have been defined as
uni- or bi-polar at system generation.

12.3.3.2 IO.HIS - This 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
12.3.3.1.
All
input
is
double-buffered with respect to the user task.
The subfunction modifier bits appear below.
the action listed in the right-hand column.

12-6

A setting of 1

indicates

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

Bit

Meaning

0-3

Unused

Stop on number of buffers

stop on digital input point

clear

Set digital output point at
of operation

start

Start on digital input point
set
(a zero specification means start
immediately)

12.3.3.3 IO.MDA - This function writes data into one or more external
D/A converters at precisely timed in~ervals. 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 12.3.3.1. All output is double-buffered with respect to the
user task.
D/A converters 0 and 1 correspond to the X and Y registers of the
LPSVC option.
D/A converters 2 through 9 correspond to the LPSDA
external D/A option.
The subfunction modifier bits are
section 12.3.3.2.

identical

those

described

12.3.3.4 IO.MDI - This function provides the capability to read data
qualified by a mask word from the digital input register at precisely
timed intervals. Sampling may be started and stopped as described in
section 12.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 12.3.3.2.

identical

those

described

12.3.3.5 IO.MDO - 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 12.3.3.1.
All
output is double-buffered with respect to the user task.
The subfunction modifier bits are
section 12.3.3.2.

identical

12-7

those

described

CHAPTER 12.
12.3.4

LABORATORY PERIPHERAL SYSTEM DRIVER

Device-Specific OIO Function (IO.STP)

Table 12-4 lists the device-specific IO.STP function of the OIO macro,
which is valid for the LPSll.
Table 12-4
Device-Specific OIO Function for the LPSll (IO.STP)
Format "

Function

OIO$C IO.STP,.~.,<stadd>
where:

stadd

Stop in-progress request

is the buffer address of the function to stop (must be
the same as the address specified in the initiating
request).

12~3.4.l
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.

(

12-8

CHAPTER 12.
12.4

LABORATORY PERIPHERAL SYSTEM DRIVER

FORTRAN INTERFACE

A collection of FORTRAN-callable subroutines provide FORTRAN programs
access to the LPSll. 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.

12.4.1

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
an I/O status code on completion of an I/O operation.

The meaning of its contents varies, depending on the FORTRAN call that
has been executed, but Table 12-5 lists certain general principles
that apply. The sections describing individual subroutines provide
more details.
Table 12-5
Contents of First Word of isb
Contents

Meaning

=0
isb(l) = 1
isb (1) = 3

Operation pending;

isb (1)

3 < isb(l)
isb(l)

I/O in progress

Successful completion
Interface subroutine unable to generate QIO
directive or illegal time or buffer value

< 300

> 300

QIO directive rejected and actual error
code = -(isb(l) ~ 3)
Driver rejected request and actual error
code = -isb(l) - 300)

FORTRAN interface routines depend on asynchronous system traps to set
their status. Thus, if the trap mechanism is disabled, proper status
cannot be set.

12-9

CHAPTER 12.
12.4.2

LABORATORY PERIPHERAL SYSTEM DRIVER

Synchronous Subroutines

RTS, DRS, HIST, SDO, and SDAC are FORTRAN subroutines that initiate
synchronous functions.
When they are used, the LPSll 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 + I
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 LPSl1 driver performs double buffering within the half buffers.
Each time the 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
from the user buffer when none is available (i.e., the buffer is
empty).
All synchronous functions may be initiated immediately or when a
specified digital input point is set (i.e., a start button is pushed).
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.

12-10

{
\

CHAPTER 12.
12.4.3

LABORATORY PERIPHERAL SYSTEM DRIVER

FORTRAN Subroutine Summary

Table 12-6 lists the FORTRAN interface subroutines supported for the
LPSll under RSX-llM. S and F indicate whether they can be called as
subroutines or functions.
Table 12-6
FORTRAN Interface Subroutines for the LPSll
Subroutine

(

Function

ADC

Read a single AID channel (F/S)

ADJLPS

Adjust buffer pointers (S)

ASLSLN

Assign a LUN to LSO:

CVSWG

Convert a switch gain AID value to
floating-point (F)

DRS

Initiate synchronous digital input
sampling (5)

HIST

Initiate histogram sampling (S)

IDIR

Read digital input (F/S)

rDOR

Write digital output (F/S)

IRDB

Read data from a synchronous function input
buffer (F/S)

LED

Display number in LED lights (S)

LPSTP

Stop an in-progress synchronous
function (S)

PUTD

Put data into a synchronous function output
buffer (5)

relay

latch an output re.lay (S)

RTS

Initiate synchronous AID sampling (S)

SDAC

Initiate synchronous D/A output (S)

SDO

Initiate synchronous digital output

(S)

The following subsections briefly describe the function and format
each FORTRAN subroutine call.

12-11

CHAPTER 12.
l2.4~4

ADC:

LABORATORY PERIPHERAL SYSTEM DRIVER
Reading a Single AID Channel

The ADC FORTRAN subroutine or function reads a single converted value
from an AID channel.
If the gain-ranging option is present in the
LPSll hardware, the channel may be converted at a specific gain or the
driver can select the best gain (the gain providing the most
significance). The converted value is returned as a normalized
floating-point number. The call is issued as follows:
CALL ADC (ichan,[var],[igain],[isb])
where:

ichan

specifies the AID channel to be converted.

var

is a floating-point variable
that
receives
converted value in floating-point format.

igain

specifies the gain at which the specified AID channel
is to be converted. The default is 1. If specified,
igain may have the following values:
igain

isb

the

Gain
Autogain-ranging (driver selects gain
that provides most significance)

is a 2-word integer
status is returned.

array

which

the

subroutine

The isb array has the standard meaning described in section 12.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 AID conversion (see section 12.5.3).
Otherwise, this value is a floating-point number calculated from the
following formula:
var = (64

* converted value) I

12-12

conversion gain

CHAPTER 12.
12.4.5

LABORATORY PERIPHERAL SYSTEM DRIVER

ADJLPS:

Adjusting Buffer Pointers

The ADJLPS FORTRAN subroutine adjusts buffer pointers for a buffer
that the LPSll driver is either synchronously filling or emptying. It
is usually called when indexing is being used for direct access to the
data in a buffer.
When data in a buffer is to be processed only once, the IRDB and PUTD
routines may be used. In some cases, however, it is useful to leave
data in the buffer until processing is complete. The user program 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 buffer of data is ready for output, ADJLPS is called to
make the half buffer available.
When ADJLPS is used for either input or output, care must be taken to
insure that the program stays in sync with the LPSll driver. If the
program loses its position with respect to the driver, the function
must be stopped and restarted. An attempt to overadjust will cause a
3 to be returned in isb (1) and no adjustment to take place.
The call is issued as follows:
CAIJL ADJLPS (ibuf,iadj,[isb])
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
status is returned.

array

which

the

subroutine

The isb array has the standard meaning described in section 12.4.1.

12-13

CHAPTER 12.
12.4.6

LABORATORY PERIPHERAL SYSTEM DRIVER

ASLSLN:

Assigning a LON to LSO:

The ASLSLN FORTRAN subroutine assigns a logical unit number (LON) to
the LPSll.
It must be called before execution of any other LPSll
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])
where:

lun

is the number of the LON to be assigned to LSO:

isb

is a 2-word integer
status is returned.

array

which

the

subroutine

The isb array has the standard meaning described in section 12.4.1.

12.4.7

CVSWG:

Converting a switch Gain AID Value to Floating-Point

The CVSWG FORTRAN function converts an AID value from a synchronous
sampling function to a floating-point number. Each data item
returned by the LPSll driver consists of a gain code and converted
value packed in a single word (see section 12.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 LPSll 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 12.4.12).

AID

The call is issued as follows:
CVSWG (ivaI)
where:

ivaI

is the value to be converted to floating point.
Its
format must be that returned b~ a synchronous AID
sampling function.
The
convers~on
is
performed
according to the following formula:
var = (64

* converted value) I conversion gain

For the various gain codes,
var = x

* converted value

as shown below:

12-14

CHAPTER 12.

12.4.8

DRS:

LABORATORY PERIPHERAL SYSTEM DRIVER
Gain

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 12.4.17) 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 12.4.11), or the ADJLPS routine (see section 12.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 to receive the
values.

ilen

specifies the length of ibuf (must be even and
than or equal to six).

imode

specifi~s the start,
stop, and sampling mode.
Its
value ~s encoded by adding together the appropriate
function selection values shown below:

(
\

Function Selection Value

(

input

Meaning

128

Start on digital input point set

Set digital output point at start

stop on digital input point clear

stop on number or buffers

12-15

data

greater

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

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 (1)

unit

LPSll clock ticks

Milliseconds

Seconds

Minutes.

The second word specifies the interval magnitude
l6-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 collected.

imask

specifies the digital input points to be read.

isb

is a 2-word integer
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.

array

which

the

subroutine

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 ha's been
added into imode.
istop

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.

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.

12-16

{

CHAPTER 12.
12.4.9

HIST:

LABORATORY PERIPHERAL SYSTEM DRIVER
Initiating Histogram Sampling

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
12.4.17) 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 to receive the
values.

ilen

specifies the length of ibuf (must be even and
than or equal to six).

imode

specifies the start, stop and sampling mode. Its value
is encoded by adding the appropriate function selection
values shown below:
Function
Selection
Value

input

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

12-17

data

greater

CHAPTER 12.
irate

LABORATORY PERIPHERAL SYSTEM DRIVER

is a 2-word integer array that specifies the time
interval between samples. The first word specifies the
interval units as follows:
irate (1)

unit

LPSll clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the interval magnitude
l6-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
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.

array

which

the

subroutine

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.

The isb array has the standard meaning described in section 12.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.

12-18

CHAPTER 12.
12.4.10

LABORATORY PERIPHERAL SYSTEM DRIVER

IDIR:

Reading Digital Input

The IDIR FORTRAN subroutine or function reads the digital input
register as an unsigned binary integer or as four binary-coded decimal
(BCD) digits. In the latter case, the BCD digits are converted to a
binary integer before the value is returned to the caller. The call
is issued as follows:
CALL IDIR (imode,[ival],[isb])
where:

imode

specifies the 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 l6-bit
unsigned binary integer.

ivaI

is a variable that receives the value read.

isb

is a 2-word integer
status is returned.

array

which

the

subroutine

The isb array has the standard meaning described in section 12.4.1.
When the function form of the call is used, the value of the
is the same as that returned in ivaI.

function

(
12.4.11

IDOR:

Writing Digital Output

The IDOR FORTRAN subroutine or function clears or sets bits in the
digital output register. The caller provides a mask word and output
mode. Bits in the digital output registers corresponding to the bits
specified in the mask word are either set or cleared according to the
specified mode. The call is issued as follows:
CALL IDOR (imode,imask,[newva1] ,[isb])
where:

imode

specifies whether the bits specified by imask are to be
cleared or set in the digital output register. If
irnode 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.

12-19.

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

newval is a variable that receives the updated (actual)
written into the digital output register.
isb

is a 2-word integer
status is returned.

array

which

the

value

subroutine

The isb array has the standard meaning described in section 12.4.1.
When the function form of the call is used, the value of the
is the same as that returned in newval.

12.4.12

IRDB:

function

Reading Data from an Input Buffer

The IRDB FORTRAN subroutine or function retrieves data sequentially
from a buffer that the LPSll driver is synchronously filling.
If no
data is available when the call is executed, the contents of the next
location in the data buffer are returned without updating the buffer
pointers. The call is issued as follows:
CALL IRDB (ibuf,[ival])
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
buffer.

When the function form of the call is used, the value of the
is the same as that returned in ival.

12.4.13

LED:

data

function

Displaying in LED Lights

The LED FORTRAN subroutine displays a l6-bit signed binary integer in
the LED lights.
The number is displayed with a leading blank
(positive number) or minus (negative number), followed by five
non-zero suppressed decimal digits that represent the magnitude of the
number. LED digits are numbered right to left starting at 1 and
continuing to 5.
The number may be displayed with or without a
decimal point. The call is issued as follows:
CALL LED (ival,[idec],[isb])

12-20

CHAPTER 12.

LABORATORY PERIPHE-RAL SYSTEM DRIVER

(
where:

ivaI

is the variable whose value is to be displayed.

idec

specifies the position of the decimal point.
A value
of 1 to 5 specifies that a decimal point is to be
displayed. All other values specify that no decimal
point is to be displayed.

isb

is a 2-word integer
status is returned.

array

which

the

subroutine

The isb array has the standard meaning described in section 12.4.1.
For example, the following call
CALL LED (-55,2)
would cause -0005.5 to be displayed in the LED lights.

12.4.14

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:

ibuf

is an integer array that specifies a buffer that was
previously
specified
in a synchronous initiation
request.

12.4.15

PUTO:

Putting a Data Item into an output Buffer

The PUTD FORTRAN subroutine puts data sequentially into a buffer elat
the LPSll 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:

ibuf

is an integer array which was previously specified in a
synchronous output request (SOO or SDAC).

ival

is a variable whose value is to be placed in
free location in the data buffer.

12-21

the

CHAPTER 12.
12.4.16

LABORATORY PERIPHERAL SYSTEM DRIVER

RELAY:

Latching an Output Relay

The RELAY FORTRAN subroutine opens or closes the
call is issued as follows:

LPSll

relays.

The

closed

(one

CALL RELAY (irel,istate,[isb])
where:

irel

specifies which relay is to be opened
for relay one, two for relay two).

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

array

which

the

~ubroutine

The isb array has the standard meaning described in section 12.4.1.

12.4.17

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 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 12.4.11), or the ADJLPS routine (see section
12.4.5) may be used in conjunction with direct access to the input
data.
The call is issued as follows:
CALL RTS (ibuf,ilen,imode,irate,iefn,ichan,richan,
isb, [nbuf] , [istart] , [istop] )

12-22

CHAPTER 12.

where:

LABORATORY PERIPHERAL SYSTEM DRIVER

ibuf

is an integer array that is to
data values.

ilen

specifies the length of ibuf (must be even and
than or equal to six).

imode

specifies the start, stop, and sampling mode.
Its
value is encoded by adding together the appropiate
function selection values as shown below:
Function
Selection
Value

irate

the

converted
greater

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

Auto gain-ranging

is a 2-word integer array that specifies the time
interval between AID samples. The first word specifies
the interval unit as follows:
unit

irate (1)

(

receive

LPSll clocks ticks

Milliseconds

Seconds

Minutes

The second word specifies the interval magnitude
l6-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 collected.

ichan

specifies the starting AID channel of the block of
channels to be sampled synchronously (must be bebreen 0
and 63).

nchan

specifies the number of AID
(must be between 1 and 64).

12-23

channels

sampled

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

ish

is a 2-word integer
status is returned.

array

which

the

subroutine

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.

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.

The ish parameter
12.4.1.

has

the

standard

meaning

described

section

When sampling is in progress, the first word of' the ish array is zero
and the second word contains the number of data values currently in
the buffer.

12.4.18

SDAC:

Initiating Synchronous D/A Output

The SDAC FORTRAN subroutine writes data into one or more external D/A
converters at precisely timed intervals. Output may be started and
stopped as for RTS (see section 12.4.17) 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 12.4.15) may be used to put data values
sequ~ntially
into the output data buffer. The ADJLPS routine (see
section 12.4.5) may be used in conjunction with direct access to the
output data buffer. The SDAC call is issued as follows:
CALL SDAC (ibuf,ilen,imode,irate,iefn,ichan,
nchan,isb,[nbuf] ,[istart] ,[istop])
where:

ibuf

is an integer
values.

ilen

specifies the length of ibuf (must be even and
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:

array

that

12-24

contains

the

output

data

greater

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER
Function
Selection
Value

irate

Meaning

128

Start on digital input point set

Set digital output point at start

Stop on digital input point clear

Stop on number of buffers

is a 2-word integer array that specifies the time
interval between D/A outputs. The first word specifies
the interval lmits as follows:
irate (1)

unit

LPSll clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the interval magnitude
l6-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.

ichan

specifies the starting D/A channel of the block of
channels to be written into synchronously (must be
between 0 and 9).

nchan

specifies the number of D/A channels to be written into
(must be between 1 and 10).

isb

is a 2-word

nbuf

specifies the number of buffers of data to be output.
It is needed only if function selection value of 16 has
been added into imode.

integer
status is returned.

array

which

the

subroutine

12-25

CHAPTER 12.
istop

LABORATORY PERIPHERAL SYSTEM DRIVER
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.

The isb array has the standard meaning described in section 12.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.

12.4.19

SDO:

Initiating Synchronous Digital Output

The SDO FORTRAN subroutine writes data qualified by a mask word into
the digital output register at precisely timed intervals. Sampling
may be started and stopped as for RTS (see section 12.4.17) and all
input is double-buffered with respect to the user task. One full
buffer of data must be available when output is initiated.
After SDO has initiated output and the specified event flag has been
set to noti,fy the task that free buffer space is available, the PUTD
routine
(see section 12.4.15) may be used to put data values
sequentially into the output data buffer. The ADJLPS routine (see
section 12.4.5) may be used in conjunction with direct access to the
output data buffer. The SDO is issued as follows:
I

CALL SDO (ibuf,ilen,imode,irate,iefn,imask,isb,
[nbuf] , [istart],[istop])
where:

ibuf

is an integer array that contains
values.

digital

output

ilen

specifies the length of ibuf (must be even and
than or equal to six).

greater

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

the

(

Meaning

128

Start on digital input point set

set digital output point at start

stop on digital input point clear

Stop on number of buffers

is a 2-word integer array that specifies the
interval between digital outputs.
The first
specifies the interval units as follows:

12-::>6

time
word

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

irate (1)

Unit

LPSll clock ticks

Milliseconds

Seconds

Minutes

The second word specifies the interval magnitude
l6-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 specifed as an octal
constant.

isb

is a 2-word integer
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.

(

array

which

the

subroutine

specifies the digital input point number to be used to
stop sampling.
It is needed i.f a function selection
value of 32 has been added into imode.

(
The ish parameter
12.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
buffer.

12.5

STATUS RETURNS

The error and status conditions listed in Table 12-7 are
the LPSll driver described in this chapter.

12-27

returned

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEr-t DRIVER
Table 12-7
LPS11 Status Returns

Code
IS.SUC

IS.PND

I/O request pending
The operation specified in the QIO
yet been completed.

IE.ABO

directive

has

not

Operation aborted
The specified I/O operation was canceled (via IO.KIL or
IO.STP) while in progress.

IE.BAD

Bad parameter
An illegal specification vias 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 the LPS11. Alternately,
the length of a buffer is not an even number of bytes.

IE.DAO

Data overrun
For the LPS1l, the driver attempted to get a value from
the user buffer when none was available or attempted to
put a value in the user buffer when no space was
available.

IE.DNR

Device not ready
The physical device unit specified in the QIO directive
was not ready to perform the desired I/O operation.
For the LPS11, this code is returned if a device
timeout occurs while a function is in progress. The
second I/O status word contains the nmober of free
positions in the buffer, as appropriate.

12-28

(

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER
Table 12-7 (Cont.)
LPSll Status Returns

Code
IE.IEF

Reason
Invalid event flag number

invalid event flag number was specified in a
synchronous function
(i.e., an event flag number that
was not in the range 1 to 64).
An

IE.IFC

Illegal function
A function code was included in an I/O request that
illegal for the LPSll.

IE.NOD

Insufficient buffer space
Dynamic storage space has been depieted, and there is
insufficient buffer space available to allocate a
secondary control block for a synchronous function.

IE.OFL

IE.ONP

Option not present
An option dependent 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 zeros.

IE.PRI

Privilege violation
The task which issued the request was not privileged to
execute that request. For the LPSll, a checkpointable
task attempted to execute a synchronous
sampling
function.

IE.RSU

Resource in use
A resource needed by the function requested in the
directive was being used (see section 12.5.1).

IE.SPC

QIO

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

12-29

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEH DRIVER

FORTRAN interface values for these status
section 12.5.4.

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

Hhen IE.RSU Is Returned

IO.SDO

One or more specified digital output bits are in use

IO.ADS

Digital output point (if specified) is in use

IO.HIS

Digital output point (if specified) is in use

IO.HDA

Digital output point (if specified) is in use

IO.HDI

Digital output point (if specified)
points to be sampled are in use

IO.MDO

nigital output point (if specified) or output
be written are in use

The following components of the LPSll are
resource:

each

digital

considered

input

bits

single

Resource

When Shareable

The A/D converter
and clock

Always shareable.

Each bit in the digital
output register

Never shareable.

Each bit in the digital
input register

AhV'ays shareable when used by IO. SDI or
for start/stop conditions (specified in
subfunction modifier bits) ,even when in
use by another function; when specified
by a synchronous digital input function,
not
shareable
with
another
such
function.

12-30

(
\

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

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

12.5.2

Second I/O Status Word

On successful completion of a function specified in a QIO macro call,
the IS.SUC code is returned to the first word of the I/O status block.
Table 12-8 lists the contents of the second word of the status
on successful completion for each LPSll function.

block,

Table 12-8
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

11!asked value read from digital input register

IO.SDO

Updated value written into digital output register

IO.ADS

Number of data values remaining in buffer

IO.HIS

Number of data values remaining in buffer

IO.MDA

Number of free positions in buffer

IO.MDI

Number of data values remaining in buffer

IO.MOO

Number of free positions in buffer

IO.STP

Zero

When IE.BAD is returned, the second I/O status word contains zero.
LPSll driver functions 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

No I/O status block, illegal digital

12-31

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

IO.MDA

I/O point number, or illegal channel number.

IO.HIS
IO.MDl
IO.MOO

No I/O status block or illegal
digital I/O point number.

12.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
the user by placing illegal values in the data buffer. A -1
(177777
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.
12.5.4

FORTRAN Interface Values

The values listed in Table 12-9 are
calls.

returned

FORTRAN

subroutine

Table 12-9
FORTRAN Interface Values

12.6

Status Return

FORTRAN Value

IS.SUC
IS.PND
IE.ABO
IE.ADP
IE.BAD
IE.BYT
IE.DAO
IE.DNR
IE.IEF
IE.IFC
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

PROGRAl1MING HINTS

This
section
contains
information
on
important
programming
considerations relevant to users of the LPSll driver described in this
chapter.

12-32

CHAPTER 12.

12.6.1

LABORATORY PERIPHERAL SYSTEM DRIVER

The LPSll Clock and Sampling Rates

The basic LPSll clock frequency (count rate) for all synchronous
functions is always 10KHZ. Device characteristics word 4 contains a
l6-bit buffer preset value, set dynamically or at system generation,
that controls the rate of "ticks" (i.e. the rate at which the LPSll
clock interrupts). The quotient that results when this value is
divided into 10KHZ is the rate of "ticks". For example, if this value
is 2, the "tick" rate is 5KHZ. The user may use a GET LUN INFORrv1ATION
system directive to examine the value and a SET /BUF MeR 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
l6-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 1 sample every 100
microseconds
(possible in hardware but impractical in soft\<Tare) and a minimum of 1
sample every 429,495 seconds. A single-channel rate greater than 2KHZ
is possible, but not recommended.
The figures below represent initial timing tests run under RSx-llM on
a PDP-ll/40 with memory management and no gain-ranging option. It
should be noten that no computation was performed on the data other
them continuously removing it from or inserting it into the data
buffer.
Analo<] rates:
1 request for 1 channel at 2.SKHZ
1 request for 2 channels at 2.0KHZ (aggregate 4KHZ)
2 requests for 1 channel at 2.0KHZ (aggregate 4KHZ)
Digital rates:
2 requests at 2.SKHZ (aggregate 5KHZ)

12.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.HDA and IO.¥illO).

12-33

CHAPTER 12.
12.6.3

LABORATORY PERIPHERAL SYSTEM DRIVER

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

2
BUFFER
BUFFER+n
BUFFER

; I/O STATUS DOUBLE-WORD
; ADDRESS OF BUFFER
ADDRESS OF END OF BUFFER
; ADDRESS OF BUFFER

Two of these words are requi~ed by the driver (I/O status block) and
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, buffer overrun has
occurred and the request is terminated. Otherwise the value is stored
in the buffer at the address specified by the driver's write pointer
and the write pointer is updated.
If the value stored in the user buffer fills half of the buffer, the
event flag specified in the I/O request is set in order to notify the
user that a half buffer of data is available to be processed.
Each
time the user task is awakened, it executes the following code:

5$:
10$:

20$:
30$:

,
efn
IOSB+2
;ANY DATA IN BUFFER?
30$
;IF EQ NO
@CURPT,RO
;GET NEXT VALUE FROM BUFFER
IOSB+2
;REDUCE NUMBER OF ENTRIES
#2,CURPT
;UPDATE BUFFER READ POINTER
CURPT,LSTPT
;END OF BUFFER?
CMP
BLOS
;IF LOS NO
20$
;RESET BUFFER READ POINTER
MOV
FSTPT,CURPT
Process data value
;TRY AGAIN
BR
10$
TST
IOSB
;REQUEST TERMINATED?
BNE
40$
;IF NE YES
Waitfor
efn
BR
5$
I
Determine reason for termination
Clear
TST
BEQ
MOV
DEC
ADD

40$

12-34

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER

For IO.MDA and IO.MDO, 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.

12.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(1004),IERR(2),INTVL(2)
C

C INITIATE SYNCHRONOUS A/D SAMPLING,
C

INTVL(1)=2
INTVL(2)=5
CALL RTS(IBF,1004,160,INTVL,IEFN,6,6,IERR,50,16,15)
C

C INITIALIZE HALF BUFFER INDEX
C

INDX=4
C

C WAITFOR HALF BUFFER OF DATA
C

CALL WAITFR(IEFN)

C CLEAR EVENT FLAG
C

CALL CLREF(IEFN)

C PROCESS HALF BUFFER OF DATA
C

(

SUM=O
DO 20 I=1,500
SUM=SUM+CVSWG(IBF(I+INDX»
CONTINUE
AVERG=SUM/500

C FREE HALF BUFFER FOR MORE DATA
C

CALL ADJLPS(IBF,500)
C

C ADJUST BUFFER INDEX
C

INDX=INDX+500
IF (INDX.GE.1004) INDX=4
C

C CHECK IF ANOTHER HALF BUFFER OF DATA IS AVAILABLE
C

IF(IERR(2).GE.500) GO TO 15

12-35

for

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEM DRIVER
IF(IERR(l).NE.O) GO TO end of sampling
GO TO 10

Synchronous output:
DIMENSION IBF(1004),IERR(2),INTVL(2)
C
C FIRST BUFFER OF DATA MUST BE AVAILABLE AT START
C
C THIS EXAMPLE ASSUMES FIRST BUFFER IS FULL AT START
C

C START SYNCHRONOUS DIGITAL OUTPUT FUNCTION
C
INTVL(l) =2
INTVL(2) =5
CALL SDO(IBF,1004,160,INTVL,IEFN,MASK,IERR,50,16,15)

C
C INITIALIZE HALF BUFFER INDEX
C
INDX=4
C
C WAITFOR ROOM IN BUFFER
C
10
CALL WAITFR(IEFN)
C
C CLEAR EVENT FLAG
C
15
CALL CLREF(IEFN)
C
C CALCULATE VALUES TO PUT IN BUFFER
C
X=(Y+2)*Z
DO 20 1=1,500
IBF(I+INDX)=X**5/A
20
CONTINUE
C
C SIGNIFY ANOTHER HALF BUFFER IS FULL
C
CALL ADJLPS(IBF.500)
C
C ADJUST BUFFER INDEX
C
INDX=INDX+500
IF(INDX.GE.1004) INDX=4
C
C CHECK IF ANOTHER HALF BUFFER IS EMPTY
C
IF(IERR(2).GE.500) GO TO 15
IF(IERR(l).NE.O) GO TO end of sampling
GO TO 10

12-36

CHAPTER 12.

LABORATORY PERIPHERAL SYSTEH DRIVER

NOTE

In both the above examples care is taken
to assure that the program stays "in
sync" with the LPSll 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 insure that the above
program sequence is used to avoid a
possible loss of data.

12-37

APPENDIX A
SUMMARY OF I/O FUNCTIONS

This appendix summarizes legal I/O functions for all device drivers
described in this manual.
Both devices and functions are listed
alphabetically. The meanings of the five parameters represented by
the ellipsis ( ••• ) are described in section 1.4.1. The meanings of
the function-specific parameters shown below are discussed in the
appropriate driver chapters. The user may reference these functions
symbolically by invoking the system macros FILIO$ (standard I/O
functions)
and SPCIO$ (special I/O functions), or by allowing them to
be defined at task build time from the system object library.

(

A-I

APPENDIX A.
A.l

SUMMARY OF I/O FUNCTIONS

ANALOG-To-DIGITAL CONVERTER DRIVERS

IO.KIL, •••

Cancel I/O requests

IO.RBC, ••• ,<stadd,size,stcnta) Initiate an A/D conversion

A.2

CARD READER DRIVER

IO.ATT, •••

Attach device

IO.DET, •••

Detach device

IO.KIL, •••

Cancel I/O requests

IO.RDB, ••• ,<stadd,size)

Read logical block (binary)

IO.RLB, ••• ,<stadd,size)

Read logical block (alphanumeric)

IO.RVB, ••• ,<stadd,size)

Read virtual block (alphanumeric)

A. 3

CASSETTE DRIVER

IO.ATT, •••

Attach device

IO.DET, •••

Detach device

IO.EOF, •••

write end-of-file

IO.KIL, •••

Cancel I/O requests

IO.RLB, ••• ,<stadd,size)

Read logical block

IO.RVB, ••• ,<stadd,size)

Read virtual block

IO.RWD, •••

Rewind tape

IO.SPB, ••• ,<nbs)

Space blocks

IO.SPF, ••• ,<nes)

Space files

IO.WLB, ••• ,<stadd,size)

Write logical block

IO.WVB, ••• ,<stadq,size)

Write virtual block

A.4

COMMUNICATION DRIVERS (MESSAGE-ORIENTED)

IO.HDX, •••

Set device to half-duplex mode

IO.INL, •••

Initialize device and set device
characteristics

A-2

APPENDIX A.

(

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

Read logical block, stripping
sync characters

IO.RNS, ••• ,<stadd,size>

Read logical block, transparent mode

IO.WYN, ••• ,<syn>

Specify sync character

IO.TRM, •••

Terminate communication, disconnecting
from physical channel

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

write logical block with sync leader

IO.WNS, ••• ,<stadd,size>

write logical block, no sync leader

A.5

(

SUMMARY OF I/O FUNCTIONS

DEC TAPE DRIVER

IO.RLB, ••• ,<stadd,size",lbn>

Read logical block (forward)

IO.RLV, ••• ,<stadd,s1ze",lbn>

Read logical block (reverse)

IO.RVB, ••• ,<stadd,size",lbn>

Read virtual block (forward)

IO.WLB, ••• ,<stadd,size",lbn>

Write logical block (forward)

IO.WLV, ••• ,<stadd,size",lbn>

write logical block (reverse)

IO.WVB, ••• ,<stadd,size",lbn>

write virtual block (forward)

A.6

DISK DRIVER

IO.RLB, ••• ,<stadd,size"blkh,blkl>

Read logical block

IO.RVB, ••• ,<stadd,size, ,blkh,blkl)

Read virtual block

IO.WLB, ••• ,<stadd,size"blkh,blkl>

Write logical block

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

Write virtual block

A. 7

LABORATORY PERIPHERAL SYSTEM DRIVER

IO.ADS, ••• ,<stadd,size,pnt,
ticks,bufs,chna>

Perform A/D sampling

IO.HIS, ••• ,<stadd,size,pnt,
ticks,bufs>

Perform histogram sampling

IO.KIL,...

Cancel I/O requests

IO.LED, ••• ,<int,num)

Display number in LED lights

A-3

APPENDIX A.

SUMMARY OF I/O FUNCTIONS

IO.MDA, ••• ,(stadd,size,pnt,
ticks,bufs,chnd)

Perform D/A output

IO.MDI, ••• ,(stadd,size,pnt,
ticks,bufs,mask)

Perform digital input sampling

IO.MDO, ••• ,(stadd,size,pnt,
ticks,bufs,mask)

Perform digital output

IO.REL, ••• ,(rel,pol)

Latch output relay

IO.SDI, ••• ,(mask)

Read digital input register

IO.SDO, ••• ,(mask,data)

Write digital output register

IO.STP, ••• ,(stadd)

stop in-progress request

A.8

LINE PRINTER DRIVER

IO.ATT, •••

Attach device

IO.DET, •••

Detach device

IO.KIL, •••

Cancel I/O requests

IO.WLB, ••• ,(stadd,size,vfc)

Write logical block

IO.WVB, ••• ,(stadd,size,vfc)

Write virtual block

A.9

MAGNETIC TAPE DRIVER

IO.ATT, •••

Attach device

IO.DET, •••

Detach device

IO.EOF, •••

Write end-of-file (tape mark)

IO.KIL, •••

Cancel I/O requests

IO.RLB, ••• ,(stadd,size)

Read logical block

IO.RVB, ••• ,(stadd,size)

Read virtual block

IO. RWD, •••

Rewind tape

IO.RWU, •••

Rewind and turn unit off-line

IO.SEC, •••

Read tape

1.0.51'-10, ••• , (cb)

Mount tape and set tape characteristics

A-4

characteristic~

APPENDIX A.

SUMMARY OF I/O FUNCTIONS

IO.SPB, ••• ,<nbs)

Space blocks

IO.SPF, ••• ,<nes)

Space files

IO.STC, ••• ,<cb)

Set tape characteristics

IO.WLB, ••• ,<stadd,size)

write logical block

IO.WVB, ••• ,<stadd,size)

write virtual block

A.lO

TERMINAL DRIVER

IO.ATT, •••

Attach device

IO.DET, •••

Detach device

IO.KIL, •••

Cancel I/O requests

IO.RLB, ••• ,<stadd,size)

Read logical block

IO.RVB, ••• ,<stadd,size)

Read virtual block

IO.WLB, ••• ,<stadd,size,vfc)

write logical block

IO.WVB, ••• ,<stadd,size,vfc)

write virtual block

A.II

UNIVERSAL DIGITAL CONTROLLER DRIVER

IO.CCI, ••• ,<stadd,sizb,tevf)

Connect a buffer to contact
interrupts

IO.CTI, ••• ,<stadd,sizb,tevf,arv)

Connect a buffer to timer
interrupts

IO.DCI, •••

Disconnect a buffer from contact
interrupt

IO.DTI, •••

Disconnect a buffer from timer
interrupts

IO.ITI, ••• ,<mn,ic)

Initialize a timer

IO.KIL, •••

Cancel I/O requests

IO.MLO, ••• ,<opn,pp,dp)

Open or close latching digital
output points

IO.RBC, ••• ,<stadd,size,stcnta)

Initiate multiple A/D conversions

A-S

APPENDIX B
I/O FUNCTION AND STATUS CODES

This appendix lists the numeric codes for all I/O functions, directive
status
returns, and I/O completion status returns.
Lists are
organized in the following sequence:
I/O completion status codes

•

Directive status codes
Device-independent I/O function codes
Device-dependent I/O function codes

Device-dependent function codes are listed by device.
and codes are organized in alphabetical order.

Both

devices

For each code, the symbolic name is listed in form IO.xxx, IE.xxx, or
IS.xxx.
A brief description of the error or function is also
included. Both decimal and octal values are provided for all codes.

B.l

(

I/O STATUS CODES

This section lists error and success codes which can be returned in
the I/O status block on completion of an I/O function. The codes
below may be referenced symbolically by invoking the system macro
IOERR$.

B.l.l

I/O Status Error Codes
Name

Decimal

Octal

!1eaning

IE.ABO

-15

177761

Operation aborted

IE.ALN

-34

177736

File already open

IE.BAD

-01

177777

Bad parameter

APPENDIX B.

I/O FUNCTION AND STATUS CODES

IE.BBE

-56

177710

Bad block

IE.BLK

-20

177754

Illegal block number

IE.BYT

-19

177755

Byte-aligned buffer specified

IE.CON

-22

177752

UDC connect error

IE.DAA

-08

177770

Device already attached

IE.DAO

-13

177763

Data overrun

IE. DNA

-07

177771

Device not attached

IE.DNR

-03

177775

Device not ready

IE.EOF

-10

177766

End-of-fi1e encountered

IE.EOT

-62

177702

End-of-tape encountered

IE.EOV

-11

177765

End-of-volume encountered

IE.FHE

-59

177705

Fatal hardware error

IE.IFC

-2

177776

Illegal function

IE.MOD

-21

177753

Invalid UDC module

IE.NLN

-37

177733

File not open

IE.NOD

-23

177751

No dynamic memory available
to allocate a secondary
control block.

IE.OFL

-65

177677

Device off-line

IE.ONP

-05

177773

Illegal sub function

IE.OVR

-18

177756

Illegal read overlay request

IE.PRI

-16

177760

Privilege violation

IE. RSU

-17

177757

Shareable resource in use

IE.SPC

-06

177772

Illegal address space

IE.VER

-04

177774

Unrecoverable error

IE.WLK

-12

177764

write-locked device

B-2

APPENDIX B.

I/O FUNC'l'l(Hl AlII) WI'ATUS CODES

(

B.l.2

B.2

I/O Status Success Cod""
Name

Decimal

IS.CR

Byte 0:
Byte 1:

IS.ESC

Byte 0:
Byte 1:

IS.PND
IS.SUC

()(; til]

Meaning

1
15

OOC40]

Successful completion with
carriage return

1
33

015401

Successful completion
with ESCape

+00

000000

I/O request pending

+01

000001

Successful completion

DIRECTIVES CODES

This section lists error and success codes which can
the directive status word at symbolic location
directive is issued.

be returned in
$DSW when a QIO

B.2.l Directive Error Codes
Name.

Decimal

Octal

Meaning

IE.ADP

-98

177636

Invalid address

IE.IEF

-97

177637

Invalid event flag number

IE.ILU

-96

177640

Invalid logical unit number

IE.SDP

-99

177635

Invalid DIC number or DPB size

IE.ULN

-05

177773

Unassigned LUN

IE.UPN

-01

177777

Insufficient dynamic storage

(
B.2.2 Directive Success Codes

B.3

Name

Decimal

Octal

Meaning

IS.SUC

+01

000001

Directive accepted

I/O FUNCTION CODES

This section lists codes for all
functions.

standard

B-3

and

device-dependent

I/O

APPENDIX B.

I/O FUNCTION AND STATUS CODES

B.3.1

Standard I/O Function Codes

Name

Octal Words

IO.ATT

Octal Bytes
Code Subcode

Meaning

001400

Attach device

IO.DET

002000

Detach device

IO.KIL

000012

Cancel I/O requests

IO.RLB

001000

Read logical block

IO.RVB

010400

Read virtual block

IO.WLB

000400

Write logical block

IO.WVB

011000

Write virtual block

B.3.2

Specific A/D Converter I/O Function Codes

Name

Octal Words

IO.RBC

003000

Octal Bytes
Code Subcode
6

l-1eaning
Initiate an A/D conversion

B.3.3 Specific A/D Converter I/O Function Codes

NaITle

Octal Words

IO.RDB

001200

octal Bytes
Code Subcode
2

200

Meaning
Read logical block (binary)

B.3.4 Specific Cassette I/O Function Codes

Name

Octal Words

IO.EOF

003000

End-of-file encountered

IO.RWD

002400

Rewind tape

IO.SPB

002420

Space blocks

IO.SPF

002440

Space files

Octal Bytes
Code Subcode

B-4

Meaning

APPENDIX B.

I/O FUNCTION AND STATUS CODES

B.3.5 Specific Communication

Name

Octal Words

IO.HDX

(Messa~e-Oriented)

I/O Function Codes

Octal Bytes
Code Subcode

Meaning

003010

Set device to half-duplex mode

IO.INL

002400

Initialize device and
set device characteristics

IO.RNS

001020

Read logical block,
transparent mode

IO.SYN

003040

Specify sync character

IO.TRM

002310

Terminate communication,
disconnecting from physical
channel

IO.WNS

000410

write logical block with no
sync leader

B.3.6 Specific DECtape I/O F1IDction Codes
Name

Octal Words

Octal Bytes
Code Subcode

Meaning

IO.RLV

001100

100

Read logical block (reverse)

IO.WLV

000500

100

write logical block (reverse)

B.3.7 Specific LPS I/O Function Codes

(

Name

Octal Words

IO.ADS

Octal Bytes
Code Subcode

Heaning

014000

Initialize A/D sampling

IO.HIS

015000

Initialize histogram sampling

IO.LED

012000

Display number in LED lights

IO.1IDA

016000

Initialize D/A output

IO.MDI

014400

Initialize digital input
sampling

IO.MDO

015400

Initialize digital output

IO.REL

013400

Latch output relay

B-5

APPENDIX B.

I/O FUNCTION AND STATUS CODES

IO.SDI

013000

Read digital input register

IO.SDO

012400

write digital output register

IO.STP

016400

stop in-progress request

B.3.8 Specific Magtape I/O Function Codes

Name

Octal Words

Octal Bytes
Code Subcode

Meaning

IO.EOF

003000

write end-of-file gap

IO.RWD

002400

Rewind tape

IO.RWU

002540

140

Rewind and unload

IO.SEC

002520

120

Sense characteristics

IO.SMO

002560

160

Mount and set characteristics

IO.SPB

002420

Space blocks

IO.SPF

002440

Space files

IO.STC

002500

100

Set characteristics

B.3.9 Specific UDC I/O Function Codes

Name

Octal Words

Octal Bytes
Code Subcode

Meaning

IO.CCI

014000

Connect a buffer to contact
interrupt digital input

IO.CTI

015400

Connect a timer

IO.DCI

014400

Disconnect a buffer from
contact interrupt digital
input

IO.DTI

016000

Disconnect a timer

IO.ITI

017000

Initialize a timer

IO.NLO

006000

Open or close latching
digital output points

IO.RBC

003000

Initiate multiple
A/D conversions

B-6

(

APENDIX C
RSX-IIM PROGRAMMING EXAMPLE

MESSAGE TRANSFER

MAC~O M~110

7
8
9
10
11

~AGE

.TITLE MESSAGE TRANSFER
.IDENT 1011

1
2
3
4
5
&

10-0cr-74 10119

COPYRIG~T

1974,

DIGITAL

EQUIPMENT

MASS.

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE ~tTHOUT
NOTICE AND SHOULD NOT BE CONST~UED AS A COMMITMENT BY DIGITAL
EQUIPMENT COR~ORATION.

14
15
1&
17

DEC ASSUMES NO RESPONSIBILITY
OF ITS SOFT~ARE ON EQUIpMENT

18
19

VERSION 01

MAYNARD,

• THIS SOFT~ARE IS FU~NISHED TO PURCHASER UNDfR A LICENSE FOR USE
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (~ITH INCLUSION
OF DEC'S COPY~IGHT NOTICE) O~LY FOR USE IN SUCH SYSTEM, EXCEgr
AS MAY OTHERwISE BE PROVIDED IN WRITING BY DEC.

12
13

CORP.,

, EARL WALDIN

22
23
24
25
2&
27
28
29

FOR
~HICH

THE
IS

USE OR RELIABILITY
NOT SJ~PLIED BY DEC.

5.SEP-7a

DEMONSTRATION Of USE OF RSX-11M 110
MACRO LIBRARY CALLS

30
31

LOCALLY DEFINED MACROS

32
33
34
35

.MACRO
J~R

.ENDM

3&
37

.MACRO
RTS
.ENDM

38
39

40
Q1
42
43

CALL SUBR
PC,SJ8R

,DEFINITION FOR SUBROUTINE CALLS

RETURN
PC

,SUBROJTINE RETURN ~ACRO

LOCAL DATA

41.j

45
4&

C-l

47
48
49
50 000000
51 000002
S2
53
54
55
56
57 000004

J READ·~ELATED
000~0~
~000~0

~DSTSI

000000

WRSTS:

BUFll
BUF21

67
68
69
70
71
72
73 000254
74 000274
75
76

PAGE 1-1

.BLKB
.BlKB

,BUFFER 1
.BUFFER 2

82.
82.

J+
J **-$XFER.DE~ONSTRATE USE Of RSX-l1M 1/0 BY OUTPUTTING RECORDS
J FROM TIl (USER'S TE~MINAl) TO LINE PRINTER. REQUESTS ARE DOUBLE
J BUFFERED TO DEMONSTRATE HOW OPERATIONS MAY BE OVE~lAPPED.
J-

$XFERII
J
J
J

103003

#1,*"T1,#0
#2,~"LP

IN~UT

,LUN 1 IS TIl DEVICE
,LUN 2 IS lP01

DEVICE, LUN

QIOSS
BCC
CALL
BR

#IO.RLB,#1,*1,,#RDSTS,,<#BUF1,#80.>
20$
,If DISPATCHED OK" CONTINUE
STCHK
,CHECK STATUS
105
.If RECOVERABLE ERROR, TRY AGAIN

20$1

WTSESS
CMPB

#1
RDSTS,#IS.SUC

,WAIT UNTIL 1 COMPLETE
,READ SUCCESSFUL?

BEQ
JMP

30$
100!

'CO~TINUE IF SUCCESSfUL
,TERMINATE IF Nor SUCCESSFUL

MOV

RDSTS+2,Rl

,GET ACTUAL BYTE COUNT IN R1

126727
001402
0CHH67
(,H2J0440

30$1
J
J
J

103003

ALUNSS

10S1
000747

016701
177352

A~U~SS

READ A LINE FROM

177364
000000G

89
90
91
92 000430
93 000502
94 000504
95 0~0510
96
97
98

l0-0CT-74 10119

BUFFER STORAGE

b5 000132
6b

88 000424

,WRITE STATUS BLOCK

III

.WORD

60
61
62
63
64 000~10

.WORD

MACRO M07t0

58 000006
S9

85 000416
86 000420

,READ STATUS BLOCK

"
0

~RITE-RELATED STO~AGE

MESSAGE TRANSFER

76 000314
79 000366
60 000370
81 000374
82
83 000376
84 000410

.WO~D
.~ORD

STORAGE

BEGIN TO FILL SECOND BUFFER

40S.

QIO!S

Bec

CALL
BR

000747

*IO.RLB,#1,*2,,~RDSTS,,<*BUF2,#80 ••

50$
STCHK
40$

,CONTINUE If DISPATCH OK
.CHECK STATUS
,TRY AGAIN

START BJFFER lOUT

100
101 000512
102 000564
1"3 000566
1"4 000572
1"5
106
liH
Ul8

50S1
103003
000747

QIOSS
BCC
CALL
BR

*IO.~LB,#2,M1,,#WRSTS,,<#BJf1,R1,#40>

60$
STCHK
50S

,CONTINUE IF NO DISPATCH ERROR
.CHECK STATUS
,TRY AGAIN

T~IS IS A SyNCHRONIZATION POINT. BOTH FUNCTIONS MJST COMPLETE
BEFORE ANYTHING ELSE BEGINS.

1"9
110

C-2

(

MACRO M0710

MESSAGE TRANSFER
111 000574
112 0006~6
113 000614
114 000616
115 000622
116 000634
117 0~0642
118
119
120
121 000644
122 000716
123 00072~
124 000724
125
126 000126
127 0010013
128 001002
129 1301006
130
131
132
133
134
135 001010
136 1301022
137 0010313
138 001"32
139 00103&
140 001050
141 0011215&
142 001060
143
144
145
146
147
148 001064

60$,
126721
177166
000000G
001123
016702
177160
126121
177144
000000G
00111111

PAGE 1-2

WTSESS
CMPB

#2
RDSTS,.IS.SUC

,WAIT FOR 2 TO FILL
,SUCCESSfUL?

BNE
MOV

100$
RDSTSt2,R2

, IF NOT, CIUSH
,GET COUNT FOR BUFFER 2

WTSESS

C~PB

~RSTS,*!s.sue

,WAIT FOR 1 TO EMPTY
,SUCCESSfUL?

B~E

100$

,IF NOT,

CRAS~I

EMPTY BUFFER 2
, FILL BUFFER 1, #IO.RLB,#1,#1,,#RDSTS,,<#BUF1,#80.>

70S1
103003
000147

8051
103003

QIO!S
Bec
CALL

,IF OK, CONTINUE
, CHECK STATUS
,TRY AGAIN

80$

STCHK

70$

GlIO!S

#IO.wLB,*2,M2,,*WRSTS,,<*BUF2,R2,*40>
,CONTINUE IF SUCCESSfUL
STCHK
,CHECK ST~TUS IF NOT SUCCESSfUL
80$
,RETURN

Bec

CALL
B~

000741

90S

THIS IS ALSO A SYNCHRONIZATION POINT
90S1
126127
176152
00000111G
001015
016101
176744
126721
11673121
00000111G
001002
000167
177344

#1
RDSTS,*IS.SUC

,WAIT rOR 1 TO FILL
,SUCCESSfUL?

BNE

100S

, I F NOT, CRAS ~I

MOV

RDSTSt2,Rl

,GET ACTUAL BYTE COUNT IN Rl

WTSESS
CMPB

,WAIT FOR BUFFER 2 TO EMPTY
,SUCCESSFUL?

BNE

UHH

JMP

40$

,TERMINATE IF Nor
,BACK INTO LOOP

WTSESS
CMPB

~RSTS,*IS.SUC

DON'T ATTEMPT TO RECOVER ERRORS
000004

100$1

149

150

151

J
J

152
153
154
155
156

10-0CT-74 10119

JCRAS~

lOT

TASK

.*STCHK • ATTEMPT TO
DIRECTIVE DISPATCH ERROR ONLY IF
IT INVOLVES DYNAMIC MEMORY ALLOCATION - OTHERWISE
RECOVE~

INPUTSI
(SP)=~ETURN

C-3

ADDRESS

TER~INATE.

MACRO MC'J710

MESSAGE TRANSFER
157
158
159
160
161
162

NONE
J-

164 ~01074
165 1101076
166 001 H'4
167
168 001106

126727 STCI1t<r
000000G
0000012lG
001004

000004

10$t

Ib9

CMPB

SDSW,*IE.UPN

JBUFFER ALLOCATION fAILURE?

BNE
wSIGSS
RETURN

10$

,IF NOT TERMINATE
,AWAIT SIGNIFICANT EVENT
,TRY AGAIN

PAGE 1-4

IO.wLB= .***** GX
Is.sue: ***.** GX

~nSTS

12l~0000R

WRSTS
$DSW
$XFER

= ****** GX

STCHK

0010b6R

S$$ARG= "'00002

MACRO M0710

000010R
BJfl
000132R
BJf2
I E~ JPN= ~il\.H •• GX
IO.~LB= *H:U~ GX

F~EE

nETECTED:

COqEZ

10-0CT~74

000004R

0~0254RG

000

001110
E~RORS

SXFER

10:19

MESSAGE TRANSFER
SYMBOL TABLE

0~0000

,CRASH TASK

lOT

.END

000254'

17k'

ABS.

PAGE 1-3

OLJT~UTsr

1&3 001066

10-0CT-74 10119

QlIil1

0
I

3586. wORDS

.~SG/LltTTM=MSG.001

C-4

APPENDIX D
GLOSSARY OF RSX-IIM TERMS

ASYNCHRONOUS SYSTEH TRAP (AST)
A system condition which occurs as a result of an external
significant event such as completion of an I/O request. On
occurrence of the significant event, control passes to an AST
service routine, and the AST is added to an Executive
first-in first-out queue for the task in which the service
routine appears.
ATTACH
Dedicate a physical device unit for exclusive use by the task
that requested attachment. Once the physical device unit has
been attached by a task, using an IO.ATT I/O function, only
that task can free the unit again for use by other tasks in
the system. Attachment request attempted to a device unit
already attached by another task will not be terminated until
the attachment request can finally be honored;
in other
words, the attachment request is terminated only when the
previous attachment is terminated, and no higher priority
attachment requests are queued.

(
DETACH

Free an attached physical device unit for use by tasks other
than the one that attached it. A physical device unit can
only be detached, by means of an IO.DET I/O function, by the
task that attached it, or by the Executive if the task is
terminated vTi th the device still attached.
DIRECTIVE
A type of system meta-instruction which is used to provide a
facility inherent in the hardware by means of executive
requests issued to the RSX-IIM Executive.
Directives are
usually invoked by means of execution of expanded code from
macros in the System Macro Library (RS;~~C.SML).
EVENT FLAG NUMBER
A number which can be specified in a QIO or other macro call
to indicate to the issuing task which significant event has
occurred. There are 64 event flags available in ~SX-lIM.
Flags numbered I through 32 are local to a task;
33 through
64 are common to all tasks.
Flags 25 ,through 32 and 57

D-I

APPENDIX D.

GLOSSARY OF RSX-IIH TERMS

through 64 are normally reserved for RSX-IIM system software
use. Each of the available flags can be referenced by number
and can be used for conununication and synchronization bet\<7een
user tasks, or bet\<7een tasks and executive service requests,
including I/O requests.
I/O STATUS BLOCK
A 2-word array (double-word) in which a code representing the
final status of an I/O request is returned, if the address of
the block is specified in the QIO macro call which generated
the request. A code identifying the type of success or error
is returned in the low-order byte of the first word, optional
device-dependent information in the high-order byte, and the
number of bytes transferred on a read or write in the second
word of the block.
Although the I/O Status Block is
optional, it is the only way a user can guarantee that he
will know the outcome of an I/O request.
LOGICAL ADDRESS
A logical address is a software representation of a hardware
address.
The use of the phrase "logical address" implies
that some mapping occurs between "true", or hardware address
and "artificial" or logical address. The reason for using
logical addresses is that they simplify the way one deals
with a hardware device or family of devices.
The logical address in RSX-11M refers to 'the relative
position of a logical block on a vo1wne. The volume is
divided into logical blocks, each of which is assigned an
address called a logical block number (LBN).
All mass
storage media are accessed by LBN (e.g., 17) rather than
physical address (e.g., cylinder 5, track 3, sector 7).
LOGICAL BLOCK

{

lo<]ical block in RSX-Ilr-1 parlance refers to 512 bytes of
storage which may be considered to be a discrete entity for
lo<]ical purposes. In fact, it might be composed of odd-sized
fragmentR of non-contiguous storage.
Actually, a logical
block <]enerally refers to one or more physical blocks of a
formatted or block-structured mass memory which compose the
logical atom Eor access to the medium.
IJogical block may
also refer to the in-core image of a logical block which is
or will be on a mass storage device.
A

The concept of logical block is useful on file-structured
devices, in that all such devices appear to share all
characteristics but total number of blocks.

D-2

APPENDIX D.

GLOSSARY OF RSX-IIM TERMS

LOGICAL BLOCK NUMBER (LBN)
Sequential position of a logical block with respect to a
collection of such blocks (which may compose a volume). If
the collection of blocks had been written in logical order on
a sequential medium, such as magnetic tape, the logical block
number for any block would be the true position of the block
on that medium, e.g., logical block 2 would be encountered
just after LBN 1 and just before LBN 3.
LOGICAL UNIT NUMBER (LUN)
A number associated with a physical device unit during a
task's I/O operations. Each task in the system can establish
its own correspondence between LUNs and physical device
units.
MACRO
A system capability which allows a user to generate Assembler
instructions, data, or symbols in a predetermined format by
providing actual arguments to the Assembler in a macro call
included
in
a
r.1ACRO-II
program.
r1acros provide a
standardized means of obtaining access to system services or
resources by invocations from programs.
PRIORITY
A number associated with an RSX-IIM task which indicates the
relative position of that task among all tasks in the system.
The priority is associated with a task at task build time and
may be changed at run time. Legal priorities are in range 1
through 250, with greater magnitude
indicating
higher
priority.
If two tasks are identical in every way (i.e.,
resources used, etc.) except priority and are initiated at
the same time, the task with the higher priority will
cOMplete first.
I/O requests issued by a task assume the
priority of that task and are honored according to the task's
priority.
SIGNIFICANT EVENT
An event or condition which indicates a change in system
status.
In RSX-IIM, a significant event is declared when an
I/O operation completes and in some other cases as well.
A
declaration
of a significant event indicates that the
Executive should review the eligibility of all tasks in the
system to determine which task should run next, since the
significant event might unblock the execution of a higher
priority task.

D-3

APPENDIX D.

GLOSSARY OF RSX-llM TERMS

SYNCHRONOUS SYSTEH TRAP (SST)
A system condition which occurs as a result of an error or
fault within the executing task. If the same instruction
. sequence were repeated, the same synchronous trap would
occur.
On recognition of a synchronous trap, control passes
to an SST service routine. SSTs are not handled directly by
the Executive as ASTs are.
VIRTUAJ.J ADDRESS
A number which indicates relative
position
within
a
collection of logically-related granules of a storage medium.
The fact that the medium itself may be virtual (e.g., 1
million bytes of addressable memory, but only 64K in core
memory, the remainder on mass storage) is
of
little
consequence;
in
fact,
the
ability to deal with a
hierarchical or multi-level memory as if it were one mediUM
is one of the principal advantages of systems supporting
virtual addressing. In RSX-llM, virtual address generally
refers to relative position within a task image, while
VIRTUAL BLOCK NUMBER (VBN) refers to relative position within
a file.
VIRTUAL BLOCK
One of a collection of blocks which make up a user file
(or
the core image of that file). The block is virtual only in
that its address (VBN) refers to position within a file
regardless of the file's allocation or placement on a storage
medium. When a user accesses a file, he can think of the
file as a virtual storage medium belonging to him. Virtual
addressing within that file could be considered to be
absolute addressing on a virtual medium •.

(

D-4

INDEX

Aborting a task, 4-9, 5-13, 7-7,
8-13
Accessing UDCll modules, 11-2
A/D conversion control word, 10-3
A/D converter I/O function codes,
specific, B-4
A/D converter status returns, 10-8
Address, logical, D-2
Address, virtual, D-4
A/D functional capabilities, 10-10
A/D gain ranges, use of, 10-11
Adjusting buffer pointers, 12-13
A/D programming hints, 10-11
A/D value, switch gain, l2-14
ADOI-D analog to digital converter,
10-2
ADOI-D conversions, restricting the
number of, 10-11
AFCII analog-to digital converter,
10-1
AFCll, identical channel numbers
on the, 10-11
AFCII sampling rate, 10-11
Alphanumeric format (026 and 029),
8-11
ALUN$ macro, 1-16
Analog data, input of, lO-6, 11-18
Analog input channels, reading
sequential, 10-6, 11-19
Analog output, performing, 11-19
Analog-to-digital converter, 10-2,
11-8
Analog-to-digital converter, AFCll,
10-1
Analog-to digital converter drivers,
10-1, A-2
ASR-33/35 teletypes, 2-2
Assembly procedure for UDCOM.MAC,
11-10
Assigning a LUN, 1-16
Assigning a LUN to ADOl, 10-7
Assigning a LUN to AFOl, 10-7
Assigning a LUN to LSO, 12-14
Assigning a LUN to UDO, 11-20
AST service, terminating, 1~21
ASTX$S macro, 1-21
Asynchronous Line interface,
DLII-E, 9-2
Asynchronous process control I/O,
synchronous and, 10~4, 11-15
Asynchronous system trap, D-l
Attach, D-l
Attaching to an I/O device, 1-24

INDEX-l

Binary format, 8-12
Block, I/O status, D-2
Block length, 6-9
Block, logical, D-2
Block number, logical, D-3
Block, reading a logical, 1-25
Block, reading a virtual, 1-26
Block size, 5-12
Block, virtual, D-4
Block, writing a logical, 1-26
Block, writing a virtual, 1-27
Buffer, circular, 11-26, 11-27,11-32
Buffer management, 12-34
Buffer, output, 12-21
Buffer pointers, adjusting, 12-13
Buffer, reading data from an input,
12-20
'
Buffers, control and data, 10-10
Cancelling I/O requests, 1-25
Capabilities, functional, 8-10
Card input errors and recovery, 8-4
Card limitation~ input, 8-13
Card reader check recovery, ready
and, 8-7
Card reader data formats, 8-11
Card reader driver, A-2
Cassette driver, 6-1, A-2
Cassette I/O function codes,
specific, B-4
Cassette recovery procedures, 6-7
Cassette tape, structure of, 6-7
Changing LUN Assignments, 1-5
Channel numbers on the AFCll,
identical, 10-11
Channel, reading a single A/D, 12-12
Channels, reading sequential analog
input, 11-19
Characters, control, 2-8, 8-10
Characteristics, tape, 5-5
Checkpoihtable tasks, 11-31
Circular buffer, 11-26, 11-27,11-32
Clock and sampling rates, 12-33
Code conversion, ESCape, 2-12
Codes, directive, B-3
Codes, I/O function, B-3
Codes, return, 1-28
Codes, specific communication I/O
function, B-5
Common block, 11-14
Common block, linking a task to the
UDCll, 11-14

communication drivers, A-2
Communication I/O function codes,
specific, B-5
Communications drivers programming
example, 9-9
Communications drivers programming
hints, 9-8
Conditions, directive, 1-29
Conditions, I/O, status, 1-31
Contact interrupt data, reading,
11-26
Contact interrupt point, reading a,
11-25
Connecting to contact interrupts,
11-20
Connecting to timer interrupts,
11-21
Cont~ct interrupt digital input,
11-5
Contact interrupts, connecting to,
11-20
Contact interrupts, disconnecting
from, 11-22
Contact sense fields, reading
several, 11-23
Control and Data buffers, 10-10
Control characters, 2-8, 8-10
Control function, RT02-C, 2-13
Control word, A/D conversion, 10-3
Converter, ana1og-to-digita1,
11-8
Creating a global common block,
11-12
Creating the UDC11 driver, 11-1
Data formats, card reader, 8-11
DECtape driver, 4-1, A-3
DECtape I/O function codes,
specific, B-5
DEC tape recovery procedures, 4-7
DECtape transfers, 4-8
DECwriters, LA30, 2-2
DECwriter, LA36, 2-2
Defining the UDC11 configuration,
11-9
Detach, D-1
Detaching from an I/O device, 1-24
Device, attaching to an I/O, 1-24
Device, detaching from an I/O,
1-24
Device-specific QIO function,
4-4, 5~4, 6-3, 8-3, 9-5~ 10-2
11-4, 12-2
Device specific QIO functions
(synchronous), 12-4
Devices, RSX-11M, 1-2
DH11 asynchronous serial line
multiplexer, 2-12
DIll asynchronous serial line
interface, 2-12

Direct access, 11-8
Direction, speed considerations when
reversing, 4-9
Directive, D-1
Directive codes, B-3
Directive conditions, 1-29
Directive error codes, B-3
Directive, • MCALL, 1-15
Directive parameter blocks, 1-12
Directive success codes, B-3
Disconnecting from contact interrupts, 11-22
Disconnecting from timer interrupts, 11-23
Disk driver, 3-11, A-3
Disk, RF11/RS11 fixed-head, 3-1
Disk, RJP04 pack, 3-2
Disk, RJS03 fixed-head, 3-2
Disk, RJS04 fixed-head, 3-2
Disk, RK11/RK05 cartridge, 3-2
Disk, RP11-C/RP03 pack, 3-2
Display in LED lights, 12-20
DJ11 asynchronous serial line
multiplexer, 2-12
DL11-E asynchronous line interface,
9-2
DP11 synchronous line interface,
9-2
Driver services, UDC11, 11-2
DUll synchronous line interface, 9-3
End-of-fi1e and IO.SPF, 6-8
End-of-tape, logical, 6-9
Errors and recovery, card input,
8-4
Error codes, directive, B-3
Error codes, I/O status, B-1
Errors, IO.ADS and ADC, 12-32
ESCape code conversion, 2-12
Even-parity zero, writing and,
5-13
Event flag number, D-1
Event flag, waiting for an, 1-21
Events, significant, 1-10, D-3
Flag number, event, D-1
Floating-point, 12-14
Format, binary, 8-12
Format control, vertical, 7-6
Format, QIO macro, 1-7
Formats, card reader data, 8-11
Format (026 and 029), alphanumeric,
8-11
Fortran interface, 10-4, 11-14, 12-9
FORTRAN interface subroutines,
LPS11, 12-11
Fortran interface values, 10-10,
11-31, 12-32
Fortran subroutine summary, 10-5,
11-16

INDEX-2

Functional capabilities, 8-10
Functional capabilities, A/D, 10-10
Function, IO.ADS, 12-5
Function, IO.HIS, 12-6
Function, IO.LED, 12-3
Function, IO.MDA, 12-7
Function, IO.MDI, 12-7
Function, IO.MDO, 12-7
Function, IO.REL, 12-3
Function, IO.SDI, 12-4
Function, IO.SDO, 12-4
Function, IO.STP, 12-8
Functions, summary of, I/O, A-I
Gain A/D value, switch, 12-14
Gain ranges, use of A/D, 10-11
Get LUN information macro, 2-3, 3-2,
4-1, 5-2, 6-1, 7-2, 8-1, 9-3,
10-2, 11-3, 12-2
Global common block, 11-12
Global common block, creating a,
11-12
Glossary, D-l
GLUN$ macro, 1-18
Half-duplex considerations, 9-8
Hints, programming, 2-12, 4-8, 5-12,
6-8, 7-6, 8-13
Histogram sampling, 12-17
Identical channel numbers on the
AFCll , 10-11
Importance of rewinding, 6-8
Initializing a timer module, 11-28
Input and output, use of ADJLPS for,
12-35
Input buffer, reading data from an,
12-20
In-progress synchronous function,
12-21
Input card limitation, 8-13
Input, contact interrupt digital,
11-5
Input of analog data, 10-6, 11-18
Input, reading digital, 12-19
Interface, DIll asynchronous serial
line, 2-12
IO.ADS and ADC errors, 12-32
IO.ADS function, 12-5
IO.ATT, 1-24
I/O completion, 1-27
IO.DET, 1-24
I/O function and status codes,
B-1
I/O function codes, B-3
I/O function codes, specific A/D
converter, B-4

INDEX-3

I/O function codes, specific cassette,
B-4
I/O function codes, specific communication, B-5
I/O function codes, specific DECtape,
B-5
I/O function codes, specific magtape,
B-6
I/O function codes, specific LPS, B-5
I/O function codes, specific UDC, B-6
I/O function codes, standard, B-4
I/O functions, standard, 1-23
I/O functions, summary of, A-I
IO.HIS function, 12-6
IO.INL, 9-9
IO.KIL, 1-25
IO.LED function, 12-3
IO.INL QIO functions, 9-6
IO.MDA function, 12-7
IO.MDI function, 12-7
IO.MDO function, 12-7
I/O, Overview of RSX-IIM, 1-1
I/O related macros, 1-13
IO.REL function, 12-3
I/O requests, cancelling, 1-25
I/O request, issuing an, 1-5, 1-15
IO.RLB, 1-25
IO.RNS QIO function, 9-6
IO.RVB, 1-26
IO.RWU, 5-4
IO.SDI function, 12-4
IO.SDO function, 12-4
IO.SEC, 5-5
IO.SPB and IO.SPF, space functions,
6-9
IO.SPF, end-of-file and, 6-8
IO.SPF, space functions, IOLSPB and,
6-9
I/O status block, 12-33, D-2
I/O status conditions, 1-31, 8-8
I/O status codes, B-1
I/O status error codes, B-1
I/O status success codes, B-3
IO.STP function, 12-8
I/O status word, 12-31
I/O, synchronous and asynchronous
process control, 11-15
IO.SYN QIO function, 9-6
IO.TRM QIO functions, 9-6
IO.WLB, 1-26
IO.WNS QIO function, 9-6
IO.WVB, 1-27
ISB status array, the, 10-4, 12-9
Isb status array, 11-15
Issuing an I/O request, 1-5, 1-15

Keys, special, 2-8, 2-9
KSR-33/35 teletypes. 2-2

Laboratory peripheral system driver,
12-1, A-3
Latching an output relay, 12-22
Latching digital output, 11-8
Latching or unlatching several
fields, 11-24
LA30 DECwriters, 2-2
LA36 DECwriter, 2-2
LED lights, displaying in, 12-20
Length, block, 6-9
Library, system object module,
11-12
Lights, displaying in LED, 12-20
Line printer driver, 7-1, A-4
Linking a task to the UDC11 common
block, 11-14
Logical address, D-2
Logical block, reading a, 1-25
Logical block number, D-3
Logical block, writing a, 1-26
Logical end-of-tape, 6-9
Logical Unit Number, 1-4, D-3
Logical unit table, 1-4
Logical units, 1-3
Low-traffic sync character considerations, 9-8
LS11 line printer, 7-2
LPS I/O function codes, specific,
B-5
LPS11, FORTRAN interface subroutines,
12-11
LP11 line printer, 7-2
LPS status returns, 12-27
LUN, assigning a, 1-16
LUN assignments, changing, 1-5
LUN information, retrieving, 1-18
LUN information macro, get, 9-3,
10-2, 11-3, 12-2
LUN to AD01, assigning a, 10-7
LUN to AF01, assigning a, 10-7
LUN to LSO, assigning a, 12-14
LUN to UDO, assigning a, 11-20
LVII line printer, 7-2
Message-oriented communication
drivers, 9-1
Macro, D-3
Macro, get LUN information, 2-3,
3-2, 4-1, 5-2, 6-1, 7-2, 8-1
Macro,
ALUN$, 1-16
ASTX$S, 1-21
GLUN$, 1-18
WTSE$, 1-21
QIO$, 1-15
Macros, I/O-related, 1-13
Magtape I/O function codes, specific,
B-6
Magnetic tape drivers, 5-1, A-4
.MCALL directive, 1-15

Multiplexer, DH11 asynchronous serial
line, 2-12
Multiplexer, DJ11 asynchronous serial
line, 2-12
Number, logical block, D-3
Number, logical unit, 1-4, D-3
Numbering conventions, 11-31
Number of AD01-D conversions,
restricting the, 10-11
Operator interventions, 5-4
Output buffer, 12-21
Output, latching digital, 11-8
Output relay, latching an, 12-22
Output, synchronous D/A, 12-24
Output, synchronous digital, 12-26
Output, writing digital, 12-19
Output, use of ADJLPS for input
and, 12-35
Overview of RSX-11M I/O, 1-1
Parameter blocks, directive, 1-12
Parity support, vertical, 9-8
Performing analog output, 11-19
Print line truncation, 7-7
Printer, LP11 line, 7-2
Printer, LS11 line, 7-2
Printer, LVII line, 7-2
Priority, D-3
Process control I/O, synchronous
and asynchronous, 10-4, 11-15
Programrriing example, communications
drivers, 9-9
Programming hints, 2-12, 4-8, 5-12,
6-8, 7-6, 8-13
Programming hints, A/D, 10-11
Programming hints, communication
drivers, 9-8
Programming hints, UDC11, 11-31
Pulsing several fields, 11-24

QIO$ Macro, 1-15
QIO macro, 2-5, 3-3, 4-2, 5-3, 6-2,
7-3, 8-2, 9-4, 10-2, 11-3
QIO Macro format, 1-7
QIO functions, device-specific, 4-4
5-4, 6-3, 8-3, 10-2, 11-4, 12-2,
12-8
QIO functions,
IO.INL, 9-6
IO.RNS, 9-6
IO.SYN, 9-6
IO.WNS, 9-6
QIO functions, standard, 4-2, 5-2,
6-3, 8-2, 9-4, 10-2, 11-3, 12-2
QIO functions, (synchronous), devicespecific, 12-4

INDEX-4

Rate, AFCll, sampling, 10-11
Rates, clock and sampling, 12-32
Reading a contact interrupt point,
11-25
Reading a logical block, 1-25
Reading a single A/D channel, 12-12
Reading a timer module, 11-27
Reading a virtual block, 1-26
Reading contact interrupt data,
11-26
Reading data from an input buffer,
12-20
Reading digital input, 12-19
Reading sequential analog input
channels, 10-6, 11-19
Reading several contact sense
fields, 11-23
Reading timer interrupt data, 11-27
Reads and writes, retry procedures
for, 5-12
Ready and card reader check
recovery, 8-7
Ready recovery, 7-5
Recovery, card input errors and,
8-4
Recovery procedures, cassette, 6-7
Recovery procedures, DECtape, 4-7
Recovery, ready, 7-5
Recovery, ready and card reader
check, 8-7
Recovery, select, 4-8, 5-12
Redundancy checking, 9-8
Relay, latching an output, 12-22
Resetting tape characteristics,
5-13
Restricting the number of AD01-D
conversions, 10-11
Retrieving LUN information, 1-18
Retrieving system macros, 1-15
Retry procedures for reads and
writes, 5-12
Return codes, 1-28
Returns, status, 2-6, 3-4, 4-4,
5-9, 6-4, 7-4, 8-4
Reverse reading and writing, 4-8
Reversing direction, speed
considerations when, 4-9
Rewinding, importance of, 6-8
RFll/RSll fixed-head disk, 3-1
RJP04 pack disk, 3-2
RJS03 fixed-head disk, 3-2
RJS04 fixed-head disk, 3-2
RKll/RK05 cartridge disk, 3-2
RPll-C/RP03 pack disk, 3-2
RSX-1lM Devices, 1-2
RSX-1lM I/O, Overview of, 1-1
RT02 alphanumeric display terminal,
2-3
RT02-C badge reader/alphanumeric
display terminal, 2-3
RT02-C control function, 2-13
RUBOUT character, 7-6

Sampling, histogram, 12-17
Sampling rate, AFCl1, 10-11
Sampling rates, clock and, 12-33
Sampling, synchronous A/D, 12-22
Sampling, synchronous digital
input, 12-15
Schmitt trigger, 12-6
Select recovery, 4-8, 5-12
Significant event, 1-10, D-3
Single A/D channel, reading a,
12-12
Size, block, 5-12
Space functions, IO.SPB and IO.SPF,
6-9
Special keys, 2-8, 2-9
Specific A/D converter I/O function
codes, B-4
Specific cassette I/O function codes,
B-4
Specific communication I/O function
codes, B-5
Specific DECtape I/O function codes,
B-5
Specific LPS I/O function codes, B-5
Specific magtape I/O function codes,
B-6
Specific UDC I/O function codes, B-6
Speed considerations when reversing
direction, 4-9
Standard I/O functions, 1-23
Standard I/O function codes, B-4
Standard QIO functions, 4-2, 5-3,
6-3, 8-2, 9-4, 10-2, 11-2, 12-2
Status array, ISB, 12-9
Status block, I/O, 12-33, D-2
Status codes, I/O, B-1
Status codes, I/O function and, B-1
Status condition, I/O, 1-31, 8-8
Status error codes, I/O, B-1
Status returns, 2-6, 3-4, 4-4, 5-9
6-4, 7-4, 8-4, 9-7
Status returns, A/D converter, 10-8
Status returns, LPS, 12-27
Status returns, UDCll, 11-28
Status success codes, I/O, B-3
Status word, I/O, 12-31
Structure of cassette tape, 6-7
Success codes, Directive, B-3
Success codes, I/O status, B-3
Summary of I/O functions, A-I
Switch gain .A/D value, 12-14
Symbols defined by UDCOM.MAC, 11-10
Sync character considerations, lowtraffic, 9-8
Synchronous A/D sampling, 12-22
Synchronous and asynchronous process
control I/O, 10-4, 11-15
Synchronous D/A output, 12-24
Synchronous, device-specific QIO
functions, 12-4
Synchronous digital input sampling,
12-15

INDEX-5

Synchronous digital output, 12-26
Synchronous function, in-progress~
12-21
Synchronous line interface, DPll, 9-2
Synchronous line interface, DUll,
9-3
Synchronous subroutines, 12-10
Synchronous system trap, D-4
System macros, retrieving, 1-15
System object module library, 11-12
System traps, 1-11
System trap, synchronous, D-4
Table, logical unit, 1-4
Tape characteristics, 5-5
Tape characteristics, resetting,
5-13
Tape, structure of cassette, 6-7
Tape, TJ16 magnetic, 5-2
Tape, TMll magnetic, 5-2
Teletypes, ASR-33/35
Teletypes, KSR-33/35
Terminal driver, 2-1, A-5
Terminal line truncation, 2-12
Terminal, RT02 alphanumeric display,
2-3
Terminal, RT02-C badge reader/
alphanumeric display, 2-3
Terminal, VT50 alphanumeric
display, 2-3
Terminal, VT05B alphanumeric
display, 2-3
Terminating AST service, 1-21
The Isb status array, 10-4
Timer, 11-7
Timer interrupt data, reading,
11-27
Timer interrupts, connecting to,
11-21
Timer interrupts, disconnecting
from, 11-23
Timer module, initializing a, 11-28
Timer module, reading a, 11-27
TJlO magnetic tape, 5-2
TMll magnetic tape, 5-2
Transmission validation, 9-8
Trap, asynchronous system, D-l
Trap, synchronous system, D-4
Traps, System, 1-1
Truncation, print line, 7-7

INDEX-6

UDC I/O function codes, specific, B-6
UDCll configuration, defining the,
11-9
UDCll driver, creating the, 11-1
UDCll driver services, 11-2
UDCll modules, accessing, 11-2
UDCll programming hints, 11-31
UDCll status returns, 11-28
UDCll symbolic definitions, 11-12
Unit number, logical, D-3
Universal digital controller driver,
11-1, A-5
Unlatching several fields, latching
ori 11-24
Use of A/D gain ranges, 10~11
Use of ADJLPS for input and output,
12-35
Verification of write operations,
6-9
Vertical format control, 7-6
Vertical parity support, 9-8
Virtual address, D-4
Virtual block, D-4
Virtual block, reading a, 1-26
Virtual block, writing a, 1-27
VT50 alphanumeric display terminal,
2-3
VT05B alphanumeric display terminal,
2-3
Waiting for an event flag, 1-21
Write operations, verification of,
6-9
Writes, retry procedures for reads
and, 5-12
Writing a logical block, 1-26
Writing and even-parity zero, 5-13
Writing a virtual block, 1-27
Writing digital output 12-19
Writing, reverse reading and, 4-8
WTSE$ macro, 1-21
fj

HOW TO OBTAIN SOFTWARE INFORMATION
SOFTWARE NEWSLETTERS, MAILING LIST
The Software Communications Group, located at corporate headquarters in
Maynard, publishes software newsletters for the various DIGITAL products.
Newsletters are published monthly, and keep the user informed about customer software problems and solutions, new software products, documentation corrections, as well as programming notes and techniques.
There are two similar levels of service:
The Software Dispatch
The Digital Software News
The Software Dispatch is part of the Software Maintenance Service.
service applies to the following software products:

This

PDP-9/15
RSX-IID
DOS/BATCH
RSTS-E
DECsystem-IO
A Digital Software News for the PDP-ll and a Digital Software News for
the PDP-8/12 are available to any customer who has purchased PDP-ll or
PDP-8/12 software.
A collection of existing problems and solutions for a given software
system is published periodically. A customer receives this publication
with his initial software kit with the delivery of his system. This
collection would be either a Software Dispatch Review or Software Performance Summary dep~nding on the system ordered.
A mailing list of users who receive software newsletters is also maintained by Software Communications. Users must sign-up for the newsletter they desire. This can be done by either completing the form supplied with the Review or Summary or by writing to:
Software Communications
P.O. Box F
Maynard, Massachusetts 01754
SOFTWARE PROBLEMS
Questions or problems relating to DIGITAL's software should be reported
as follows:
North and South American Submitters:
Upon completion of Software Performance Report (SPR) form remove last
copy and send remainder to:
-Software Communications
P.O. Box F
Maynard, Massachusetts 01754
The acknowledgement copy will be returned along with a blank SPR form
upon receipt. The acknowledgement will contain a DIGITAL assigned SPR
number.
The SPR number or the preprinted number should be referenced in
any future correspondence. Additional SPR forms may be obtained from
the above address.
All International Submitters:
Upon completion of the SPR form, reserve the last copy and send the remainder to the SPR Center in the nearest DIGITAL office. SPR forms are
also available from our SPR Centers.
PROGRAMS AND MANUALS
Software and manuals should be ordered by title and order number.
United States, send orders to the nearest distribution center.

In the

Digital Equipment Corporation
Digital Equipment Corporation
Software Distribution Center
Software Distribution Center
146 Main Street
1400 Terra Bella
Maynard, Massachusetts 01754
Mountain View, California 94043
Outside of the United States, orders should be directed to the nearest
Digital Field Sales Office or representative.
USERS SOCIETY
DECUS, Digital Equipment Computers Users Society, maintains a user exchange center for user-written programs and technical application information. The Library contains approximately 1,900 programs for all
DIGITAL computer lines. Executive routines, editors, debuggers, special
functions, games, maintenance and various other classes of programs are
available.
DECUS Program Library Catalogs are routinely updated and contain lists
and abstracts of all programs according to computer line:
PDP-8, FOCAL-8, BASIC-8, PDP-12
PDP-7/9, 9, 15
PDP-II, RSTS-ll
PDP-6/l0, 10
Forms and information on acquiring and submitting programs to the DECUS
Library may be obtained from the DECUS office.
In addition to the catalogs, DECUS also publishes the following:
DECUSCOPE
-The Society's technical newsletter, published bi-monthly,
aimed at facilitating the interchange of technical information among users of DIGITAL computers and at disseminating news items concerning the Society. Circulation reached 19,000 in May, 1974.
PROCEEDINGS OF
-Contains technical papers presented at DECUS Symposia
THE DIGITAL
held twice a year in the united States, once a year
EQUIPMENT USERS
in Europe, Australia, and Canada.
SOCIETY
MINUTES OF THE
-A report of the DECsystem-lO sessions held at the two
DECsystem-lO
united States DECUS Symposia.
SESSIONS
COPY-N-Mail
-A monthly mailed communique among DECsystem-lO users.
-Mailing of Local User Group (LUG) and Special Interest
LUG/SIG
Group (SIG) communique, aimed at providing closer
communication among users of a specific product or
application.
Further information on the DECUS Library, publications, and other DECUS
activities is available from the DECUS offices listed below:
DECUS
Digital Equipment Corporation
146 Main Street
Maynard, Massachusetts 01754

DECUS EUROPE
Digital Equipment Corp. International
(Europe)
P.O. Box 340
1211 Geneva 26
Switzerland

(

RSX-llM I/O Drivers Reference
Manual
DEC-ll-OMDRA-A-D

READER'S COMMENTS
NOTE:

This form is for document corrments only. Problems
with software should be reported on a Software
Problem Repcrt (SPR) form (see the HOW TO OBTAIN
SOFTWARE INFOR!v1ATION page).
,

Did you find errors in this manual?

If so, specify by page.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.
[] Assembly language programmer
[]

Higher-level language programmer

[] Occasional programmer (experienced)
[] User with little programming experience
[]

Student programmer

[] Non-programmer interested in computer concepts and capabilities
Name

Date __________________________

Organization _________________________________________________________________
Street _______________________________________________________________________
City _____________________________ State ______________ Zip Code _______________
or
Country
If you do not require a written reply, please check here.

[]

.------------------------------------------------------------Fold lIere------------------------------------------------------------

.----------------------------------------------- Do Not Tear - Fold lIere and Staple -----------------------------------------------

FIRST CLASS
PERMIT NO. 33
MAYNARD, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

Postage will be paid by:

Software Communications
P. O. Box F
Maynard, Massachusetts 01754