DECUDK—User Defined Keys

DECUDK downloads definitions for user-defined keys.

Format

DCS 9/0 Device Control String Introducer

Ps1 ; Ps2 ; Ps3   Clear, Lock, and Modifier Parameters

| 7/12 Final Character

D . . . D   Key Definition String

ST 9/12 String Terminator

Parameters

Ps1

Ps1	Meaning
0 (default) or none	Clear all keys before loading new values.
1	Load new UDK values; clear old values only when redefined.

When Ps1 is 1, the terminal only clears the keys you are loading. By using a Ps1 value of 1, you can redefine some keys without redefining them all.

Programming Tip
If Ps1 is 1, a key load may fail because no memory space is available. The reason for this is as follows:

With Ps1 set to 1, keys are cleared and loaded sequentially. If the new definition for a key is larger than the old one, then you may exceed the 804 byte limit.

For example, suppose F6 contains 412 bytes, F7 contains 366 bytes, and F8 contains 20 bytes. You try to load F8 with 40 bytes, F6 with one byte, and F7 with one byte, in that order. This works if all keys are cleared first (Ps1 is 0), but not if keys are cleared one at a time (Ps1 is 1). When you try to load F8 with 40 bytes, the load fails because only 26 bytes are free at that time.

804 (maximum) - 412 ( F6 ) - 366 ( F7 ) = 26

Ps2
is the lock parameter. Pl determines whether the key definitions are locked or unlocked after you load them.

Ps2	Action
0 or none	Lock the keys. If you want to load new values into the keys, then you must unlock the keys by using Set-Up.
1	Do not lock the keys against future redefinition.

If Ps2 is 1 and the keys are already locked, then nothing happens.

The terminal uses a special lock to prevent or allow the programming of user-defined keys. You can turn on this lock from Set-Up or from the host (with a DECUDK device control string). The lock affects all programmable keys. When you use the lock, you should follow these guidelines:

• Unlock the keys to define them.

  The keys must be unlocked before you can define them. You can only unlock the keys from set-up. If a key is locked and an application tries to redefine the key with a DECUDK sequence, then the terminal ignores the sequence.

• Lock the keys to prevent redefinition.

  You can lock the keys from Set-Up or from the host by sending a DECUDK sequence. New key definitions are locked by default.

Ps3
is the modifier parameter. Ps3 designates whether the key is shifted or unshifted.

Ps3	Action
0, 2, or none	Defines the shifted function key.
1	Defines the unshifted function key.
3	Defines the alternate unshifted function key.
4	Defines the alternate shifted function key.

|
is the final character. The vertical bar (7/12) identifies this control string as a DECUDK.

D ... D
are the key definition strings such as:

You include these strings between the final character ( | ) and the string terminator (ST). Each string consists of a key selector number (Kyn), a string parameter (Stn), a slash (/) (2/15), and a direction (Dir). A semicolon (;) (3/11) separates different strings.

• Kyn is the key selector number of the key you are defining. Tables 5–11 and 5–12 list the definable keys and their identifying values. Table 5–13 compares the function keys on the VT keyboard to equivalent keys on the PC keyboard.
• Stn is the string parameters, which are the encoded definition of the keys, consisting of hex pairs in the following ranges:

  3/0 through 3/9 (0 through 9)
  4/1 through 4/6 (A through F)
  6/1 through 6/6 (a through f)

  When you combine these hex values, they represent an 8-bit quantity.

  This method lets you use any of the 256 character codes in the key string. You can enter key definition strings in any order.

  Default: Empty. The key is undefined.

• Dir is the user-defined sequence (UDS) direction.

  Dir	Direction	UDS is sent to . . .
  0, none	Normal	Host and/or the terminal, depending on the setting of the COMM mode parameter. The UDS is directed to: The host for full-duplex mode. The screen for half-duplex mode.
  1	Local	Terminal screen only.
  2	Remote	Host only.

  Default: None (Normal)

Table 5–11 VT Keyboards

Kyn	Pm = 1	Pm = none, 0, or 2
	Key	Key
