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