Reads data from the pseudoterminal. The PTD$READ
routine completes asynchronously; that is, it returns to the caller
without waiting for the data to be read.
For synchronous completion, use the PTD$READW
routine. The PTD$READW routine is identical to the PTD$READ routine
in every way, except that PTD$READW returns to the caller after the
data is read.
D.4.1 Format |
 |
PTD$READ [efn], chan [.astadr] [,astprm] readbuf, readbuf_len |
D.4.2 Returns |
|
| OpenVMS usage: | longword (unsigned) |
| type: | write only |
| access: | by value |
D.4.3 Arguments |
|
efn
| OpenVMS usage: | ef_number |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
Number of the event flag to be set when PTD$READ
returns the requested information. If you do not specify this argument,
event flag 0 is used. When PTD$READ begins execution, it clears this
flag.
chan
| OpenVMS usage: | channel |
| type: | word (unsigned) |
| access: | read only |
| mechanism: | by value |
Number of the I/O channel assigned to the new
pseudoterminal. This channel is only intended to be used for PTD$XXX
operations.
astadr
| OpenVMS usage: | ast_procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by reference |
AST service routine to be executed when PTD$READ
completes. If you specify astadr,
the AST routine executes at the same access mode as the caller of
the PTD$READ routine.
astprm
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
AST parameter to be passed to the AST service
routine specified by the astadr argument.
readbuf
| OpenVMS usage: | char_string |
| type: | character coded text string |
| access: | write only |
| mechanism: | by reference |
Address of the read I/O status longword. The first
character position in an I/O buffer to receive all output is this
address plus 4. The readbuf argument
must be in the range specified in the inadr argument of the PTD$CREATE routine; otherwise, an SS$_ACCVIO status
is returned.
readbuf_len
| OpenVMS usage: | word_unsigned |
| type: | word (unsigned) |
| access: | read only |
| mechanism: | by value |
Number of characters that can be read from the
pseudoterminal and stored in the buffer specified by readbuf.
D.4.4 Description |
|
The PTD$READ routine reads data from the pseudoterminal.
The read request completes with a minimum of one character and a maximum
of the number of characters specified by the readbuf_len argument.
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.
D.4.5 Return Values |
|
SS$_NORMAL | Normal successful completion. |
| SS$_ACCVIO | Unable to read an argument, or invalid read buffer address. |
| SS$_DEVOFFLINE | Device is off line and request cannot proceed. |
| SS$_EXASTLM | Insufficient AST quota for notification AST. |
SS$_ILLEFC | Illegal event flag cluster. |
SS$_INFMEM | Insufficient memory. |
| SS$_IVBUFLEN | Buffer size supplied is illegal. |
SS$_IVCHAN | Illegal channel. |
| SS$_NOPRIV | Insufficient privilege to perform request. |
| SS$_UNASEFC | Unassociated event flag cluster. |
