Functions and CALL Routines under OpenVMS

TTOPEN Function: OpenVMS

Assigns an I/O channel to a terminal.

Category:	Terminal-Access
OpenVMS specifics:	All aspects are host-specific

Syntax
Details
Example
See Also

Syntax

TTOPEN(control-specification,channel)

control-specification

is the control string that specifies the terminal and processing options, separated from each other by blanks. It can be a character variable, a character literal enclosed in double quotation marks, or another character expression. The value for control-specification gives the device name and processing options and has the following form:

DEVICE=name <processing-option-list>

Each argument can be abbreviated to the shortest unique spelling. There is no default.

name

specifies the terminal name for subsequent I/O operations. DEVICE=name is required.

processing-option-list

can be one or more of the following, separated by blanks:

BUFFERFULL | NOBUFFERFULL

If you specify BUFFERFULL as one of the processing options when you enumerate the control string for the TTOPEN function, input terminates when the buffer is full or when a terminating character (either the default character or the character set with the TERMINATOR processing option) is read.

The following list enumerates the effects on input termination when you turn on combinations of processing options:

BUFFERFULL and TERMINATOR=

causes input to be terminated when any of the following is true:

the buffer is full. The size of the buffer is specified by the SIZE= option. If SIZE= is not specified, then the buffer size defaults to 200 characters.
a character that is contained in the terminator string is encountered.
you press Enter.

NOBUFFERFULL and TERMINATOR=

causes input to be terminated when any of the following is true:

the buffer is full. In this case, the buffer size defaults to 1024 characters. The SIZE= option is ignored.
a character that is contained in the terminator string is encountered.
you press Enter.

BUFFERFULL (only)

causes input to be terminated when either of the following is true:

the buffer is full
you press Enter.

NOBUFFERFULL (only)

causes input to be terminated when either of the following is true:

the buffer is full. In this case, the buffer size defaults to 1024 characters.
you press Enter.

TERMINATOR= (only)

causes input to be terminated when any of the following is true:

the buffer is full. In this case, the buffer size defaults to 1024 characters.
a character that is contained in the terminator string is encountered.
you press Enter.

The default is NOBUFFERFULL.

ECHO | NOECHO

indicates whether data typed at the terminal is echoed on the monitor. If this attribute is not set, the behavior is based on the LOCALECHO characteristic for the terminal specified with DEVICE=. The following DCL command shows the characteristics for the terminal:

$ SHOW TERMINAL name

SIZE=n

sets the size of the input buffer (that is, the number of characters that can be read at one time). The value can be no more than 200, the maximum size of a character variable in SAS. The default is 200 characters.

TERMINATOR=hex-string

specifies the list of characters that are considered to be terminating characters for input. The hex-string consists of hexadecimal character pairs that correspond to the ASCII value of the characters used as terminators. Do not separate the digit pairs with delimiters such as commas or spaces.

If NOBUFFERFULL is in effect, the default terminator is a carriage return (hexadecimal value is 0D).

TIMEOUT=n

specifies how many seconds to wait for input from the terminal. If no input is received in the time specified, the operation fails with a time-out error. By default, there is no time limit and the input operation waits forever.

channel

is a numeric variable into which the TTOPEN function places the channel number.

Details

The channel that the TTOPEN function assigns is used by the other terminal-access functions to perform I/O to and from the terminal. If the TTOPEN function executes successfully, the return value is 0. Otherwise, the return value is the OpenVMS error code that indicates why it failed.

Example

The following example reads up to 20 characters, discarding extra characters when the buffer is full and accepting either the carriage return or the horizontal tab character (hexadecimal value is 09) as terminators. If the read is successful, the program prints the string:

length string $ 20;
rc=ttopen("dev=TT: size=20 term=0D09",chan);
rc=ttread(chan,string,size);
if size>0 & rc=0 then put string;
rc=ttclose(chan);