SECTION 4 -- TERMINAL I/O FUNCITONS

The terminal I/O package provides function calls for reading and writing to the terminal associated with an interactive program.

The screen-oriented functions (clear screen, position cursor, etc.) work only for CRTs that are supported by TAE. The types of CRT terminals supported depend upon the host system. The VAX/VMS implementation of TAE supports VT100, VT52, and any other terminal for which the installation has TERMTABLE support. UNIX implementations of TAE support any CRT described in the /etc/termcap file.

Note that the t_init function must be called once before any other t_ calls are executed. Along with determining the number of lines and columns for a CRT terminal, t_init determines the type of terminal (T_CRT, T_NOTCRT, or T_NOTTERM). Section 4.3 describes t_init in more detail.

Also note that for all cursor positioning functions, line 1, column 1 is the upper left on the screen.

4.1 t_clear - Clear Screen

CODE t_clear ()

Function return:

SUCCESS: the CRT screen was successfully cleared.
P_FAIL: general failure indication.

Argument: None

t_clear is called to clear the CRT screen. After the screen is cleared, the cursor is positioned at line 1, column 1. t_clear requires a terminal type of T_CRT (See section 4.3.).

4.2 t_highlight - Highlight a String

COUNT t_highlight (string)

Function return:

Total length of escape sequences added to the string.
If zero, the CRT cannot support highlighting.

Argument:

```
string: input/output, TEXT string[];
```
String to be highlighted.

t_highlight produces a new string with the necessary escape sequences for highlighting.

4.3 t_init - Initialize Terminal Package

CODE t_init (lines, columns, type)

Function return:

SUCCESS: the Terminal Package was successfully initialized.
P_FAIL: general failure indication.

Arguments:

```
lines: output, COUNT *lines;
```
Number of lines for the CRT terminal. Lines is zero if the terminal is not a CRT or if the terminal is of unknown type.
```
columns: output, COUNT *columns;
```
Number of columns for a CRT terminal. Columns is zero if the terminal is not a CRT or if the terminal is of unknown type.
```
type: output, CODE *type;
```
- T_CRT if the terminal is a supported CRT.
- TNOTCRT if the terminal is not a supported CRT.
- T_NOTTERM if the device is not a terminal; this code usually indicates that the program is running in batch or asynchronous mode.

t_init is the initialization call for the t_ package. Lines, columns, and type are integer output arguments describing characteristics of the terminal associated with the process. t_init must be called once before any other t_ calls.

NOTE: In some cases, when the "terminal" is an X Window System terminal emulator, t_init is not appropriate. See t_pinit for an appropriate alternative.

4.4 t_input - Read Line from CRT

CODE tinput (line, column, string, term)

Function return:

SUCCESS: the text line at the specified position was successfully read from the CRT.
P_FAIL: general failure indication.

Arguments:

```
line: input, FUNINT line;
```
Line number, starting at 1, of initial cursor position.
```
column: input, FUNINT column;
```
Column number, starting at 1, of initial cursor position.
```
string: output, TEXT string[STRINGSIZ+1];
```
Output character string. This string does not include the terminator. String should be declared large enough to hold the longest line.
```
term: output, CODE *term;
```
- T_CR: the line was terminated by a carriage return.
- T_ESCAPE: the line was terminated by an escape key.
- P_OVER: string was declared smaller than the received line.

The t_input reads characters from the terminal at the specified line and column. The user may terminate the line with a carriage return or an escape. t_input requires a terminal type of T_CRT.

4.5 t_lclear - Clear Line on CRT

CODE t_lclear (line, column)

Function return:

SUCCESS: the line starting at the specified column was successfully cleared on the CRT.
P_FAIL: general failure indication.

Arguments:

```
line: input, FUNINT line;
```
Line number, starting at 1, to clear.
```
column: input, FUNINT column;
```
Column number, starting at 1, to begin clearing the line.

