| set-half | Index Level | set-incremental |
| Syntax | set-imap {item.id {time.out}} {(options} |
| Category | TCL |
| Type | Verb |
| 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 Reference Manual 'keyboards' entry 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. "item.id" 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 Reference Manual entry '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 "item.id" 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 D3/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. |
| 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 "item.id" is modified. "item.id" 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. |
| See Also | set-iomap set-kbrd keyboards term iomap-file term-type define-up |
| Example |
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. set-imap Disables the keyboard input translation. |
| Warnings |
Depending on the implementation, the time out may have a resolution less than the millisecond. On Unix implementations, the resolution is typically 10 milliseconds and 50 milliseconds on non-unix implementations. Therefore, a time out of 15 milliseconds will be rounded up to 20 milliseconds on Unix and 50 milliseconds on non-Unix.
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 will be decoded incorrectly. For example, if network conditions create large delays between characters, it is conceivable that an 'ESC [ A' sequence will reach the computer as an ESC followed by '[ A', thus breaking the sequence. This might be especially true using a network where data may be 'packetised'. In these situations, it might be necessary to set a larger time out value, thus opening the possibility that a user might type discrete keys, like ESC, then '[', then 'A', which could be interpreted as a sequence. When translating output, there are some restrictions on how the data is processed: - In FlashBASIC, all the data in an input sequence must be within one PRINT or CRT statement. For example, if 'START' is to be translated into another string, then: crt 'START' will be translated correctly, but: crt 'ST': crt 'ART' will not. - Applying output translation to the echoing of input data, multi-character sequences can cause some apparent delay in the echoing. For example, assume the system is set to translate on OUTPUT 'abc' into 'ABC', so that typing 'abc' will infact echo 'ABC' (NOTE: 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, the following will occur: User Input Display ---------- ------- a (NO echo, because this might be the beginning of a sequence, but the application actually receives the 'a') b (Still no echo) c ABC (The sequence was converted properly and displayed) a (No echo, as above) x ax (The 'x' broke the sequence. The data is displayed) - If a character is being translated, and this character may occur in an otherwise normal escape sequence generated, by exemple, by a FlashBASIC '@' function, the escape sequence will be broken. For example, if all '@' signs were to be translated into an escape sequence ESC,c']',x'31', for example, and if, for the given terminal, the clear screen sequence is ESC,c'@', then the end result will be ESC,ESC,c']',x'31', which is not correct. Extreme care must be used when defining output translation on single characters. |
| Compatibility | D3 7.0 AP AP 6.1 |
| set-half | Index Level | set-incremental |