tcl.set-imap Verb: Access/TCL


Command tcl.set-imap Verb: Access/TCL
Applicable release versions: AP, AP 6.1
Category TCL (746)
Description defines a keyboard input and/or a terminal output translation table, through which any sequence of keyboard input and terminal output characters can be translated into any other sequence of characters.
Input translation can be used to translate special key sequences, like "ESC [ A", into a sequence understandable by the application.
Ouput translation can be used to convert a character into an appropriate escape sequence, for example, to change fonts on a printer, print the character, and change the fonts back.

The translation is based on the notion of 'input sequence', which is a variable-length series of characters which must be received completely within a given time, typically 1/10th of a second, to be recognized as one key stroke, and converted into an output sequence. If an input sequence is not received within the specified time, or if a character received is not part of a valid sequence, the sequence is aborted, and all characters received so far are 'de-sequentialized' and passed to the application or displayed as a series of discrete characters.
When applied to a terminal output translation, there is no notion of timeout, but there are some restrictions (see the section 'Warnings' below).

The translation is described in a table which is associated to each port. See the REF documentation 'keyboards' for the format of the table. A table can be shared among different ports. Each input and output table contains a 'main' translation table and an optional 'alternate' table. The two tables have identical structure and capabilities. The main table is active when the translation is activated. A special input sequence can be defined to switch to the alternate table until it is switched manually back, or for one translation (keystroke) only.

An input sequence can have from one to 127 characters. An output sequence can be from 0 to 127 character long. If an output sequence is null, the corresponding key is made inoperative (input) or the data is not displayed (output).

Without a numeric option, the current port is affected. Optionally, a specific port can be specified by using the port number as a numeric option.

A <BREAK> key aborts any pending sequence and sets the main translation table as the active one.

If there is no argument, the translation mechanism, if currently active, is disabled.

"" The item-id of the translation table, located in the 'keyboards' file in the 'dm' account. The format of the keyboard item is described in the REF documentation 'keyboards'. If the item has already been compiled into a translation table and stored as a binary item in the dictionary of the file, the translation item is not re-compiled, unless the "c" option is used.

"time.out" Value of the time out, expressed in milliseconds, after which an incomplete input sequence is aborted. If not specified, the value defined in the item "" by the 'timeout value' modifier in attribute one, is used. If none is specified, the default value is 100 milliseconds. The "time.out" should be adjusted to the baud rate and possible special conditions, like network delays, to detect sequences of characters properly. If "time.out" is 0, the translation mechanism will wait indefinitely between characters of a sequence until either a valid sequence is received or until an unexpected character 'breaks' a sequence. The timeout does not apply to output translation. See the section "warning" below for information about adjusting the timeout value.

If the one-to-one input/output translation defined by the TCL command 'set-iomap' is also active on this port, the translation defined by 'set-imap' is processed first, and each character of the resulting string is passed through the one-to-one conversion table set by 'set-iomap'.

When used on PC-based AP/SCO or AP/Native, the keyboard setting defined by 'set-kbrd' is processed first.

set-imap can be called automatically by the TCL command TERM with the (K) option, if the item defining the terminal has the name of a keyboard translation item in the value 4 of attribute 1.
Syntax set-imap { {time.out}} {(options}
Options port.number Port number in decimal. If not specified, the current port is used.

c Compiles the item. This option must be used when "" is modified. "" is compiled into a binary item and stored in the dictionary of the "keyboards" file.

v "verbose". Displays information about the translation table (name, size) and the modifiers used in attribute one.
set-imap ibm3151
  Sets the keyboard translation to an ibm3151.

set-imap wy-50 100 (24
  Sets the keyboard translation to a wy-50, changing the timeout to 100 ms, on 
port 24.

set-imap att605 (c
  Sets the keyboard translation to an att605, recompiling the item first.

  Disables the keyboard input translation.
Related tcl.set-iomap