t_lclear will clear everything to the right of and including the specified column number for the line number specified. t_lclear requires a terminal type of T_CRT.

4.6 t_output - Write Line to CRT

CODE t_output (line, column, string)

Function return:

SUCCESS: the text line was successfully written to the specified position on the CRT.
P_FAIL: general failure indication.

Arguments:

```
line: input, FUNINT line;
```
Line number, starting at 1, of first character position.
```
column: input, FUNINT column;
```
Column number, starting at 1, of first character position.
```
string: input, TEXT string[];
```
Character string to be written to the CRT terminal.

t_output writes a character string beginning at the specified cursor location. The characters are written exactly as contained in string--there is no automatic carriage control. If the string extends beyond the rightmost column, the results are undefined. t_output requires a terminal type of T_CRT.

4.7 t_pinit - Special Terminal Initialization

CODE t_pinit (termlines, termcols, termtype)

Function return:

SUCCESS: the Terminal Package was successfully initialized.
P_FAIL: general failure indication.

Arguments:

```
lines: output, COUNT *lines;
```
Number of lines for the CRT terminal. Lines is zero if the terminal is not a CRT or if the terminal is of unknown type.
```
columns: output, COUNT *columns;
```
Number of columns for a CRT terminal. Columns is zero if the terminal is not a CRT or if the terminal is of unknown type.
```
type: output, CODE *type;
```
- T_CRT if the terminal is a supported CRT.
- T_NOTCRT if the terminal is not a supported CRT.
- T_NOTTERM if the device is not a terminal; this code usually indicates that the program is running in batch or asynchronous mode.

t_pinit is used for "process initialization" of the terminal. t_pinit is identical to t_init with the exception that the terminal is not reset. This function allows a process to avoid re-initializing a terminal that has already been initialized by TAE's Monitor. t_pinit exists because initializing some terminals (e.g., the terminal emulator under the X Window System) causes the screen to clear, often an undesirable effect.

To use t_pinit in a process, place the call before all other TAE function calls, including z_init.

4.8 t_pos - Position Cursor

CODE t_pos (line, column)

Function return:

SUCCESS: the cursor was successfully positioned on the CRT.
P_FAIL: general failure indication.

Arguments:

```
line: input, FUNINT line;
```
Line number, starting at 1, for cursor position.
```
column: input, FUNINT column;
```
Column number, starting at 1, for cursor position.

t_pos positions the CRT cursor. If line and/or column exceed the CRT's dimensions, the result is undefined. t_pos requires a terminal type of T_CRT.

4.9 t_read - Read Line from Terminal

CODE t_read (string, term)

Function return:

SUCCESS: the text line was successfully read from terminal.
P_FAIL: general failure indication.

Arguments:

```
string: output, TEXT string[STRINGSIZ+1];
```
Output character string. This string does not include the terminator. String should be declared large enough to hold the longest line.
```
term: output, CODE *term;
```
- T_CR: the line was terminated by a carriage return.
- T_ESCAPE:the line was terminated by an escape key.
- P OVER: string was declared smaller than the received line.

t_read reads a line from the terminal. It is used for terminal input when the caller does not depend upon the terminal being a cursor addressable CRT. The user may terminate the line with a carriage return or an escape.

4.10 t_write - Write Line to Terminal

CODE t_write (string, cc)

Function return:

SUCCESS: the text line was successfully written to terminal.
P_FAIL: general failure indication.

Arguments:

```
string: input, TEXT string[];
```
The string to be written to the terminal.
```
cc: input, FUNINT cc;
```
The type of carriage control desired:
- T_STDCC: Standard carriage control - newline, print buffer, carriage return.
- T_NULL: No carriage control. The string is transmitted exactly as the characters appear in the string argument.
- T_PROMPT: "Prompting" carriage control - newline, print buffer.
- T_DOUBLE: Double space control - newline, print buffer, newline.

t write writes a line to the terminal. It is used for terminal output when the caller does not depend upon the terminal being a cursor addressable CRT.