11	F1	Shift/F1
12	F2	Shift/F2
13	F3	Shift/F3
14	F4	Shift/F4
15	F5	Shift/F5
17	F6	Shift/F6
18	F7	Shift/F7
19	F8	Shift/F8
20	F9	Shift/F9
21	F10	Shift/F10
23	F11	Shift/F11
24	F12	Shift/F12
25	F13	Shift/F13
26	F14	Shift/F14
28	F15	Shift/F15
29	F16	Shift/F16
31	F17	Shift/F17
32	F18	Shift/F18
33	F19	Shift/F19
34	F20	Shift/F20
		Note Pm values of 3 and 4 are specific to the PC keyboard. They are ignored when you use a VT keyboard.

Table 5–12 PC Keyboards

Kyn	Pm Value
	1	None, 0 or 2	3	4
11	F1	Shift/F1	Alt/F1	Alt/Shift/F1
12	F2	Shift/F2	Alt/F2	Alt/Shift/F2
13	F3	Shift/F3	Alt/F3	Alt/Shift/F3
14	F4	Shift/F4	Alt/F4	Alt/Shift/F4
15	F5	Shift/F5	Alt/F5	Alt/Shift/F5
17	F6	Shift/F6	Alt/F6	Alt/Shift/F6
18	F7	Shift/F7	Alt/F7	Alt/Shift/F7
19	F8	Shift/F8	Alt/F8	Alt/Shift/F8
20	F9	Shift/F9	Alt/F9	Alt/Shift/F9
21	F10	Shift/F10	Alt/F10	Alt/Shift/F10
23	F11	Shift/F11	Alt/F11	Alt/Shift/F11
24	F12	Shift/F12	Alt/F12	Alt/Shift/F12

Table 5–13 VT and PC Keyboard Function Keys Compared

Kyn	Keyboard
	VT	PC
11	F1	F1
12	F2	F2
13	F3	F3
14	F4	F4
15	F5	F5
17	F6	F6
18	F7	F7
19	F8	F8
20	F9	F9
21	F10	F10
23	F11	F11
24	F12	F12
25	F13	–
26	F14	–
28	F15	–
29	F16	–
31	F17	–
32	F18	–
33	F19	–
34	F20	–

Description

DCS (9/0) indicates the beginning of a device control string. DCS is an 8-bit C1 character. You can use ESC P (1/11 5/0) for a 7-bit environment.

ST is the string terminator. ST (9/12) is a C1 8-bit character. You can use ESC \ (1/11, 5/12) for a 7-bit environment.

General Guidelines When Loading UDKs

• Clear UDK memory space before loading new definitions.

  Use a DECUDK string to clear keys without locking them. Then you can use another DECUDK string to redefine the keys and lock them.

• If you redefine a key, then the old definition is lost. This clears space if the new definition uses less bytes than the old one.

• There is only one way to unlock UDKs.

  To unlock a UDK, use Set-Up.

• When you clear a UDK, the key definition is empty.

• An invalid hex pair in a DECUDK string stops a UDK sequence.

  When a load sequence stops (error or other cause), the terminal saves keys already loaded and sends the rest of DECUDK to the screen.

• You can disable the local function keys by redefining them with DECUDK.
• DECUDK works in all VT modes except VT52 mode.

Examples of DECUDK Device Control Strings

The following sequence clears unshifted UDKs:

DCS 0 ; 1 ; 1 | ST

The following sequence locks unshifted UDKs:

DCS 1 ; 0 ; 1 | ST

Suppose you want to define the unshifted F20 key to be "PRINT", without clearing or locking any other keys. The first part of your sequence would look like this:

DCS 1 ; 1 ; 1 | 3 4 /

34 is the code for the F20 key.

After the slash character (/) (2/15), you include the definition. The rest of the sequence after the slash character would look like this:

5 0 5 2 4 9 4 E 5 4 ST

The hex encoding for "PRINT" is as follows:

50	=	P
52	=	R
49	=	I
4E	=	N
54	=	T

The ST character (9/12) marks the end of the control string:

DCS 1 ; 1 ; 1 | 34 / 50 52 49 4E 54 ST