This section discusses the following pseudoterminal
functions:
6.5.1 Reading Data |
 |
To read data from the pseudoterminal, the control
program uses the PTD$READ routine. When a PTD$READ routine is called,
the operating system queues a read operation. The read operation completes
when the pseudoterminal has characters to output. The read request
queries TTDRIVER whether there is data found to be returned. If so,
the resulting string of characters is returned. If a read request
is issued and no data is available, the read request is queued and
then completed at a later time. In this case, the routine always returns
at least one character. The read request may complete even when there
are no characters available to output. In this rare case when TTDRIVER
indicates that there is no more data to be output and there is really
no data, the read operation completes with zero bytes of data.
An application that issues an asynchronous pseudoterminal
read can use the $SYNCH system service to find out when the read completed.
The efn argument for the $SYNCH service
must be the same as the efn specified
in the original PTD$READ call, and the iosb for the $SYNCH service must match the readbuf of the PTD$READ call.
6.5.2 Writing Data |
|
To write data to the pseudoterminal, the control
program uses the PTD$WRITE routine. The write request allows you to
specify a buffer to receive any output that the write request generates;
you do not need to issue a separate read request to read this data.
When you use an echo buffer, the control application can significantly
reduce the number of I/O requests required.
An application can issue only one write request
at a time. Once the write request completes, the application must
check the write buffer status longword to see whether all the data
supplied was written. If not, the application must issue additional
write requests until all the data has been accepted.
6.5.3 Using Write with Echo |
|
If a read request is pending when a write-with-echo
request is issued, the echo data is placed in the echo buffer. If
more data is echoed than can fit in the echo buffer, the remaining
data is placed in the pending read requests buffer. If no pending
read exists, the data is held by the driver until another request
that can take the data is issued. Both the read and the write with
echo must use completion ASTs to allow the driver to report request
completions to the application in the correct order.
If an application is not using the write-with-echo
capability, the application should avoid using completion ASTs if
possible. Unnecessary use of completion ASTs significantly increases
the number of instructions needed to complete a read or write operation.
When using write with echo, both the wrtbuf and echobuf arguments contain I/O status information. An application must check
both of these status longwords if the PTD$WRITE completes successfully.
If a write operation wrote no characters, characters might still be
in the echo buffer. If no data was echoed, the status in the echobuf is SS$_NORMAL with zero bytes transferred.
6.5.4 Flow Control |
|
By default, the driver attempts to notify the
control program of data overrun or loss. The pseudoterminal sends
an XOFF AST when the type-ahead buffer is getting full. Once the pseudoterminal
delivers an XOFF AST, the pseudoterminal also returns a status of
SS$_DATAOVERUN with the actual number of characters input. This prevents
a single request from flooding the type-ahead buffer. If a control
program makes repeated attempts to insert data after receiving the
SS$_DATAOVERUN message, it can flood the terminal type-ahead buffer.
When the type-ahead buffer has filled, the pseudoterminal returns
the status of SS$_DATALOST.
If the control program is writing to the terminal
or terminal driver, it should let the terminal and terminal driver
handle flow control. To do this, the application should enable all
three input flow control notification ASTs. The control program should
write a DC1 to the terminal if an XON AST is delivered. It should
write a DC3 to a terminal if an XOFF AST is delivered, and write a
BELL character to the terminal if the BELL AST is delivered. These
signals allow the terminal to decide what to do with the flow control
data. The application should ignore the SS$_DATAOVERUN and SS$_DATALOST
return status and continue writing data to the pseudoterminal.
6.5.5 Event Notification |
|
This section describes how the pseudoterminal
driver provides notification of important driver events.
6.5.5.1 Input Flow Control
The driver provides three ways to indicate when
the class driver wants to stop input and one way to signal when it
is safe to resume output:
The driver returns a status
of SS$_DATAOVERUN and the number of characters input for the control
program write.
The control program can
enable a BELL attention AST to be delivered when the class driver
calls the PTD$SET_TERMINAL_NOTIFICATION routine. This AST is delivered
if the pseudoterminal does not have the HOSTSYNC attribute set. If
only a BELL or only an XOFF AST event is enabled and an XOFF or a
BELL AST needs to be delivered, the AST that is available is delivered.
The control program can
enable an XOFF attention AST to be delivered when the class driver
calls the PTD$SET_TERMINAL_NOTIFICATION routine. This AST is delivered
if the pseudoterminal has the HOSTSYNC attribute set.
The control program can
enable an XON attention AST to be delivered when the class driver
calls the PTD$SET_TERMINAL_NOTIFICATION routine. This AST is delivered
only if the pseudoterminal has the HOSTSYNC attribute set.
The Output Stop AST tells the control program
that the terminal driver is stopping output. This keeps the control
program from having to determine whether an XOFF written to the control
side is being treated by the terminal driver as flow control or data.
The Output Resume AST tells the control program
that the terminal driver wants to resume output. This AST can be delivered
at any time, even if output is active or has previously been stopped.
The control program should always restart output processing when it
receives this AST.
6.5.5.4 Characteristics Changed
The Characteristics Changed AST tells the control
program that the terminal driver has called the pseudoterminal CHANGE
CHARACTERISTICS routine. This routine is called whenever the terminal
driver has changed the device characteristics. The control program
should then read the pseudoterminal characteristics to determine what
has changed.
The Output Abort AST tells the control program
that the terminal driver has called the pseudoterminal ABORT OUTPUT
routine. This routine is called when the terminal driver wants to
flush any outstanding output data. The control program should flush
any internally buffered data when this AST is received.
6.5.5.6 Terminal Driver Read Events
Three special event types notify the control program
when a terminal read request starts and finishes. By default, the
pseudoterminal does not deliver the read notification ASTs associated
with these events. The PTD$SET_EVENT_NOTIFICATION routine must be
used explicitly to enable or disable their delivery.
Start Read—Tells
the control program that the terminal driver is starting a read request.
Some applications require this in order to know when to start inputting
a logged session script. The special event types are:
Middle Read—Tells
the control program that the terminal driver has finished writing
the prompt string if one was supplied.
End Read—Tells
the control program that the terminal driver has finished a read request.
Once an event notification AST is enabled, it
continues to be delivered until it is canceled, or until the device
is deleted. This characteristic allows the control program to enable
the AST once, which greatly reduces the risk of missing multiple rapid
occurrences of an event. If the driver cannot get sufficient resources
to deliver the notification AST, that report is lost. Only one AST
per event is allowed, and attempts to specify multiple ASTs result
in use of the last one specified.
To enable or disable event notification, the control
program uses the PTD$SET_EVENT_NOTIFICATION routine, which is described
in Appendix D.
