HP OpenVMS I/O User’s Reference Manual: OpenVMS Version 8.4 > Appendix D Control Connection Routines

D.4 PTD$READ — Read Data from Pseudoterminal

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$_ACCVIOUnable to read an argument, or invalid read buffer address.
SS$_DEVOFFLINEDevice is off line and request cannot proceed.
SS$_EXASTLMInsufficient AST quota for notification AST.

SS$_ILLEFC

Illegal event flag cluster.

SS$_INFMEM

Insufficient memory.
SS$_IVBUFLENBuffer size supplied is illegal.

SS$_IVCHAN

Illegal channel.
SS$_NOPRIVInsufficient privilege to perform request.
SS$_UNASEFCUnassociated event flag cluster.