Pseudo Terminal release notes
This document briefly describes a VAX/VMS Pseudo Terminal. It
contains information about the device, a programming chapter, user
interface section, and instructions on compiling and installing
the drivers.
Contents
CHAPTER 1 INTRODUCTION 1-1
1.1 USES OF PTYS 1-1
1.2 CONCEPT OF CONTROL AND TERMINAL DEVICE 1-2
1.3 SIMILARITIES BETWEEN PTYS AND TERMINALS 1-2
1.4 DIFFERENCES BETWEEN PTYS AND TERMINALS 1-3
1.4.1 Device Characteristics 1-3
1.4.2 Device Type 1-4
1.4.3 Device Class 1-4
1.4.4 TW Unit Number 1-4
CHAPTER 2 USING THE PTY 2-1
2.1 CREATING A PTY 2-1
2.2 READING DATA 2-2
2.3 WRITING DATA 2-3
2.4 SPECIAL SIGNALS 2-4
2.5 PROBLEMS 2-4
CHAPTER 3 PTY FUNCTION CODES 3-1
3.1 READ 3-1
3.2 WRITE 3-2
3.3 SET MODE AND SET CHARACTERISTICS 3-3
3.4 SENSE MODE AND SENSE CHARACTERISTICS 3-4
3.5 I/O STATUS BLOCK 3-5
iii
Contents
CHAPTER 4 BUILDING AND INSTALLING THE PTY 4-1
4.1 COMPILING SOURCES 4-1
4.2 INSTALLING THE DEVICES 4-2
FIGURES
3-1 Sense Mode and Characteristics Buffer 3-5
3-2 IOSB Contents - Read and Write Function 3-5
3-3 IOSB Contents - Set Mode and Characteristics
Functions 3-6
3-4 IOSB Contents - Sense Mode and Characteristics
Functions 3-6
iv
Chapter 1
Introduction
This chapter describes the use of the VAX/VMS Pseudo Terminal
Driver as implemented at Carnegie-Mellon University Computer
Science Department. Additional information about VMS device
drivers and the VMS operating system interface can be found in
VAX/VMS I/O User's Guide, and in VAX/VMS System Service Reference
Manual.
1.1 Uses of PTYs
There is no device from DEC which suffices for remote logins when
using non-DECnet protocols. The remote terminal driver expects the
remote node to do the local line editing. This includes delete,
control-o, control-s, control-q, and many other capabilities. PTYs
handle the local line editing locally. When the line editing is
done locally, the remote machine has to know much less about VMS
and its terminal handling conventions.
Introduction 1-1
1.2 Concept of Control and Terminal Device
A single PTY consists of two devices, a control and a terminal de-
vice. The terminal device is the device that acts like a terminal.
The control device on VMS is named ``PYAx:''. For example, a
PTY control device could be named ``PYA1:''. The terminal de-
vice portion of the PTY is name ``TWAx:''. The terminal device
``TWA1:'' is the mate to the control device ``PYA1:''. Similarly,
the control device ``PYA5:'' is the mate to the terminal device
``TWA5:''.
1.3 Similarities Between PTYs and Terminals
The terminal portion of a PTY behaves very much like a regular
VAX/VMS terminal. The terminal portion of a PTY has:
o Type-ahead
o Specifiable or default line terminators
o Special operating modes, such as NOECHO and PASSALL
o American National Standard escape sequence detection
o Terminal/mailbox interaction
o Terminal control characters such as Sontrol-S and control-q
for starting and stopping output, Control-O for discarding
output, and all other special characters that are handled by
the VAX/VMS terminal driver.
o Limited full-duplex operation (simultaneously active read and
write requests)
o The device characteristics are inherited from the system de-
fault parameters with the following exceptions:
- The device is always forced to HOSTSYNC.
1-2 Introduction
- The device is set to NOMODEM and cannot ever be set to
MODEM.
1.4 Differences Between PTYs and Terminals
The difference between a VAX/VMS terminal and the terminal portion
of a PTY is where the input comes from and where the output goes
to. On a VAX/VMS terminal, the input comes from an actual terminal
and the output goes to an actual terminal. On a PTY the input
comes from the control device and the output goes to the control
device. In order to simulate someone typing at the terminal device
``TWA5:'' we must write to the control device ``PYA5:''. In order
to read what has been typed out to the terminal device ``TWA5:''
we must read from the control device ``PYA5:''. PTYs are like
terminals that only software can access.
PTYs are virtual devices. When allocating a PTY, they behave much
like mailboxes or network devices. To allocate a PTY, simply
allocate the first one ('PYA0:'). The allocating routine will
create a new PTY and assign it to you. The PTY will be deallocated
when no process is referencing the device.
1.4.1 Device Characteristics
A PTY control device has the following characteristics.
o DEV$M_AVL - On line and available
o DEV$M_IDV - Capable of input
o DEV$M_ODV - Capable of output
o DEV$M_REC - Record oriented
A PTY control device does not have the following characteristics.
o DEV$M_CCL - Carriage Control
Introduction 1-3
o DEV$M_TRM - Terminal Device
1.4.2 Device Type
The device type is DT$_PY. Since a PTY is a nonstandard device,
you will probably not find the correct macros, literals or con-
stants for this device type. This field should have a value of
0.
1.4.3 Device Class
The device class is DC$_PY. Since a PTY seems to be such an odd
creature, this field should be FF in hex, or 177 in octal.
1.4.4 TW Unit Number
The unit number of the TW device is the same as the unit number of
the associated PT device.
1-4 Introduction
Chapter 2
Using the PTY
This chapter will present information on using the PTY. It covers
creating the device, reading, writing data, and using additional
signaling information. Finally it covers a minor deficiency of the
existing implementation.
2.1 Creating a PTY
Make sure the two drivers are loaded as PYA0: and TWA0:. Then,
just assign a channel to PYA0:, this will create a PYAn: and a
TWAn: (the unit numbers just go up). Anything you write to that
channel appears on the TWAx: as if typed at a terminal. Any output
to the terminal TWAn: is available to be read from PYAn:. The
devices do flow control between one another and all buffering. So,
you can just read, for example, with a 100 char buffer from PY and
the read will complete with whatever number of characters the QIO
to the PTY terminal had, anywhere from 1 to MAXBUF. If the QIO to
the PTY had more chars than your read buffer, it'll just fill the
read buffer and return, and you can get the rest on the next read.
It is very simple to use.
Also, if you assign a mailbox with the PYAn: device (use LIB$ASN_
WTH_MBX when assigning channel to PYA0:) you will get a MSG$_
TRMHANGUP see the VMS I/O User's Reference Manual: Part I for
the format of the message in the mailbox whenever the terminal
Using the PTY 2-1
is hung-up. A hang-up occurs when a process logouts out or it or
deassigns the last channel to the device. It works just like the
HANGUP on terminals with modem signals. You can even ignore the
hangup message if you want, it only generates the message in the
mailbox, you can continue to use the device if you choose after
getting the message.
Should you deassign the PYAn: device, a DISCONNECT will be forced
on any process using the TWAn: device, just like dropping carrier
on a modem line. If you have the TT2$M_DISCONNECT bit set in the
default terminal characteristics (TTY_DEFCHAR2 in SYSGEN), then
you will get a virtual terminal upon logging into a TWAn: device.
Then you get CONNECT/DISCONNECT to work. Really nice on network
connections.
Note that, just as with normal VMS terminals, you will only get
a VTAn: if the line has the DISCONNECT terminal characteristic
before you log into it, and only if you use LOGINOUT to start a
process on the terminal. Just sending a <CR> into the device as
the first character will start up LOGINOUT like a normal terminal.
2.2 Reading data
A read from the the PY device is used to accept data from the
TW device. The largest read operation possible is limited by the
value of SYSGEN parameter MAXBUF. The read request will complete
with a minimum of 1 character and maximum of the number characters
the buffer can hold. The read operation will only complete when
the TW driver has one or more characters to output. If at the time
you issue a read request no data is available this request will
be queued and completed at a later time. The PY device accepts
all three read function codes, but unlike the TW device treats all
three exactly the same. Note, that the system will still require
that you have the correct privileges to use them.
2-2 Using the PTY
When writing a control program for the PTY, care should be taken
to insure that a read request is always queued to the PY device.
Failure to do so can cause excessive delays in processing on the
TW device.
2.3 Writing data
A write to the PY device is used to input data to the TW device.
The largest write operation possible is limited by the value of
the SYSGEN parameter MAXBUF. It is not recommended that vary large
write requests be issued. It is possible by using very large I/O
requests to flood the TW devices input buffer. When this occurs
data will be lost without an error being reported. Note the driver
has been optimized for write requests of 1 to 32 bytes. Larger
requests will work but require more work on the part of the driver
to setup and process.
The current version of the driver has taken steps to help pre-
vent the data over-run condition described above. It does this
by setting the TW device to send and XOFF message if its type-
ahead buffer it getting full. Once this occurs, the PY device
will return a status of SS$_DATAOVERUN with the actual number of
characters input. This is sufficient to prevent a single request
from flooding the type-ahead buffer. If a program makes repeated
attempts to insert data after receiving this message it can flood
the terminal type-ahead buffer. This occurs because the driver
always inserts one character before checking to see if TW driver
is accepting data. Because the class driver does not tell the in-
put routine that it rejected the character, it is not possible to
report this real loss of data. One final note: if for some reason
the TW device clears the HOSTSYNC characteristic the driver will
no longer report the impending data overrun condition.
Using the PTY 2-3
2.4 Special signals
Certain class driver events such as stopping and resuming input,
stopping and resuming output, and altering the device characteris-
tics, are of interest to the control program. This version of the
PTY SUPPLIES a notification mechanism for three of these events.
It provides notification for stopping and starting input; and for
notification when the device characteristics change. The control
program will have the supplied AST routine called when one these
events occur.
By making use of the start and stop input ASTs, and the SS$_
DATAOVERUN return stauts the control program can avoid flooding
the TW devices type-ahead buffer. Note, that these signals will
be returned even if HOSTSYNC is cleared. These AST can be enabled
by using the IO$_SETMODE, or the IO$_SETCHAR function on the PY
DEVICE. The ASTs will not accept an AST parameter, instead they
return the class driver signal character as the AST parameter.
Finally, the control, program by using the AST delivered the the
TW device, changes characteristics along with the IO$_SENSExxxx
function to track the TW device characteristics.
2.5 Problems
A minor problem exists and is actually a side-effect of the driver
being cautious in order to prevent possible problems. If you have
a virtual terminal associated with the pseudo-terminal, and you
deassign the last channel to the control device (the PY device)
a DISCONNECT is forced on any process on the terminal (the TW
device) and the PY and TW are both deleted. In this case, the TW
will not be deleted, although the PY will and the TW be marked
as OFFLINE. This is because the driver relies on VMS to do the
actual delete of the device. VT's alter the way device reference
counts work, and VMS never gets around to deleting the device.
It is marked for delete, so anything you do (like SHOW TERM) will
cause it to be deleted. This could be fixed by deleting the device
2-4 Using the PTY
explicitly after forcing the DISCONNECT, however it is very hard
to prevent the use of the UCB and thus cause a system crash. Note
that it doesget deleted correctly if you do not have a virtual
terminal associated with the PTY, or if you have no processes
active on the PTY when the PY and TW are to be deleted.
Using the PTY 2-5
Chapter 3
PTY Function Codes
The function codes for the terminal device portion of a PTY are
exactly the same as those for regular VAX/VMS terminals. For more
information on VAX/VMS terminal I/O see VAX/VMS I/O User's Guide.
The basic function of the control portion of a PTY are read, write
and set mode or characteristics.
A user does not need to have assigned the PTY terminal device
in order to do I/O operations on the PTY control device. If the
terminal device has type ahead enabled, sending the right charac-
ters to the control device will send a message to OPCOM to start
running SYS$SYSTEM:LOGINOUT.EXE on the terminal device.
3.1 Read
The basic purpose of a PTY control device read is to transfer
data from the output buffer of the PTY terminal device to a user
specified buffer. There are three read functions which a user can
apply to a PTY control device.
o IO$_READVBLK - Read virtual block
o IO$_READLBLK - Read logical block
o IO$_READPBLK - Read physical block
PTY Function Codes 3-1
A read is complete if either of the below conditions occur:
o The user specified buffer is full
o At least one character is available from the PTY terminal
device
The read function codes can take the following device/function
dependent arguments:
o P1 = The starting virtual address of the buffer that is to
receive the data read
o P2 = The size of the buffer in bytes that is to receive the
data read
o P3, P4, P5, P6 = ignored
3.2 Write
The basic purpose of a PTY control device write is to transfer
data from the user specified buffer to the type-ahead buffer of
the PTY terminal device. There are three write functions which a
user can apply to a PTY control device.
o IO$_WRITEVBLK - write virtual block
o IO$_WRITELBLK - write logical block
o IO$_WRITEPBLK - write physical block
The write function codes can take the following device/function
dependent arguments:
o P1 = The starting virtual address of the buffer that is to be
written to the PTY terminal device
o P2 = The number of bytes that are to be sent
o P3, P4, P5, P6 = Ignored
3-2 PTY Function Codes
3.3 Set Mode and Set Characteristics
The SETMODE and SETCHAR functions allow the programmer to enable
three special event notification ASTs. These special events have
been discussed in detail in the previous chapter. The driver
treats both of these funtion code identically but the VMS QIO(W)
dispatcher will require the PHY_IO privilege if you use choose to
use the IO$_SETCHAR function.
o IO$_SETMODE
o IO$_SETCHAR
These functions take the following device/function dependent
arguments.
o P1 = address of characteristics buffer
o P2 = For XON and XOFF ASTs the program can provide a 16 bit AST
parameter. When the AST is delivered the high order 16 bits of
the AST parameter will be XON, XOFF, or bell character. For the
notification of TW characterisitcs changing the AST parameter
can be a full long word (32-bits).
o P3 = access mode to deliver AST (maximized with the caller's
access mode)
o P4 = type of AST to be queued. (1 = XON AST notification,
2 = XOFF AST notification, and 3 = terminal characteristics
changed)
o P5, P6 = ignored
PTY Function Codes 3-3
3.4 Sense Mode and Sense Characteristics
The two function codes to sense the mode of the PTY control device
are:
o IO$ SENSEMODE
o IO$ SENSECHAR
The IO$ SENSEMODE function returns the process-associated, that
is temporary, characteristics of the terminal device. The IO$
SENSECHAR function returns the permanent characteristics of the
terminal device. The IO$_SENSEMODE function is a logical func-
tion and requires no privilege. The IO$_SENSECHAR function is a
physical function and requires the PHY_IO privilege use it.
These function codes take the following device/function dependent
arguments.
o P1 = address of an 8 or 12 byte characteristics buffer
o P2 = size of characteristics buffer (eight is the default)
o P3, P4, P5, P6 = ignored
The P1 argument points to a quadword block which is the same for-
mat as the Set Mode Characteristics Buffer, shown in Figure 3-1.
3-4 PTY Function Codes
Figure 3-1: Sense Mode and Characteristics Buffer
__________________________________________________________________
31 24 23 16 15 8 7 0
-----------------------------------------------------
| Page Width | Type | Class |
-----------------------------------------------------
| Page Length| Basic Characteristics |
-----------------------------------------------------
| Extended Characteristics |
_____________-----------------------------------------------------
Figure 3-2: IOSB Contents - Read and Write Function
__________________________________________________________________
31 24 23 16 15 8 7 0
-----------------------------------------------------
| Byte Count | Status |
-----------------------------------------------------
| Unused |
-----------------------------------------------------
__________________________________________________________________
3.5 I/O Status Block
The I/O status block formats for read, write, set mode and sense
mode I/O functions are shown in Figure 3-2, 3-3 and 3-4.
The status indicates the success or failure of the specified
operation. Below are possible values for the status field:
o SS$_ABORT - The operation was canceled by the Cancel I/O on
Channel ($CANCEL) system service. Applicable only if the drive
was actively involved in an operation.
PTY Function Codes 3-5
Figure 3-3: IOSB Contents - Set Mode and Characteristics
Functions
__________________________________________________________________
31 24 23 16 15 8 7 0
-----------------------------------------------------
| Unused | Status |
-----------------------------------------------------
| Unused |
_____________-----------------------------------------------------
Figure 3-4: IOSB Contents - Sense Mode and Characteristics
Functions
__________________________________________________________________
31 24 23 16 15 8 7 0
-----------------------------------------------------
| Rcv Speed | Xmit speed | Status |
-----------------------------------------------------
| Unused |parity flags| LF fill | CR fill |
-----------------------------------------------------
__________________________________________________________________
o SS$_ACCVIO - The specified buffer is not accessible to the
specified process
o SS$_BADPARAM - An illegal value was supplied in P4 for a set
request.
o SS$_DATAOVERUN - The TW device has stopped accepting data. The
byte count indicates the number of characters accepted by the
terminal.
o SS$_NORMAL - Successful Completion.
o SS$_NOSUCHDEV - The TW device no longer exists.
3-6 PTY Function Codes
Chapter 4
Building and Installing the PTY
In VAX/VMS V5.0, several pieces of software support the terminal
interface. The hardware independent portion is SYS$SYSTEM:TTDRIVER.EXE.
This version of the PTY does not require any changes or patches to
this code. PTY drivers consist of two device drivers, TWDRIVER.EXE
for the terminal portion of the PTY's, and PYDRIVER.EXE for the
control portion. In order to have a working PTY you must build and
install both pieces.
4.1 Compiling Sources
There are several pieces of source code that make up PTY drivers.
PYDRIVER.MAR is the source for the control portion. TWDRIVER.MAR
is the source for the terminal portion.
The commands for compiling and linking the devices are:
Building and Installing the PTY 4-1
$ ! Compile the drivers
$ MACRO /LIST /OBJECT TWDRIVER.MAR
$ MACRO /LIST /OBJECT PYDRIVER.MAR
$ ! Link the drivers
$ LINK /MAP /FULL /CROSS -
TWDRIVER,SYS$SYSTEM:SYS.STB/SELECTIVE,SYS$INPUT:/OPTION
BASE=0
$ LINK /MAP /FULL /CROSS -
PYDRIVER,SYS$SYSTEM:SYS.STB/SELECTIVE,SYS$INPUT:/OPTION
BASE=0
4.2 Installing the Devices
To load a PTY, login to a privileged account and issue the follow-
ing commands.
$ RUN SYS$SYSTEM:SYSGEN
LOAD device:[directory]TWDRIVER
LOAD device:[directory]PYDRIVER
CONNECT TWA0/NOADAPTER/DRIVER=TWDRIVER
CONNECT PYA0/NOADAPTER/DRIVER=PYDRIVER
Don't try to use PTB0 or PYB0. The code is not built to handle
these. It is only built to handle the PYA and TWA control and
terminal devices.
4-2 Building and Installing the PTY