Using Terminals

A GT.M process assigns $PRINCIPAL to the UNIX standard input of the process (for READ) and standard output (for WRITE). For a local interactive process, $PRINCIPAL identifies the "terminal" from which the user is signed on.

While all terminals support the CTRAP deviceparameter, only $PRINCIPAL supports CENABLE. While CTRAP allows terminal input to redirect program flow, CENABLE allows the terminal user to invoke the Direct Mode.

Directly connected printers often appear to GT.M as a terminal (although printers generally do not provide input) regardless of whether the printer is connected to the computer with a high speed parallel interface, or an asynchronous terminal controller.

Setting Terminal Characteristics

GT.M does not isolate its handling of terminal characteristics from the operating system environment at large. GT.M inherits the operating system terminal characteristics in effect at the time the GT.M image is invoked. When GT.M exits, the terminal characteristics known by the operating system are restored.

However, if the process temporarily leaves the GT.M environment with a ZSYSTEM command , GT.M does not recognize any changes to the terminal characteristics left by the external environment. This may cause disparities between the physical behavior of the terminal, and the perceived behavior by GT.M.

UNIX enforces standard device security for explicit OPENs of terminals other than the sign-in terminal ($PRINCIPAL). If you are unable to OPEN a terminal, contact your system manager.

USE of a terminal causes the device driver to flush the output buffer. This feature of the USE command provides routine control over the timing of output, which is occasionally required. However, it also means that redundant USE commands may induce an unnecessary performance penalty. Therefore, FIS recommends restricting USE commands to redirecting I/O, modifying deviceparameters, and initiating specifically required flushes.

The terminal input buffer size is fixed at 1024 on UNIX and a variable read terminates after 1023 characters.

Setting the environment variable TERM

The environment variable $TERM must specify a terminfo entry that accurately matches the terminal (or terminal emulator) settings. Refer to the terminfo man pages for more information on the terminal settings of the platform where GT.M needs to run.

Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation. The terminal (emulator) vendor may also be able to help.

GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis:

auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1),cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1),key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines). 

GT.M sends keypad_xmit before terminal reads for direct mode and READs (other than READ *) if EDITING is enabled. GT.M sends keypad_local after these terminal reads.

Logical Records for Terminals

A logical record for a terminal equates to a line on the physical screen. The WIDTH device characteristic specifies the width of the screen, while the LENGTH device characteristic specifies the number of lines on the screen.

READ * Command for Terminals

If the terminal has ESCAPE sequencing enabled, and the input contains a valid escape sequence or a terminator character, GT.M stores the entire sequence in $ZB and returns the ASCII representation of the first character.

Example:

GTM>kill
GTM>use $principal:escape
GTM>read *x set zb=$zb zwrite
(Press the F11 key on the VT220 terminal keyboard)
x=27
zb=$C(27)_"[23~"

This enters an escape sequence in response to a READ *. The READ * assigns the code for <ESC> to the variable X. GT.M places the entire escape sequence in $ZB. As some of the characters are not graphic, that is, visible on a terminal, the example transfers the contents of $ZB to the local variable ZB and uses a ZWRITE so that the non-graphic characters appear in $CHAR() format.

When escape processing is disabled, READ *x returns 27 in x for an <ESC>. If the escape introducer is also a TERMINATOR, $ZB has a string of length one (1), and a value of the $ASCII() representation of the escape introducer; otherwise, $ZB holds the empty string. GT.M stores the remaining characters of the escape sequence in the input stream. A READ command following a READ * command returns the remaining characters of the escape sequence.

Example:

