Video Systems Reference Manual

User Defined Keys Extension

Document Identifier

A-DS-EL00070-011-0 Rev. AX10, 15-May-83

Abstract

This section describes the interface to load and invoke User Definable Keys (UDK), which form an extension to the Level 2 Character Cell Display service class.

Applicability

SARA Formal Cross-Component Standard. Mandatory for Engineers designing hardware for terminal products and Software Engineers designing programs using terminal interfaces. Additional requirements are defined in the section on "Concepts and Conformance Criteria".

Status

FOR REVIEW ONLY

Title
VIDEO SYSTEMS - UDK EXTENSION
Document Identifier
A-DS-EL00070-011-0 Rev. AX10, 15-May-1983
Revision History
Original Draft 25-Dec-1982
Files
User DocumentationEL070S11.mem
Internal DocumentationEL070S11.rno
EL070S11.rnt
EL070S11.rnx
Document Management Group
Terminal Interface Architecture
Responsible Department
Video Architecture Group
Responsible Individual
Peter Sichel
Acceptance

This document has been approved by the Manager of the Video Architecture Group based on a comprehensive review of its individual sections by the members of the SARA component groups working Terminal Interface Architecture issues. The list of individuals on the review and approval list are on file in Standards and Methods Control.

Direct requests for further information to Peter Sichel, PKO3-⁠1/10C, DTN 223-5162, RANI::VIDARCH

Copies of this document can be ordered from:

Standards and Methods Control
APO1/F7, DTN 289-1414, JOKUR::SIMONETTI

Contents

Chapter 11
User Definable Keys Extension

  1. Introduction … 4
  2. Functional Description … 5
    1. Programmable Keys … 5
    2. Default Definitions … 5
    3. Key Definitions … 5
    4. Lock Control … 6
  3. Control Functions … 7
    1. Introducer Sequence Format … 11
    2. Command String Format … 13
      1. Key Selection Codes … 13
      2. String Parameters … 14
    3. Error Conditions … 15
    4. Algorithm … 16
  4. UDK Key Definition Examples … 22
  5. Change History … 23
    1. Revision 0.0 To AX10 … 23

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 ParameterMeaning
20The User Defined Keys are not locked, and all keys may be defined, cleared, or redefined from the host.
21The User Defined Keys are locked, and may not be defined, cleared, or redefined from the host.
23No User Defined Keys are present. The device does not support this extension.

Notes:

  1. 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:

  1. 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.

  2. Host software should not generally leave the user defined keys unlocked. This may cause a breach of security to the terminal user.

  3. The host must keep track of space available for key definitions. No error indication is given if the available buffer space is filled up.

  4. 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.

  1. 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)).

  2. 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 CodeRelated Key
17F6
18F7
19F8
20F9
21F10
23F11
24F12
25F13
26F14
28Help Key
29Do Key
31F17
32F18
33F19
34F20

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:

  1. 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).

  2. 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.

  3. 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:

  1. Introduction

  2. Functional Description

  3. Report UDK Status (control function)

  4. Extensively modified the UDK load sequence, DECUDK

  5. Pascal coded algorithms

  6. UDK load examples