|
|
|
|
Reading Data
To read data from the pseudoterminal, the control program
uses the PTD$READ routine. The read request completes with a minimum
of one character and a maximum of the number of characters requested.
The read operation completes when the pseudoterminal has characters
to output. If a read request is issued and no data is available,
the read request is queued and then completed at a later time.
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.
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.
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.
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.
Event Notification
This section describes how the pseudoterminal driver provides
notification of important driver events.
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:
Output
Stop
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.
Output
Resume
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.
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.
Output
Abort
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.
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.
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 Control Connection Routines.
|
|