GTM>kill
GTM>use $principal:(noescape:term=$char(13))
GTM>read *x set zb=$zb read y:0 zwrite
(Press the F11 key on the terminal keyboard)
[23~x=27
y="[23~"
zb=""
GTM>use $principal:noecho read *x set zb=$zb read y:0 use $principal:echo zwrite
x=27
y="[23~"
zb=""
GTM>read *x set zb=$zb use $principal:flush read y:0 zwrite
x=27
y=""
zb=""

While the first READ Y:0 picks up the sequence after the first character, notice how the graphic portion of the sequence appears on the terminal – this is because the READ *X separated the escape character from the rest of the sequence thus preventing the terminal driver logic from recognizing it as a sequence, and suppressing its echo. The explicit suppression of echo removes this visual artifact. In the case of the final READ *X, the FLUSH clears the input buffer so that it is empty by the time of the READ Y:0.

READ X#maxlen Command for Terminals

Generally, GT.M performs the same maintenance on $ZB for a READ X#maxlen as for a READ. However, if the READ X#maxlen terminates because the input has reached the maximum length, GT.M sets $ZB to null. When the terminal has ESCAPE sequencing enabled, and the input contains an escape sequence, GT.M sets $ZB to contain the escape sequence.

Terminal Deviceparameter Summary

The following tables provide a brief summary of deviceparameters for terminals, grouped into related areas. For detailed information, refer to “Open”, “Use”, and “Close”.

Error Processing Deviceparameters

DEVICEPARAMETER

COMMAND

COMMENT

EXCEPTION=expr

O/U/C

Controls device-specific error handling.

Interaction Management Deviceparameters

DEVICEPARAMETER

COMMAND

COMMENT

[NO]CENABLE

U

Controls whether <CTRL-C> on $PRINCIPAL causes GT.M to go to direct mode.

CTRAP=expr

U

Controls vectoring on trapped <CTRL> characters.

[NO]ESCAPE

U

Controls escape sequence processing.

[NO]PASTHRU

U

Controls interpretation by the operating system of special control characters (for example <CTRL-B>).

[NO]TERMINATOR[=expr]

U

Controls characters that end a READ

Flow Control Deviceparameters

DEVICEPARAMETER

COMMAND

COMMENT

[NO]CONVERT

U

Controls forcing input to uppercase.

[NO]FILTER

U

Controls some $X, $Y maintenance.

FLUSH

U

Clears the typeahead buffer.

[NO]HOSTSYNC

U

Controls host's use of XON/XOFF.

[NO]READSYNC

U

Controls wrapping READs in XON/XOFF.

[NO]TTSYNC

U

Controls input response to XON/XOFF.

[NO]TYPEAHEAD

U

Controls unsolicited input handling.

Screen Management Deviceparameters

DEVICEPARAMETER

COMMAND

COMMENT

CLEARSCREEN

U

Clears from cursor to end-of-screen.

DOWNSCROLL

U

Moves display down one line.

[NO]ECHO

U

Controls the host echo of input.

ERASELINE

U

Clears from cursor to end-of-line.

[Z]LENGTH=intexpr

U

Controls maximum number of lines on a page ($Y).

UPSCROLL

U

Moves display up one line.

[Z]WIDTH=intexpr

U

Controls the maximum width of an output line ($X).

[Z][NO]WRAP

U

Controls handling of output lines longer than the maximum width.

X=intexpr

U

Positions the cursor to column intexpr.

Y=intexpr

U

Positions the cursor to row intexpr.

O: Applies to the OPEN command

U: Applies to the USE command

C: Applies to the CLOSE command

Terminal Examples

This section contains examples of GT.M terminal handling.

Example:

use $principal:(exception="zg "_$zl_":C^MENU")

This example USEs the principal device, and sets up an EXCEPTION handler. When an error occurs, it transfers control to label C in the routine ^MENU at the process stack level where the EXCEPTION was established.

Example:

use $principal:(x=0:y=0:clearscreen)

This example positions the cursor to the upper left-hand corner and clears the entire screen.

Example:

use $principal:(noecho:width=132:wrap)

This example disables ECHOing, enables automatic WRAPping, and sets the line width to 132 characters.

Note that GT.M enables WRAP automatically when you specify the WIDTH deviceparameter.

Example:

use $principal:nocenable

This example disables <CTRL-C>.