Updated: 11 December 1998

OpenVMS I/O User's Reference Manual

Forces the pseudoterminal to be deleted and frees the channel.

Format

PTD$DELETE chan

RETURNS

OpenVMS usage:	longword (unsigned)
type:	write only
access:	by value

Arguments

chan

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of the I/O channel assigned to the pseudoterminal. This channel is only intended to be used for PTD$XXX operations.

Description

PTD$DELETE forces the pseudoterminal to be deleted and frees the channel assigned to the pseudoterminal. When a pseudoterminal is deleted, any process using the pseudoterminal (except the control program) is disconnected. A PTD$DELETE request causes any pending I/O for the control program to be aborted. It deletes any queued event notification ASTs and returns the I/O buffers back to the application. It also causes the pseudoterminal unit control block (UCB) to be deleted once the reference count returns to zero.

Return Values

SS$_NORMAL	Normal successful completion.
SS$_DEVOFFLINE	Device is off line and request cannot proceed.
SS$_IVCHAN	Illegal channel.
SS$_NOPRIV	Insufficient privilege to perform request.

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.

Format

PTD$READ [efn], chan [,astadr] [,astprm] readbuf, readbuf_len

RETURNS

OpenVMS usage:	longword (unsigned)
type:	write only
access:	by value

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 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.

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. 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.

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$_INSFMEM	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.

Reads data from the pseudoterminal. The PTD$READW routine completes synchronously; that is, it returns to the caller after the data has been read.

For asynchronous completion, use the PTD$READ routine. The PTD$READ routine is identical to the PTD$READW routine in every way except that PTD$READ returns to the caller without waiting for the data to be read.

Format

PTD$READW [efn], chan [,astadr] [,astprm] readbuf, readbuf_len

Enables or disables a number of repeating terminal event notification ASTs.

Format

PTD$SET_EVENT_NOTIFICATION chan, astadr [,astprm] [,acmode], type

RETURNS

OpenVMS usage:	longword (unsigned)
type:	write only
access:	by value

Arguments

chan

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of the I/O channel assigned to the 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

Address of the notification AST service routine, or zero if the AST is to be canceled.

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.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode for which the AST is to be declared. The most privileged access mode is the access mode of the caller. The resulting mode is the access mode at which the AST is declared.

type

OpenVMS usage:	type_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Value that indicates which notification AST to enable. The $PTDDEF macro defines the symbolic names listed in Table D-2.

Table D-2 Symbolic Names Defined by$PTDDEF Macro

Symbolic Name	Description
PTD$C_SEND_XON	Deliver notification AST when the pseudoterminal is ready to accept input. This AST is not delivered if the pseudoterminal is set to NO HOSTSYNC.
PTD$C_SEND_BELL	Deliver notification AST when the pseudoterminal wants to stop input and signal it with a bell character.
PTD$C_SEND_XOFF	Deliver notification AST when the pseudoterminal wants to stop input and signal it with a DC3 character.
PTD$C_STOP_OUTPUT	Deliver notification AST when the pseudoterminal is stopping output.
PTD$C_RESUME_OUTPUT	Deliver notification AST when the pseudoterminal is resuming output.
PTD$C_CHAR_CHANGED	Deliver notification AST when the pseudoterminal has changed some device characteristic.
PTD$C_ABORT_OUTPUT	Deliver notification AST when the pseudoterminal wants to abort output.
PTD$C_START_READ	Deliver notification AST when the pseudoterminal is starting an application's read request. This AST is delivered only if read event notification has been enabled.
PTD$C_MIDDLE_READ	Deliver notification AST when the pseudoterminal has finished sending an application's read request prompt string. This AST is delivered only if read event notification has been enabled.
PTD$C_END_READ	Deliver notification AST when the pseudoterminal has finished an application's read request. This AST is delivered only if read event notification has been enabled.
PTD$C_ENABLE_READ	Enable terminal read event AST delivery. If this code is used, you cannot supply the astadr argument.
PTD$C_DISABLE_READ	Disable terminal read event AST delivery. If this code is used, you cannot supply the astadr argument.

Description

PTD$SET_EVENT_NOTIFICATION enables or disables the repeating terminal event notification ASTs listed in Table D-2. After an event notification AST is enabled, it remains in effect until it is disabled or until the device is deleted.

Return Values

SS$_NORMAL	Normal successful completion.
SS$_ACCVIO	Unable to read an argument, or invalid I/O buffer address.
SS$_BADPARAM	An astadr, astprm, or acmode argument was not zero when enabling or disabling read notification.
SS$_DEVOFFLINE	Device is off line and request cannot proceed.
SS$_EXASTLM	Insufficient AST quota for notification AST.
SS$_INSFMEM	Insufficient memory.
SS$_IVCHAN	Illegal channel.
SS$_NOPRIV	Insufficient privilege to perform request.

Inputs data to the pseudoterminal and reads any immediately echoed characters.

Format

PTD$WRITE chan [,astadr] [,astprm], wrtbuf, wrtbuf_len [,echobuf] [,echobuf_len]

RETURNS

OpenVMS usage:	longword (unsigned)
type:	write only
access:	by value

Arguments

chan

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of I/O channel assigned to the 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$WRITE completes. If astadr is specified, the AST routine executes at the same access mode as the caller of the PTD$WRITE 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.

wrtbuf

OpenVMS usage:	char_string
type:	character coded text string
access:	read only
mechanism:	by reference

Address of the write I/O status longword. The first character in an I/O buffer to be written is this address plus 4. The wrtbuf must be in the range specified by the inadr argument of the PTD$CREATE routine; otherwise an SS$_ACCVIO status is returned.

wrtbuf_len

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of characters to be written to the pseudoterminal. These characters appear as input to the terminal side of the pseudoterminal.

echobuf

OpenVMS usage:	char_string
type:	character coded text string
access:	write only
mechanism:	by reference

Address of the echo I/O status longword. The first character position in an I/O buffer to receive all output is this address plus 4. The echobuf must be in the range specified by the inadr argument of the PTD$CREATE routine; otherwise an SS$_ACCVIO status is returned.

echobuf_len

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of characters that can be read from the pseudoterminal. If an echo buffer is specified, up to echobuf_len characters can be stored in it.

Description

PTD$WRITE inputs data to the pseudoterminal and reads any immediately echoed characters. PTD$WRITE allows you to specify a buffer to receive any output generated by the write; you do not need to issue a separate read request to read this data.

Return Values

SS$_NORMAL	Normal successful completion.
SS$_ACCVIO	Unable to read an argument, or invalid I/O buffer address.
SS$_DATALOST	The terminal driver type-ahead buffer is full and character written was lost.
SS$_DATAOVERUN	The terminal driver type-ahead buffer is getting full; attempts to send more data might result in loss of characters.
SS$_DEVOFFLINE	Device is off line and request cannot proceed.
SS$_EXASTLM	Insufficient AST quota for notification AST.
SS$_INSFMEM	Insufficient memory.
SS$_IVBUFLEN	Buffer size supplied is illegal.
SS$_IVCHAN	Illegal channel.
SS$_NOPRIV	Insufficient privilege to perform request.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6136PRO_040.HTML