The set-imap BASIC program 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.
The set-imap command has additional functionality over that of the set-func command (no longer supported); multiple characters may be used, and no lead character is required.
A null item has been added to the keyboards file so that a set-imap null sets the function keys to null.
set-imap {item-ID{time.out}} {(options}
| item-ID | Item-ID of the translation table, located in the keyboards file in the dm account. The format of the keyboard item is described in keyboards file. 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 recompiled, unless the c option is used. A null item sets the function keys to null. | |
| 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 time-out 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, such as network delays, to detect sequences of characters properly. If the time out is 0, the translation mechanism waits indefinitely between characters of a sequence until either a valid sequence is received or until an unexpected character breaks a sequence. The time out does not apply to output translation. For information on adjusting the time-out value, see Caution below. | |
| 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 the item is modified. The item is compiled into a binary item and stored in the dictionary of the keyboards file. | |
| v | Verbose option displays information about the translation table (name and size) and the modifiers used in attribute one. | |
Input translation can be used to translate special key sequences, such as pressing ESC, [ , A, into a sequence understandable by the application.
Output 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 desequentialized 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 time-out, but there are some restrictions (see Caution below).
The translation is described in a table which is associated to each port. 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 characters in length. 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.
Pressing BREAK 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.
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.
The set-imap command can be called automatically by the TCL term command 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.
For UNIX: The resolution is typically 10 milliseconds and 50 milliseconds on non-UNIX implementations. Therefore, a time out of 15 milliseconds is rounded up to 20 milliseconds on UNIX and 50 milliseconds on a non-UNIX system.
For Windows: The time out resolution is 50 milliseconds. If the input buffer of the process becomes full, some sequences may be aborted and/or truncated. If high system or communication load creates abnormal delays, it is possible that an input sequence is decoded incorrectly. For example, if network conditions create large delays between characters, it is conceivable that an Esc, [, A reaches the computer as an escape character, followed by [, then A character sequence, thus breaking the sequence. This may be especially true using a network where data may be broken into packets. In these situations, it may be necessary to set a larger time out value, thus opening the possibility that a user can use discrete keys, such as ESC, [, and A, which could be interpreted as a sequence.
crt ’st’ crt ’art’Applying output translation to echo input data, multicharacter sequences can cause some apparent delay in the echo process. For example, assume the system is set to translate on output abc into ABC, so that typing abc will echo ABC. Do not confuse the translation of the echo and the translation of the actual data, though they should be identical for obvious clarity reasons, if the user types the string, this occurs:
User Input Display ---------------- a b c ABC a x ax a aNo echo, because this may be the beginning of a sequence, but the application actually receives the a.
bThere is still no echo.
c ABCThe sequence is converted and displays.
aNo echo, as above.
x axThe x breaks the sequence and the data displays. If a character is being translated, and this character can occur in an otherwise normal escape character sequence generated, for example, by a FlashBASIC @ function, the escape character sequence is broken. For example, if all @ functions are translated into an escape character sequence Esc, c']',x'31', and if, for the specified terminal, the clear screen character sequence is Esc, c'@', then the end result is Esc,Esc, c']',x'31', which is not correct. Extreme care must be used when defining the output translation on single characters.
Sets the keyboard translation to an ibm3151.
set-imap ibm3151
Sets the keyboard translation to a Wy-50, changing the time out to 100 milliseconds, on port 24.
set-imap wy-50 100 (24
Sets the keyboard translation to an att605, recompiling the item first.
set-imap att605 (c
Disables the keyboard input translation.
set-imap