1 Introduction
User Defined Keys are a Level 2 extension, which provide the capability of loading into the terminal key definition strings which subsequently be transmitted using a single key stroke. The format for loading key definition strings is intended to be extensible to future devices which have more complex keyboards, larger memories, or other forms of input processing. Conforming Level 2 devices which implement this extension, however, are required to provide only fifteen programmable keys, with a total buffer space of at least 256 characters.
It should be noted that conformance to this standard does not require the ability to retain the key definitions in non-volatile memory. That is, the loaded definitions may be lost if the terminal is powered off. On the other hand, non-volatile storage and restoration of the key definition strings is not precluded. Furthermore, conformance does not preclude a device from providing the ability to interact locally with the key definitions (input, edit, or delete), provided that it is done in keeping with the intent of this standard.
2 Functional Description
2.1 Programmable Keys
The keys which may be programmed in Level 2 devices are all of the keys in the Application Function Key Row, when used in combination with the Shift key (see the section "Keyboard Processing" for a complete description of the keyboard). The keys may only be programmed, and are only operational, when the terminal is in Level 2 operation (as selected by the control function Select Conformance Level (DECSCL); see the section "Terminal Management" for a complete description of the DECSCL function). When the terminal is in Level 1 operation (or in VT52 mode), the DECUDK control function is ignored and the keys are "dead" (i.e., they do not transmit and do not keyclick).
2.2 Default Definitions
Programmable keys which have not been defined, or have had their definitions erased, do not transmit and therefore do not keyclick. Programmable keys which have been defined do keyclick, and are also subject to all of the requirements of the lower level transmission layers, such as XON/XOFF flow control, rate limiting, and C1 Control Code translation.
2.3 Key Definitions
The definition for each key consists of a variable length character string of 0 to 255 7-bit or 8-bit characters. Each character in the string is a code in the range 0/0 through 15/15. Thus, any character in the code table may be included within a key definition.
Buffer space for the key definitions is supplied on a first come first serve basis. Once the supplied buffer space is used up, no more keys may be defined unless space is freed up. Space may be freed up either by redefining previously defined keys using shorter strings than before, clearing key definitions using the DECUDK control function, or clearing the entire definition set (through a terminal power up reset).
2.4 Lock Control
The terminal uses a special lock to arbitrate the programming of User Defined Keys. This lock can be turned on or off through Setup mode. It may also be turned on (but not off) from the host using the DECUDK control function. The lock acts globally over all programmable keys.
The state of the Lock Control may be determined from the host using the Device Status Report control function.
3 Control Functions
Report UDK Status — DSR
Levels: 2
Purpose: Report the status of the UDK Lock Control.
Request Format:
CSI ? 25 n 9/11 3/15 3/2 3/5 6/14
Report Format:
CSI ? Ps n 9/11 3/15 Ps 6/14
Description: The DSR control function (Device Status Report) may be used to request the current status of the UDK Lock Control. (See the section "Terminal Management" for a complete description of Device Status Report.) The terminal will respond to a UDK status request (CSI ? 25 n) by transmitting a Device Status Report control sequence containing one of the following selective parameters (preceded by the private parameter value ?, 3/15):
| Selective Parameter | Meaning |
|---|---|
| 20 | The User Defined Keys are not locked, and all keys may be defined, cleared, or redefined from the host. |
| 21 | The User Defined Keys are locked, and may not be defined, cleared, or redefined from the host. |
| 23 | No User Defined Keys are present. The device does not support this extension. |
Notes:
A report will be given even if the UDK extension is not supported. Thus, this request is an optional means of determining if the extension is present (the other means being the Primary Device Attributes request, as described in the section "Terminal Management").
State Affected: None
Algorithm:
PROCEDURE REPORT_UDK_STATUS;
BEGIN
IF LEVEL_2_EXTENSIONS[UDK] THEN
BEGIN
CASE UDK_LOCK_CONTROL OF
UDK_LOCK_OFF: WRITE (HOST_PORT,'<CSI>?20n');
UDK_LOCK_ON: WRITE (HOST_PORT,'<CSI>?21n');
END;
END
ELSE WRITE (HOST_PORT,'<CSI>?23n');
END;
Known Deviations: None
User Defined Keys — DECUDK
Levels: 2X
Purpose: Down line load User Defined Key sequences.
Format: The DECUDK control is a Device Control String consisting of an introducer sequence, followed by a command string. The format of the introducer sequence is:
DCS Pe ; Pl | 9/0 Pe ; Pl 7/12
The introducer sequence is terminated by the final character | (7/12).
The command string format is:
Ky1 / St1 ; Ky2 / St2 ; ... ; Kyn / Stn ST
The command string is terminated by the String Terminator character 9/13 (in 7-bits, ESC \, or 1/11 5/12). See the section "Code Extension Layer" for a complete description of the Device Control String format.
Description: DECUDK control down line loads one or more key definitions into the User Defined Keys. This sequence is ignored if the UDKs have been locked, either through a previous DECUDK sequence or as a local terminal function. This sequence executes only when the terminal is in Level 2 operation.
Notes:
Software should use the UDK function to reclaim key definition space in the device. This can be done by clearing keys without locking them. Once the keys have been cleared the UDK function can be used to redefine the keys and lock them.
Host software should not generally leave the user defined keys unlocked. This may cause a breach of security to the terminal user.
The host must keep track of space available for key definitions. No error indication is given if the available buffer space is filled up.
If a key is redefined the old sequence is lost. This may free up space if the new sequence is shorter than the previous definition.
3.1 Introducer Sequence Format
The following selective parameter values in the introducer sequence may effect the interpretation of the command string. All parameters have the same syntax as a control sequence and may be omitted, in which case the default values are used.
Parameter (Pe): Erase Control
The first parameter controls which key definitions are to be cleared before loading takes place, according to:
- 0 - Clear all UDKs before loading new values (default)
- 1 - Load new UDK values, clear old only when redefined
By using Pe=1, it is possible to redefine some keys without reloading them all.
Note that if the clear parameter is set to 1 (load new, but don't clear old) it is possible that a key load might fail, due to lack of buffer room, even though the final total for all keys would have been 256 bytes or less. This is because all keys are cleared and loaded sequentially. Sequential loading without first clearing the key definitions could result in intermediate storage requirements greater than the maximum provided, even though the final requirement would be less than or equal to the maximum. For example: If F6 contained 120 bytes, F7 contained 110 bytes, and F8 contained 20 bytes, loading F8 with 40 bytes, F6 with 1 byte and F7 with 1 byte works if all UDKs are cleared first, but not if the keys are cleared as they are sequentially redefined. (When the user attempts to load F8 with 40 bytes, the load will fail, because only 26 bytes are free at that time (256-120-110=26)).
Parameter (Pl): Lock Control
The second parameter permits the keys to be locked against subsequent deletion or re-definition. Locking the keys does not effect the definitions included in the current DECUDK sequence (unless the keys were previously locked), but causes all subsequent DECUDK sequences to be ignored (until the lock is cleared by the terminal user under local control). The following selective parameters may be specified:
- 0 - Lock the UDKs against future redefinition (default)
- 1 - Don't lock the UDKs against future redefinition
Note that Pl=1 does not unlock the UDKs, it just does not lock them.
The Final character | (7/12) indicates that this DCS string is the DECUDK control function. The data following it up to the String Terminator (ST) is from 2/0 through 7/14 and represents the actual key loading command.
3.2 Command String Format
The syntax of the DECUDK command string is as follows:
Key definition strings, Kyn/Stn, are included in the data following the Final character and before the String Terminator (ST). Each Key Definition String consists of a Key Selector Number, Kyn, and a String Parameter, Stn, separated by a slash "/". Multiple Key definition strings are separated by semi-colon ";".
Bit combinations 0/8 to 0/13 may be included in the command string, and have no effect on the interpretation of the data. They permit convenient formatting of command strings when being created by text editors since TAB, CR, and LF are included in this range. The following bit combinations are considered as error conditions when they occur within the character font data. Their processing is UNDEFINED by the architecture. It is recommended to hardware implementors that they be ignored for future compatibility.
0/1 through 0/7
0/14 through 2/14 (with the exception of ESC, 1/11 when it is followed immediately by \, 5/12, to form the two character ESC Fe sequence String Terminator)
3/10
3/12 through 4/0
4/7 through 6/0
6/7 through 15/15 (with the exception of ST, 9/12)
These characters should not be used by conforming software.
3.2.1 Key Selection Codes
Key selection codes are specified as string of characters in the range 3/0 through 3/9 ("0" through "9"), indicating a single decimal value. The values which may be specified in Level 2 are the parameter values of the control sequences normally transmitted by the programmable keys when they are not pressed in combination with the Shift key (CSI ? Pn ~). (See the section "Keyboard Processing" for a complete description of the codes transmitted by the Application Function Keys.)
The following table indicates the relationship between the specified value and actual keys on the keyboard:
| Key Selection Code | Related Key |
|---|---|
| 17 | F6 |
| 18 | F7 |
| 19 | F8 |
| 20 | F9 |
| 21 | F10 |
| 23 | F11 |
| 24 | F12 |
| 25 | F13 |
| 26 | F14 |
| 28 | Help Key |
| 29 | Do Key |
| 31 | F17 |
| 32 | F18 |
| 33 | F19 |
| 34 | F20 |
Key selectors may be in any order and may be specified multiple times within the string. If multiple definitions of a key occur, the last definition is preserved. If no key definition is specified for a selected key, that UDK will be cleared of it's definition.
3.2.2 String Parameters
The string parameters, Stn, are the encoded contents of the UDKs. They consist of hex pairs in the range 3/0 - 3/9 ("0" through "9"), 4/1 - 4/6 ("A" through "F"), and 6/1 - 6/6 ("a" through "f"). When these hex values are combined they represent an 8-bit quantity. This allows any of the 256 character codes to be used in the UDK sequence. The 8-bit code is loaded high byte first, then low byte, as shown below:
1st hex value 2nd hex value +-------------------------------+ | high nibble | low nibble | | of code | of code | +-------------------------------+
3.3 Error Conditions
The following error conditions may occur, and have the specified recovery:
Partial Hex Code - If an odd number of hex values is received in any of the string definitions, the current key definition and the entire remainder of the load sequence will be ignored. The Lock Control will also be set (UDK Lock On).
Key Code Out of Range - If a key selection code is received which does not represent a programmable key in the device, the entire definition for that key will be processed and ignored. The remainder of the string will be processed normally.
Null Key Definition - If two key definition separators (semi-colons) occur together, with no properly terminated key selection code intervening, the characters between the semi-colons will be ignored. The remainder of the string will be processed normally.
3.4 Algorithm
NOTE: For the sake of clarity, the following algorithm was coded using an excess of UDK buffer memory and working buffers. It should be recognized that the memory management schemes which will probably be required in many implementations will make this procedure much more complex.
State Affected:
UDK: UDK_TYPE;TOTAL_COUNT: 0..MAX_SIZE_UDK_BUFFER;UDK_LOCK_CONTROL: (UDK_LOCK_OFF,UDK_LOCK_ON);UDK_BUFFER_OVERFLOW: BOOLEAN;
Algorithm:
CONST MIN_UDK_VALUE = 17;
MAX_UDK_VALUE = 35;
MAX_SIZE_UDK_BUFFER = 256;
TYPE CODE_TYPE = 0..255;
KEY_DEFINITION_TYPE = RECORD
CODE_BUFFER:
ARRAY [1..MAX_SIZE_UDK_BUFFER] OF CODE_TYPE;
CODE_COUNT: 0..MAX_SIZE_UDK_BUFFER;
END;
UDK_RANGE = MIN_UDK_VALUE..MAX_UDK_VALUE;
LEGAL_UDK_VALUES_TYPE = SET OF UDK_RANGE;
UDK_TYPE =
ARRAY [UDK_RANGE] OF KEY_DEFINITION_TYPE;
VAR UDK: UDK_TYPE;
TOTAL_CODE_COUNT: 0..MAX_SIZE_UDK_BUFFER;
UDK_LOCK_CONTROL: (UDK_LOCK_OFF,UDK_LOCK_ON);
LEGAL_UDK_VALUES: LEGAL_UDK_VALUES_TYPE;
LOCK_SET: BOOLEAN;
UDK_ERASE_CONTROL: (NO_ERASE_UDK,ERASE_ALL_UDK);
VALID_UDK_SYNTAX: BOOLEAN;
UDK_STRING_TERMINATED: BOOLEAN;
KEY_CODE: INTEGER;
KEY_CODE_TERMINATED: BOOLEAN;
HEX_CODE_VALUES: SET OF CODE_TYPE;
WORK_BUFFER:
ARRAY [1..MAX_SIZE_UDK_BUFFER] OF CODE_TYPE;
CODE_PAIR_TERMINATED: BOOLEAN;
DEFINITION_TERMINATED: BOOLEAN;
UDK_BUFFER_OVERFLOW: BOOLEAN;
I,N: INTEGER;
PROCEDURE GET_NEXT_EVENT (VAR EVENT: EVENT_BUFFER_TYPE); EXTERN;
PROCEDURE GET_UDK_PARAMETERS (EVENT: EVENT_BUFFER_TYPE); FORWARD;
PROCEDURE GET_KEY_CODE; FORWARD;
PROCEDURE GET_KEY_DEFINITION; FORWARD;
PROCEDURE FILL_KEYS; FORWARD;
PROCEDURE INITIALIZE_UDKS;
(*
This routine is called on power up reset to initialize
the UDK state information to its default values.
*)
BEGIN
(* the following codes are in the specified range,
and are the valid programmable key codes for Level 2 *)
LEGAL_UDK_VALUES:= [17..21,23..26,28..29,31..35];
(* the following are valid hex codes, 0-9, A-F, and a-f *)
HEX_CODE_VALUES:= [48..57,65..70,97..102];
UDK_BUFFER_OVERFLOW:= FALSE;
TOTAL_CODE_COUNT:= 0;
FOR N:= MIN_UDK_VALUE TO MAX_UDK_VALUE DO
UDK[N].CODE_COUNT:= 0;
(* NOTE: The actual value of the Lock Control on
initialization is specified by the user in Setup *)
UDK_LOCK_CONTROL:= UDK_LOCK_OFF;
END;
PROCEDURE EXECUTE_UDK (EVENT: EVENT_BUFFER_TYPE);
(*
This routine is called each time a DECUDK control
string introducer is received. It provides the top
level control for the key loading sequence.
*)
BEGIN
GET_UDK_PARAMETERS (EVENT);
IF VALID_UDK_SYNTAX THEN
BEGIN
UDK_STRING_TERMINATED:= FALSE;
IF UDK_LOCK_CONTROL = UDK_LOCK_OFF THEN
BEGIN
(* clear all udk's if requested *)
IF UDK_ERASE_CONTROL = ERASE_ALL_UDK THEN
BEGIN
FOR N:= MIN_UDK_VALUE TO MAX_UDK_VALUE DO
UDK[N].CODE_COUNT:= 0;
TOTAL_CODE_COUNT:= 0;
END;
(* then process the command string *)
FILL_KEYS;
END;
(* if locked or overflowed, keep going until the end *)
WHILE NOT UDK_STRING_TERMINATED DO
BEGIN
GET_NEXT_EVENT (EVENT);
IF (EVENT.EVENT_CODE = CONTROL_CODE)
AND (EVENT.CODE_VALUE = 156) THEN
UDK_STRING_TERMINATED:= TRUE;
END;
END;
(* set the lock if requested *)
IF LOCK_SET THEN UDK_LOCK_CONTROL:= UDK_LOCK_ON;
END;
PROCEDURE GET_UDK_PARAMETERS;
(* get all of the parameters for the load *)
BEGIN
VALID_UDK_SYNTAX:= TRUE;
CASE EVENT.PARAMETERS[1] OF
0: UDK_ERASE_CONTROL:= ERASE_ALL_UDK;
1: UDK_ERASE_CONTROL:= NO_ERASE_UDK;
OTHERWISE VALID_UDK_SYNTAX:= FALSE;
END;
CASE EVENT.PARAMETERS[2] OF
0: LOCK_SET:= TRUE;
1: LOCK_SET:= FALSE;
OTHERWISE VALID_UDK_SYNTAX:= FALSE;
END;
END;
PROCEDURE FILL_KEYS;
(*
This routine processes the command string and loads the
key definition strings into the appropriate key buffers.
*)
BEGIN
UDK_STRING_TERMINATED:= FALSE;
(* get all of the key definitions in the strings *)
REPEAT
KEY_CODE_TERMINATED:= FALSE;
DEFINITION_TERMINATED:= FALSE;
GET_KEY_CODE;
IF KEY_CODE_TERMINATED THEN
BEGIN
(* fill work buffer with code string *)
GET_KEY_DEFINITION;
(* ignore out of range key codes *)
IF (KEY_CODE IN LEGAL_UDK_VALUES)
AND (CODE_PAIR_TERMINATED) THEN
BEGIN
IF TOTAL_CODE_COUNT + I <= MAX_SIZE_UDK_BUFFER THEN
BEGIN
UDK[KEY_CODE].CODE_BUFFER:= WORK_BUFFER;
TOTAL_CODE_COUNT:=
TOTAL_CODE_COUNT - UDK[KEY_CODE].CODE_COUNT;
UDK[KEY_CODE].CODE_COUNT:= I;
TOTAL_CODE_COUNT:= TOTAL_CODE_COUNT + I;
END
ELSE UDK_BUFFER_OVERFLOW:= TRUE;
END
ELSE IGNORE;
END;
(* these conditions cause the rest of the string to be ignored *)
UNTIL (NOT CODE_PAIR_TERMINATED) OR (UDK_BUFFER_OVERFLOW)
OR (UDK_STRING_TERMINATED);
END;
PROCEDURE GET_KEY_CODE;
(*
This routine parses a single key selector code
from the command string.
*)
BEGIN
KEY_CODE:= 0;
REPEAT
GET_NEXT_EVENT (EVENT);
CASE EVENT.EVENT_CODE OF
GRAPHIC_CODE:
BEGIN
IF (EVENT.CODE_VALUE >= 48)
AND (EVENT.CODE_VALUE <= 57) THEN
KEY_CODE:= (KEY_CODE * 10) + (EVENT.CODE_VALUE - 48)
ELSE
BEGIN
CASE EVENT.CODE_VALUE OF
47: KEY_CODE_TERMINATED:= TRUE;
59: DEFINITION_TERMINATED:= TRUE;
OTHERWISE IGNORE;
END;
END;
END;
CONTROL_CODE: (* terminate on String Terminator, 9/12 *)
IF EVENT.CODE_VALUE = 156 THEN UDK_STRING_TERMINATED:= TRUE
ELSE IGNORE; (* ignore other control characters *)
OTHERWISE IGNORE; (* ignore escape and control sequences *)
END;
UNTIL (KEY_CODE_TERMINATED) OR (DEFINITION_TERMINATED)
OR (UDK_STRING_TERMINATED);
END;
PROCEDURE GET_KEY_DEFINITION;
(*
This routine parses a single key definition string from the
command string.
*)
BEGIN
I:= 0;
CODE_PAIR_TERMINATED:= TRUE;
REPEAT
GET_NEXT_EVENT (EVENT);
CASE EVENT.EVENT_CODE OF
GRAPHIC_CODE:
BEGIN
IF EVENT.CODE_VALUE IN HEX_CODE_VALUES THEN
BEGIN
(* convert ascii codes to hex values *)
EVENT.CODE_VALUE:= EVENT.CODE_VALUE - 48;
IF EVENT.CODE_VALUE >= 65 THEN
EVENT.CODE_VALUE:= EVENT.CODE_VALUE - 7;
IF EVENT.CODE_VALUE >= 97 THEN
EVENT.CODE_VALUE:= EVENT.CODE_VALUE - 22;
(* then pack into buffer *)
IF CODE_PAIR_TERMINATED THEN
BEGIN
I:= I+1;
WORK_BUFFER[I]:= 0;
CODE_PAIR_TERMINATED:= FALSE;
END
ELSE CODE_PAIR_TERMINATED:= TRUE;
WORK_BUFFER[I]:=
((WORK_BUFFER[I]) * 16) + EVENT.CODE_VALUE;
END;
IF EVENT.CODE_VALUE = 59 THEN
DEFINITION_TERMINATED:= TRUE;
END;
CONTROL_CODE: (* terminate on String Terminator, 9/12 *)
IF EVENT.CODE_VALUE = 156 THEN UDK_STRING_TERMINATED:= TRUE
ELSE IGNORE; (* ignore other control characters *)
OTHERWISE IGNORE; (* ignore escape and control sequences *)
END;
UNTIL (DEFINITION_TERMINATED) OR (UDK_STRING_TERMINATED);
END;
4 UDK Key Definition Examples
To clear the UDKs send the following sequence:
DCS 0 ; 1 | ST
To lock the UDKs send the following sequence:
DCS 1 ; 0 | ST
The following is a generalized example of the recommended way to load the UDKs:
DCS 0 ; 1 | Ky1 / St1 ; Ky2 / St2 ; ... ; Kyn / Stn ST
5 Change History
5.1 Revision 0.0 To AX10
The spec was entirely rewritten from the original draft. The following sections were added:
Introduction
Functional Description
Report UDK Status (control function)
Extensively modified the UDK load sequence, DECUDK
Pascal coded algorithms
UDK load examples
This page deliberately left blank.