KVC@BUSTER.NRC.COM (Kevin Carosso) (06/22/88)
+-+-+-+ Beginning of part 2 +-+-+-+
X Science Department. Additional information about VMS device
X drivers and the VMS operating system interface can be found in
X VAX/VMS I/O User's Guide, and in VAX/VMS System Service Reference
X Manual.
X
X
X 1.1 Uses of PTYs
X
X There is no device from DEC which suffices for remote logins when
X using non-DECnet protocols. The remote terminal driver expects the
X remote node to do the local line editing. This includes delete,
X control-o, control-s, control-q, and many other capabilities. PTYs
X handle the local line editing locally. When the line editing is
X done locally, the remote machine has to know much less about VMS
X and its terminal handling conventions.
X
X
X
X
X
X
X
X
X
X
X Introduction 1-1
X`012
X
X
X
X
X
X
X
X
X 1.2 Concept of Control and Terminal Device
X
X A single PTY consists of two devices, a control and a terminal de-
X vice. The terminal device is the device that acts like a terminal.
X
X The control device on VMS is named ````PYAx:''. For example, a
X PTY control device could be named ````PYA1:''. The terminal de-
X vice portion of the PTY is name ````TWAx:''. The terminal device
V ````TWA1:'' is the mate to the control device ````PYA1:''. Similar
Xly,
X the control device ````PYA5:'' is the mate to the terminal device
X ````TWA5:''.
X
X
X 1.3 Similarities Between PTYs and Terminals
X
X The terminal portion of a PTY behaves very much like a regular
X VAX/VMS terminal. The terminal portion of a PTY has:
X
X o Type-ahead
X
X o Specifiable or default line terminators
X
X o Special operating modes, such as NOECHO and PASSALL
X
X o American National Standard escape sequence detection
X
X o Terminal/mailbox interaction
X
X o Terminal control characters such as Sontrol-S and control-q
X for starting and stopping output, Control-O for discarding
X output, and all other special characters that are handled by
X the VAX/VMS terminal driver.
X
X o Limited full-duplex operation (simultaneously active read and
X write requests)
X
X o The device characteristics are inherited from the system de-
X fault parameters with the following exceptions:
X
X - The device is always forced to HOSTSYNC.
X
X
X
X
X
X 1-2 Introduction
X`012
X
X
X
X
X
X
X
X
X - The device is set to NOMODEM and cannot ever be set to
X MODEM.
X
X
X
X 1.4 Differences Between PTYs and Terminals
X
X The difference between a VAX/VMS terminal and the terminal portion
X of a PTY is where the input comes from and where the output goes
X to. On a VAX/VMS terminal, the input comes from an actual terminal
X and the output goes to an actual terminal. On a PTY the input
X comes from the control device and the output goes to the control
X device. In order to simulate someone typing at the terminal device
V ````TWA5:'' we must write to the control device ````PYA5:''. In or
Xder
X to read what has been typed out to the terminal device ````TWA5:''
X we must read from the control device ````PYA5:''. PTYs are like
X terminals that only software can access.
X
X PTYs are virtual devices. When allocating a PTY, they behave much
X like mailboxes or network devices. To allocate a PTY, simply
X allocate the first one ('PYA0:'). The allocating routine will
X create a new PTY and assign it to you. The PTY will be deallocated
X when no process is referencing the device.
X
X
X 1.4.1 Device Characteristics
X
X A PTY control device has the following characteristics.
X
X o DEV$M_AVL - On line and available
X
X o DEV$M_IDV - Capable of input
X
X o DEV$M_ODV - Capable of output
X
X o DEV$M_REC - Record oriented
X
X A PTY control device does not have the following characteristics.
X
X o DEV$M_CCL - Carriage Control
X
X
X
X
X Introduction 1-3
X`012
X
X
X
X
X
X
X
X
X o DEV$M_TRM - Terminal Device
X
X
X 1.4.2 Device Type
X
X The device type is DT$_PY. Since a PTY is a nonstandard device,
X you will probably not find the correct macros, literals or con-
X stants for this device type. This field should have a value of
X 0.
X
X
X 1.4.3 Device Class
X
X The device class is DC$_PY. Since a PTY seems to be such an odd
X creature, this field should be FF in hex, or 177 in octal.
X
X
X 1.4.4 TW Unit Number
X
X The unit number of the TW device is the same as the unit number of
X the associated PT device.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 1-4 Introduction
X`012
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Chapter 2
X
X
X Using the PTY
X
X
X
X
X This chapter will present information on using the PTY. It covers
X creating the device, reading, writing data, and using additional
X signaling information. Finally it covers a minor deficiency of the
X existing implementation.
X
X
X 2.1 Creating a PTY
X
X Make sure the two drivers are loaded as PYA0: and TWA0:. Then,
X just assign a channel to PYA0:, this will create a PYAn: and a
X TWAn: (the unit numbers just go up). Anything you write to that
X channel appears on the TWAx: as if typed at a terminal. Any output
X to the terminal TWAn: is available to be read from PYAn:. The
X devices do flow control between one another and all buffering. So,
X you can just read, for example, with a 100 char buffer from PY and
X the read will complete with whatever number of characters the QIO
X to the PTY terminal had, anywhere from 1 to MAXBUF. If the QIO to
X the PTY had more chars than your read buffer, it'll just fill the
X read buffer and return, and you can get the rest on the next read.
X It is very simple to use.
X
X Also, if you assign a mailbox with the PYAn: device (use LIB$ASN_
X WTH_MBX when assigning channel to PYA0:) you will get a MSG$_
X TRMHANGUP see the VMS I/O User's Reference Manual: Part I for
X the format of the message in the mailbox whenever the terminal
X
X
X
X Using the PTY 2-1
X`012
X
X
X
X
X
X
X
X
X is hung-up. A hang-up occurs when a process logouts out or it or
X deassigns the last channel to the device. It works just like the
X HANGUP on terminals with modem signals. You can even ignore the
X hangup message if you want, it only generates the message in the
X mailbox, you can continue to use the device if you choose after
X getting the message.
X
X Should you deassign the PYAn: device, a DISCONNECT will be forced
X on any process using the TWAn: device, just like dropping carrier
X on a modem line. If you have the TT2$M_DISCONNECT bit set in the
X default terminal characteristics (TTY_DEFCHAR2 in SYSGEN), then
X you will get a virtual terminal upon logging into a TWAn: device.
X Then you get CONNECT/DISCONNECT to work. Really nice on network
X connections.
X
X Note that, just as with normal VMS terminals, you will only get
X a VTAn: if the line has the DISCONNECT terminal characteristic
X before you log into it, and only if you use LOGINOUT to start a
X process on the terminal. Just sending a <CR> into the device as
X the first character will start up LOGINOUT like a normal terminal.
X
X
X 2.2 Reading data
X
X A read from the the PY device is used to accept data from the
X TW device. The largest read operation possible is limited by the
X value of SYSGEN parameter MAXBUF. The read request will complete
X with a minimum of 1 character and maximum of the number characters
X the buffer can hold. The read operation will only complete when
X the TW driver has one or more characters to output. If at the time
X you issue a read request no data is available this request will
X be queued and completed at a later time. The PY device accepts
X all three read function codes, but unlike the TW device treats all
X three exactly the same. Note, that the system will still require
X that you have the correct privileges to use them.
X
X
X
X
X
X
X 2-2 Using the PTY
X`012
X
X
X
X
X
X
X
X
X When writing a control program for the PTY, care should be taken
X to insure that a read request is always queued to the PY device.
X Failure to do so can cause excessive delays in processing on the
X TW device.
X
X
X 2.3 Writing data
X
X A write to the PY device is used to input data to the TW device.
X The largest write operation possible is limited by the value of
X the SYSGEN parameter MAXBUF. It is not recommended that vary large
X write requests be issued. It is possible by using very large I/O
X requests to flood the TW devices input buffer. When this occurs
X data will be lost without an error being reported. Note the driver
X has been optimized for write requests of 1 to 32 bytes. Larger
X requests will work but require more work on the part of the driver
X to setup and process.
X
X The current version of the driver has taken steps to help pre-
X vent the data over-run condition described above. It does this
X by setting the TW device to send and XOFF message if its type-
X ahead buffer it getting full. Once this occurs, the PY device
X will return a status of SS$_DATAOVERUN with the actual number of
X characters input. This is sufficient to prevent a single request
X from flooding the type-ahead buffer. If a program makes repeated
X attempts to insert data after receiving this message it can flood
X the terminal type-ahead buffer. This occurs because the driver
X always inserts one character before checking to see if TW driver
X is accepting data. Because the class driver does not tell the in-
X put routine that it rejected the character, it is not possible to
X report this real loss of data. One final note: if for some reason
X the TW device clears the HOSTSYNC characteristic the driver will
X no longer report the impending data overrun condition.
X
X
X
X
X
X
X
X
X Using the PTY 2-3
X`012
X
X
X
X
X
X
X
X
X 2.4 Special signals
X
X Certain class driver events such as stopping and resuming input,
X stopping and resuming output, and altering the device characteris-
X tics, are of interest to the control program. This version of the
X PTY SUPPLIES a notification mechanism for three of these events.
X It provides notification for stopping and starting input; and for
X notification when the device characteristics change. The control
X program will have the supplied AST routine called when one these
X events occur.
X
X By making use of the start and stop input ASTs, and the SS$_
X DATAOVERUN return stauts the control program can avoid flooding
X the TW devices type-ahead buffer. Note, that these signals will
X be returned even if HOSTSYNC is cleared. These AST can be enabled
X by using the IO$_SETMODE, or the IO$_SETCHAR function on the PY
X DEVICE. The ASTs will not accept an AST parameter, instead they
X return the class driver signal character as the AST parameter.
X
X Finally, the control, program by using the AST delivered the the
X TW device, changes characteristics along with the IO$_SENSExxxx
X function to track the TW device characteristics.
X
X
X 2.5 Problems
X
X A minor problem exists and is actually a side-effect of the driver
X being cautious in order to prevent possible problems. If you have
X a virtual terminal associated with the pseudo-terminal, and you
X deassign the last channel to the control device (the PY device)
X a DISCONNECT is forced on any process on the terminal (the TW
X device) and the PY and TW are both deleted. In this case, the TW
X will not be deleted, although the PY will and the TW be marked
X as OFFLINE. This is because the driver relies on VMS to do the
X actual delete of the device. VT's alter the way device reference
X counts work, and VMS never gets around to deleting the device.
X It is marked for delete, so anything you do (like SHOW TERM) will
X cause it to be deleted. This could be fixed by deleting the device
X
X
X
X 2-4 Using the PTY
X`012
X
X
X
X
X
X
X
X
X explicitly after forcing the DISCONNECT, however it is very hard
X to prevent the use of the UCB and thus cause a system crash. Note
X that it doesget deleted correctly if you do not have a virtual
X terminal associated with the PTY, or if you have no processes
X active on the PTY when the PY and TW are to be deleted.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Using the PTY 2-5
X`012
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Chapter 3
X
X
X PTY Function Codes
X
X
X
X
X The function codes for the terminal device portion of a PTY are
X exactly the same as those for regular VAX/VMS terminals. For more
X information on VAX/VMS terminal I/O see VAX/VMS I/O User's Guide.
X
X The basic function of the control portion of a PTY are read, write
X and set mode or characteristics.
X
X A user does not need to have assigned the PTY terminal device
X in order to do I/O operations on the PTY control device. If the
X terminal device has type ahead enabled, sending the right charac-
X ters to the control device will send a message to OPCOM to start
X running SYS$SYSTEM:LOGINOUT.EXE on the terminal device.
X
X
X 3.1 Read
X
X The basic purpose of a PTY control device read is to transfer
X data from the output buffer of the PTY terminal device to a user
X specified buffer. There are three read functions which a user can
X apply to a PTY control device.
X
X o IO$_READVBLK - Read virtual block
X
X o IO$_READLBLK - Read logical block
X
X o IO$_READPBLK - Read physical block
X
X
X
X
X PTY Function Codes 3-1
X`012
X
X
X
X
X
X
X
X
X A read is complete if either of the below conditions occur:
X
X o The user specified buffer is full
X
X o At least one character is available from the PTY terminal
X device
X
X The read function codes can take the following device/function
X dependent arguments:
X
X o P1 = The starting virtual address of the buffer that is to
X receive the data read
X
X o P2 = The size of the buffer in bytes that is to receive the
X data read
X
X o P3, P4, P5, P6 = ignored
X
X
X
X 3.2 Write
X
X The basic purpose of a PTY control device write is to transfer
X data from the user specified buffer to the type-ahead buffer of
X the PTY terminal device. There are three write functions which a
X user can apply to a PTY control device.
X
X o IO$_WRITEVBLK - write virtual block
X
X o IO$_WRITELBLK - write logical block
X
X o IO$_WRITEPBLK - write physical block
X
X The write function codes can take the following device/function
X dependent arguments:
X
X o P1 = The starting virtual address of the buffer that is to be
X written to the PTY terminal device
X
X o P2 = The number of bytes that are to be sent
X
X o P3, P4, P5, P6 = Ignored
X
X
X
X
X 3-2 PTY Function Codes
X`012
X
X
X
X
X
X
X
X
X 3.3 Set Mode and Set Characteristics
X
X The SETMODE and SETCHAR functions allow the programmer to enable
X three special event notification ASTs. These special events have
X been discussed in detail in the previous chapter. The driver
X treats both of these funtion code identically but the VMS QIO(W)
X dispatcher will require the PHY_IO privilege if you use choose to
X use the IO$_SETCHAR function.
X
X o IO$_SETMODE
X
X o IO$_SETCHAR
X
X These functions take the following device/function dependent
X arguments.
X
X o P1 = address of characteristics buffer
X
V o P2 = For XON and XOFF ASTs the program can provide a 16 bit AS
XT
X parameter. When the AST is delivered the high order 16 bits of
X the AST parameter will be XON, XOFF, or bell character. For the
X notification of TW characterisitcs changing the AST parameter
X can be a full long word (32-bits).
X
X o P3 = access mode to deliver AST (maximized with the caller's
X access mode)
X
X o P4 = type of AST to be queued. (1 = XON AST notification,
X 2 = XOFF AST notification, and 3 = terminal characteristics
X changed)
X
X o P5, P6 = ignored
X
X
X
X
X
X
X
X
X
X
X
X PTY Function Codes 3-3
X`012
X
X
X
X
X
X
X
X
X 3.4 Sense Mode and Sense Characteristics
X
X The two function codes to sense the mode of the PTY control device
X are:
X
X o IO$ SENSEMODE
X
X o IO$ SENSECHAR
X
X The IO$ SENSEMODE function returns the process-associated, that
X is temporary, characteristics of the terminal device. The IO$
X SENSECHAR function returns the permanent characteristics of the
X terminal device. The IO$_SENSEMODE function is a logical func-
X tion and requires no privilege. The IO$_SENSECHAR function is a
X physical function and requires the PHY_IO privilege use it.
X
X These function codes take the following device/function dependent
X arguments.
X
X o P1 = address of an 8 or 12 byte characteristics buffer
X
X o P2 = size of characteristics buffer (eight is the default)
X
X o P3, P4, P5, P6 = ignored
X
X The P1 argument points to a quadword block which is the same for-
X mat as the Set Mode Characteristics Buffer, shown in Figure 3-1.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 3-4 PTY Function Codes
X`012
X
X
X
X
X
X
X
X
X Figure 3-1: Sense Mode and Characteristics Buffer
X __________________________________________________________________
X 31 24 23 16 15 8 7 0
X -----------------------------------------------------
X | Page Width | Type | Class |
X -----------------------------------------------------
X | Page Length| Basic Characteristics |
X -----------------------------------------------------
X | Extended Characteristics |
X _____________-----------------------------------------------------
X
X
X Figure 3-2: IOSB Contents - Read and Write Function
X __________________________________________________________________
X
X 31 24 23 16 15 8 7 0
X -----------------------------------------------------
X | Byte Count | Status |
X -----------------------------------------------------
X | Unused |
X -----------------------------------------------------
X
X __________________________________________________________________
X
X 3.5 I/O Status Block
X
X The I/O status block formats for read, write, set mode and sense
X mode I/O functions are shown in Figure 3-2, 3-3 and 3-4.
X
X The status indicates the success or failure of the specified
X operation. Below are possible values for the status field:
X
X o SS$_ABORT - The operation was canceled by the Cancel I/O on
X Channel ($CANCEL) system service. Applicable only if the drive
X was actively involved in an operation.
X
X
X
X
X
X
X
X PTY Function Codes 3-5
X`012
X
X
X
X
X
X
X
X
X Figure 3-3: IOSB Contents - Set Mode and Characteristics
X Functions
X __________________________________________________________________
X
X 31 24 23 16 15 8 7 0
X -----------------------------------------------------
X | Unused | Status |
X -----------------------------------------------------
X | Unused |
X _____________-----------------------------------------------------
X
X
X Figure 3-4: IOSB Contents - Sense Mode and Characteristics
X Functions
X __________________________________________________________________
X
X 31 24 23 16 15 8 7 0
X -----------------------------------------------------
X | Rcv Speed | Xmit speed | Status |
X -----------------------------------------------------
X | Unused |parity flags| LF fill | CR fill |
X -----------------------------------------------------
X __________________________________________________________________
X
X o SS$_ACCVIO - The specified buffer is not accessible to the
X specified process
X
X o SS$_BADPARAM - An illegal value was supplied in P4 for a set
X request.
X
X o SS$_DATAOVERUN - The TW device has stopped accepting data. The
X byte count indicates the number of characters accepted by the
X terminal.
X
X o SS$_NORMAL - Successful Completion.
X
X o SS$_NOSUCHDEV - The TW device no longer exists.
X
X
X
X
X
X
X 3-6 PTY Function Codes
X`012
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Chapter 4
X
X
X Building and Installing the PTY
X
X
X
X
X In VAX/VMS V5.0, several pieces of software support the terminal
V interface. The hardware independent portion is SYS$SYSTEM:TTDRIVER
X.EXE.
X This version of the PTY does not require any changes or patches to
X this code. PTY drivers consist of two device drivers, TWDRIVER.EXE
X for the terminal portion of the PTY's, and PYDRIVER.EXE for the
X control portion. In order to have a working PTY you must build and
X install both pieces.
X
X
X 4.1 Compiling Sources
X
X There are several pieces of source code that make up PTY drivers.
X PYDRIVER.MAR is the source for the control portion. TWDRIVER.MAR
X is the source for the terminal portion.
X
X The commands for compiling and linking the devices are:
X
X
X
X
X
X
X
X
X
X
X
X
X Building and Installing the PTY 4-1
X`012
X
X
X
X
X
X
X
X
X $ ! Compile the drivers
X $ MACRO /LIST /OBJECT TWDRIVER.MAR
X $ MACRO /LIST /OBJECT PYDRIVER.MAR
X $ ! Link the drivers
X $ LINK /MAP /FULL /CROSS -
X TWDRIVER,SYS$SYSTEM:SYS.STB/SELECTIVE,SYS$INPUT:/OPTION
X BASE=0
X $ LINK /MAP /FULL /CROSS -
X PYDRIVER,SYS$SYSTEM:SYS.STB/SELECTIVE,SYS$INPUT:/OPTION
X BASE=0
X
X
X 4.2 Installing the Devices
X
X To load a PTY, login to a privileged account and issue the follow-
X ing commands.
X
X $ RUN SYS$SYSTEM:SYSGEN
X LOAD device:[directory]TWDRIVER
X LOAD device:[directory]PYDRIVER
X CONNECT TWA0/NOADAPTER/DRIVER=TWDRIVER
X CONNECT PYA0/NOADAPTER/DRIVER=PYDRIVER
X
X Don't try to use PTB0 or PYB0. The code is not built to handle
X these. It is only built to handle the PYA and TWA control and
X terminal devices.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 4-2 Building and Installing the PTY
$ GOSUB UNPACK_FILE
$ FILE_IS = "PTY_EXAMPLE.C"
$ CHECKSUM_IS = 573259616
$ COPY SYS$INPUT VMS_SHARE_DUMMY.DUMMY
X/*
X* ++
X* FACILITY:
X*
X*`009TW/PY driver test program
X*
X* ABSTRACT:
X*`009`009Program to take data from a users terminal input it to a PY
X*`009device and display output. The program contains the ability to also
X*`009report interesting events on a control connection.
X*
X*`009NOTE:
X*`009`009The program requires the following privileges
X*
X*`009`009`0091) SHARE
X*`009`009`0092) PHY_IO
X*`009`009`0093) SYSPRV
X*
X* 1) The program will ask for a terminal to output diagnostic information. If
X* you just hit <cr> it will skip outputying this info.
X*
X* 2) The diagnostic information is notification of XON & XOFF, and device
X* characteristics changing on the TW device. If you use this you have
X* to have PHY_IO or else the program bombs.
X*
X* 3) The program will stop accepting input if the TW device is not accepting
X* input. When this happens all you can do is wait, I did this on purpose
X* to make sure that the XOFF logic is working. Some day maybe I will go
X* back and make it smarter.
X* --
X*/
X`012
X/* Include file definitions and template structure definitions */
X
X#include`009descrip
X#include`009iodef
X#include`009ssdef
X#include`009stdio
X#include`009ttdef
X#include`009tt2def
X
Xstruct`009devchar
X{
Xchar`009`009class;
Xchar`009`009type;
Xshort int`009buffer_size;
Xint`009`009basic_char;
Xint`009`009extended_char;
X};
X
Xstruct`009iosb
X{
Xshort int`009status;
Xshort int`009byte_cnt;
Xshort int `009terminator;
Xshort int`009terminator_size;
X};
X
X
X`012
X/* Global data definitions */
X
Xchar`009`009mbx_buff[40];
Xchar `009`009py_r_buff[255];
X
Xshort int`009info_chan;
Xshort int`009kbd_chan;
Xshort int`009mbx_chan;
Xshort int`009py_chan;
X
Xshort int`009kbd_s_efn;
Xshort int`009kbd_r_efn;
Xshort int`009py_s_efn;
Xshort int`009py_w_efn;
Xshort int`009wait_efn;
Xshort int`009xoff_efn;
X
Xint`009`009exit_handler();
Xint`009`009exit_status;
Xint`009`009info_flag = 0;
Xint`009`009term_mask[8] = {0, 0, 0, 0, 0, 0, 0, 0};
X
Xstruct`009devchar saved_char;
Xstruct`009exit_block
X{
Xint`009`009flink;
Xint`009`009*hanlder_addr;
Xchar`009`009arg_count;
Xchar`009`009unused[3];
Xint`009`009reason;
X}`009`009exit_block_descrip = {0, exit_handler, 1, 0, 0, 0, &exit_status};
Xstruct`009iosb`009info_w_iosb;
Xstruct`009iosb`009kbd_w_iosb;
Xstruct`009iosb`009mbx_iosb;
Xstruct`009iosb`009py_r_iosb;
Xstruct`009iosb`009py_s_iosb;
Xstruct`009term_descrip
X{
Xshort int`009size;
Xshort int`009unused;
Xint`009`009*ptr;
X} term_block = {32, 0, &term_mask[0]};
X
X`012
Xmain()
X{
X
Xchar`009`009devnam[80];
Xchar`009`009kbd_r_buff[255];
X
X
X$DESCRIPTOR(dummy,"");
X$DESCRIPTOR(kbd_devnam,"tt:");
X$DESCRIPTOR(null_char,"\000");
X$DESCRIPTOR(py_devnam,"PYA0:");
X
Xint`009`009bintim[2] = {-5*10*100*100,-1};
Xint`009`009length;
Xint`009`009read_mbx_ast();
Xint`009`009py_read_ast();
Xint`009`009set_line_ast();
Xint`009`009xon_ast();
Xint`009`009xoff_ast();
Xint`009`009status;
X
Xstruct`009devchar`009changed_char;
Xstruct`009iosb`009kbd_r_iosb;
Xstruct`009iosb`009py_w_iosb;
X
X
-+-+-+-+-+ End of part 2 +-+-+-+-+-