Example 6-1 shows
how to use the pseudoterminal. (The example is also included in the
SYS$EXAMPLES directory.) This section begins with a brief overview
of the example. The example itself briefly discusses each module;
the pseudocode for that module follows its discussion.
The scenario chosen for this example is a simple
terminal session logging utility that uses most of the pseudoterminal
capabilities. This example also shows how to use the write-with-echo
capability, which provides a significant gain in performance.
6.6.1 Design Overview
The design approach writes the log record in a
main loop that hibernates when it has no work to do. The loop uses
ASTs to read keystrokes from the terminal, write to the pseudoterminal,
and write data to the terminal. When a block of characters is written
to the terminal, that block is placed into a queue of blocks to be
written to the log file, and a wake request is issued. Logging is
stopped if you log out of the subprocess, if you enter the stop logging
character Ctrl\, or if a severe error occurs during data processing.
When any of these events occur, all outstanding log records are written
before the program exits.
One major design consideration is how flow control
should be handled — either by attempting to enforce flow control,
or by letting the terminal and terminal driver handle it. In this
example, the terminal and terminal driver handle flow control; the
driver sends XON, XOFF, or BELL characters to the terminal as necessary.
One of the six I/O buffers is permanently reserved
as the terminal read buffer. This buffer is passed directly to the
terminal read $QIO. This eliminates having to move data that is read
from the terminal into the read buffer. The other five buffers are
placed in a queue and are allocated and deallocated as needed. This
pool of buffers reserves the first two longwords to be used as queue
headers and traditional IOSBs. The third longword and the I/O status
longwords are used by the pseudoterminal driver.
Example 6-1 Sample Pseudocode for Pseudoterminal Driver Program
/*
** Main Routine
**
** Function: Intitializes the environment and then hibernates, waiting
** to be awakened. When awakened, the program checks to see whether it
** is exiting, or whether more log data is available. If more data is
** available, the data is appended to the current log record and checked
** to see whether a log record should be written. A log record is written
** either when maxbuf characters are in the log buffer,
** or when it finds a <CR>character pair. The algorithm
** allows an unlimited number of <NULL>fill characters to occur
** between the <CR>and the <LF>. If the program is
** exiting, it closes the log file, deletes the pseudoterminal, resets the
** terminal, and exits.
*/
Initialize environments (This includes creating pseudoterminal, the log file
and starting up the subprocess.)
If (Initialization OK) Then
Do
while (I/O buffer to log)
Data size = number of bytes in I/O buff
For all data in I/O buffer
If (cr_seen) Then
If (current char == <LF>) Then
write current log buffer
reset cr_seen
point to start of log buffer
Else if (current char != <NULL>) Then
insert <CR>and current char into log buffer
move log buffer ptr over 2 characters
reset cr_seen
Endif
Else if (current character != <CR>) Then
insert character into log buffer
move log buffer ptr over 1 character
Else
set cr_seen
Endif
If (log buffer ptr >= IOC$GW_MAX-48) Then
write log buffer
reset log buffer pointer
reset cr_seen
Endif
Endloop
Free I/O buffer call free_io_buffers
Endwhile
If (not exiting) Then
Wait for more to do call SYS$HIBER
Endif
Until ( (exiting) and (no I/O buffers to log) )
close log file
If ( (close failed) and (exit reason is SS$_NORMAL) ) Then
set exit to status to failure reason
Endif
If (subprocess still running) Then
call SYS$FORCEX to run down the subprocess
Endif
call PTD$CANCEL to flush all pending pseudoterminal read requests
call SYS$CANCEL to flush all terminal requests
call PTD$DELETE to delete the pseudoterminal
If ( (delete failed) and (exit reason is SS$_NORMAL) ) Then
set exit to status to failure reason
Endif
reset terminal to startup condition using SYS$QIOW
If ( (terminal reset failed) and (exit reason is SS$_NORMAL) ) Then
exit to status to failure reason
Endif
Endif
call LIB$SIGNAL and report exit reason
Exit
/*
**
** Initialization Code
**
** Function: This routine sets the terminal characteristics, creates the
** pseudoterminal, starts up the subprocess, and opens the log file. If
** any of these steps fail, the program undoes any steps already done and
** returns to the main routine.
**
*/
read the maximum buffer size from IOC$GW_MAXBUF
Assign a channel to SYS$INPUT
If (assign ok) Then
Read the terminal characteristics from the terminal
If (read of terminal characteristics ok) Then
Open log file with maximum record size of IOC$GW_MAXBUF
If (open ok) Then
Create the pseudoterminal with characteristics of terminal
If (create ok) then
Place 4 of the buffers on the queue of free I/O buffers
Copy terminal characteristics and modify them to NOECHO and PASTHRU
Set the terminal characteristics use modified value
If (set ok) Then
Get device name of pseudoterminal use SYS$GETDVI
If (get ok) Then
Create subprocess
If (create ok) Then
Enable XON, XOFF, BELL, SET_LINE event notification ASTs
If (AST setup OK) Then
Call PTD$READ to start reading from the pseudoterminal
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (read ok) Then
Call SYS$QIO and read a single character from the
keyboard ASTADR = kbd_read_ast
If (read failed) Then
Call PTD$CANCEL to flush queued pseudoterminal read
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Reset terminal to original state
Close log file and delete it
Endif
Else
Call PTD$DELETE to delete pseudoterminal
Close log file and delete it
Endif
Else
Close log file and delete it
Endif
Endif
Endif
Endif
/*
** kbd_read_ast
**
** Function: This routine is called every time data is read from the terminal.
** If the program is exiting, then the routine exits without restarting the
** read. The character read is checked to see if the terminate processing
** character Ctrl\ was entered. If the terminate processing character was
** entered, the exiting state is set and a SYS$WAKE is issued to start the
** main routine. Now an attempt is made to obtain an I/O buffer in which
** to store echoed output. If an I/O buffer is unavailable, a simple
** PTD$WRITE is issued; a PTD$WRITE with echo is issued if a buffer is
** available. If the write completes successfully, another read is issued
** to the keyboard.
**
*/
If (not exiting) Then
If (read ok) Then
Search input data for Ctrl\
Allocate a read buffer call allocate_io_buffer
If (got a buffer) Then
Call PTD$WRITE to write characters to pseudoterminal
ASTADR = ft_echo_ast
ASTPRM = allocated I/O buffer
WRTBUF = read I/O buffer
WRTBUF_LEN = number of characters read
ECHOBUF = allocated I/O buffer
ECHOBUF_LEN = 500
Else
Call PTD$WRITE to write characters to pseudoterminal
WRTBUF = read I/O buffer
WRTBUF_LEN = number of characters read
Endif
If (write setup ok)
If ( (write status is ok) or (write status is SS$_DATALOST) )
Issue another single character read to terminal with
ASTADR = kbd_read_ast, with data going to read I/O buffer
If (read setup failed) Then
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to SS$_NORMAL
Endif
Else
Set exit flag
Set exiting reason to read failure status
Endif
If (exiting) Then
Wake the mainline call SYS$WAKE
Endif
Endif
/*
** terminal_output_ast
**
** Function: This routine is called every time an I/O buffer is written
** to the terminal. If the terminal write request completes successfully,
** it inserts the I/O buffer into the queue of I/O buffers to be logged.
** If the I/O buffer is the only entry on the queue, it issues a SYS$WAKE
** to start the main routine. To prevent spurious wake requests,
** SYS$WAKE is not issued if multiple entries are already on
** the queue. If a terminal write error occurs, the routine sets the
** exit flag and wakes the main routine.
**
*/
If (terminal write completed ok) Then
insert I/O buffer onto logging queue
If (this is only entry on queue) Then
wake the mainline call SYS$WAKE
Endif
Else
set exit flag
set exiting reason to terminal write error reason
wake the mainline call SYS$WAKE
Endif
/*
**
** ft_read_ast
**
** Function: This routine is called when a pseudoterminal read request
** completes. It writes the buffer to the terminal and attempts to start
** another read from the pseudoterminal. If the program is not exiting,
** this routine writes the buffer to the terminal and does not start another
** pseudoterminal read.
**
*/
If (not exiting)
If (Pseudoterminal read ok) Then
write buffer to the terminal ASTADR = terminal_output_ast
If (write setup ok) Then
Allocate another read buffer call allocate_io_buffer
If (got a buffer) Then
Call PTD$READ to restart reads from the pseudoterminal.
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (read setup failed) Then
Set exit flag
Set exiting reason to read failure reason
Wake the mainline call SYS$WAKE
Endif
Else
Set read stopped flag
Endif
Else
Set exit flag
Set exiting reason to terminal write failure reason
Wake the mainline call SYS$WAKE
Endif
Else
Set exit flag
Set exiting reason to terminal read failure reason
Wake the mainline call SYS$WAKE
Endif
Endif
/*
**
** ft_echo_ast
**
** Function: This routine is called if a write to the pseudoterminal used
** an ECHO buffer. If any data was echoed, the output is written to the
** terminal. If no data was echoed, the I/O buffer is freed so it can be
** used later. If the program is exiting, this routine exits.
**
*/
If (not exiting) Then
If (ECHO buffer has data) Then
Write the buffer to the terminal with ASTADR = terminal_output_ast
If (error setting up write) Then
Set exit flag
Set exiting reason to write failure reason
Wake mainline call SYS$WAKE
Endif
Else
Free I/O buffer call free_io_buffers
Endif
Endif
/*
** free_io_buffers
**
** Function: This routine places a free I/O buffer on the queue of available
** I/O buffers. It also restarts any stopped read operations from the
** pseudoterminals. This routine disables AST delivery while it is running
** in order to synchronize reading and resetting the read stopped flag.
**
*/
If (not exiting) Then
Disable AST deliver using SYS$SETAST
If (Pseudoterminal reads not stopped) Then
Insert I/O buffer on the interlocked queue of free I/O buffers
Else
Call PTD$READ to restart reads from the pseudoterminal.
ASTADR = ft_read_ast
ASTPRM = buffer address
READBUF = I/O buffer + 8
READBUF_LEN = 500
If (no error starting read) Then
Clear read stopped flag
Else
Set exit flag
Set exit reason to read setup reason
Endif
Endif
Enable AST delivery using SYS$SETAST
Endif
/*
**
** allocate_io_buffer
**
** Function: This routine obtains a free I/O buffer from the queue of
** available I/O buffers. If the program is exiting, this routine
** returns an SS$_FORCEDEXIT error.
**
*/
If (not exiting) Then
remove a I/O buffer from the interlocked queue of I/O buffers
If (queue empty) Then
exit with reason LIB$_QUEWASEMP
else
exit with reason SS$_FORCEDEXIT
Endif
/*
** subprocess_exit
**
** Function: This routine is called when the subprocess has completed
** and exited. This routine checks whether the program is already exiting.
** If not, then the routine indicates that the program is exiting and wakes
** up the main program.
**
*/
If (not exiting) Then
indicate subprocess no longer running
set exit status to SS$_NORMAL
indicate exiting
call SYS$WAKE to start up main loop
Endif
/*
** xon_ast
**
** Function: This routine is called for the pseudoterminal driver to signal
** that it is ready to accept keyboard input. The routine attempts to send
** an XON character to the terminal by sending XON DC1 using SYS$QIO.
** If the attempt fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIO to send a <DC1>character to the terminal
Endif
/*
** bell_ast
**
** Function: This routine is called when the pseudoterminal driver wants
** to warn the user to stop sending keyboard data. The routine attempts
** to ring the terminal bell by sending the BELL character to the terminal
** using SYS$QIO. If the attempt fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIO to send a <BELL>character to the terminal
Endif
/*
** xoff_ast
**
** Function: This routine is called when the pseudoterminal driver wants to
** signal that it will stop accepting keyboard input. The routine attempts
** to send an XOFF character to the terminal by sending XOFF DC3 to the
** terminal using SYS$QIO. If the attempt fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIO to send a <DC3>character to the terminal
Endif
/*
** set_line_ast
**
** Function: This routine is called when the pseudoterminal device
** characteristics change. The routine reads the current pseudoterminal
** characteristics, changes the characteristics to set PASTHRU and NOECHO,
** and applies the characteristics to the input terminal. If the attempt
** to alter the terminal characteristics fails, it is not retried.
**
*/
If (not exiting) Then
call SYS$QIOW to read the pseudoterminals characteristics
If (not error) Then
Set the alter the just read characteristics to have PASTHRU and NOECHO
attributes
call SYS$QIO to set the terminal characteristics.
Endif
Endif
