SAS Companion for the OpenVMS Operating Environment

Customizing Key Definitions

You can define most of the keys on your keyboard. However, a few keys have dedicated functions that are associated with them. For example, the mouse buttons are dedicated to the cursor and cut-and-paste operations and are not available for user customization. For more information, see Default Keyboard Actions.

You can customize your key definitions by using one of the following methods:

Through the KEYS window. To open the KEYS window, do one of the following:
- Issue the KEYS command.
- From the Tools menu, select Options, and then select Keys.
If you change any key definitions through the KEYS window for the SAS windowing environment windows, the definitions are stored in the catalog SASUSER.PROFILE in the entry DMKEYS.KEYS. Key definitions for other SAS windows are stored in catalog entries named BUILD.KEYS, FSEDIT.KEYS, and so on.
For more information about the KEYS command and the KEYS window, refer to the SAS online Help.
With the KEYDEF command. The KEYDEF command allows you to redefine individual function keys:
```
keydef keyname <command | ~text-string>
```
For example, if you specify keydef F8 dlgpref, then the F8 key will issue the DLGPREF command that opens the Preferences dialog box.
For more information about the KEYDEF command, refer to the SAS online Help.
By defining the SAS.keyboardTranslations and SAS.keysWindowLabels resources in your resources file as described in Defining Key Translations.

Defining Key Translations

To customize a key for the X Window System, you define a key sequence and specify an action to be executed when that key sequence is typed on the keyboard. This is known as binding keys to actions; together they are referred to as a translation.

The SAS.keyboardTranslations resource specifies the set of key bindings that the SAS System uses in all SAS windows. The default value for the SAS.keyboardTranslations resource is determined at run time based on the vendor identification string reported by the X server that you are using as the display. These default settings are listed in the SAS$ROOT:[TOOLS] directory. To modify the default bindings supplied by the SAS System, you must modify the SAS.keyboardTranslations resource.

Note: The X Toolkit Intrinsics translations specified in this resource apply to both the user area and the command line of all SAS windows that are affected by this resource. This resource does not affect windows that are controlled by Motif interface resources, such as the Command window, the Open or Import dialog boxes, and some other menu dialog boxes. [cautionend]

To create a key definition, follow these steps:

Determine the keysyms for the keys that you want to define. Keysyms are the symbols recognized by the X Window System for each key on a keyboard. For more information, see Determining Keysyms.
Modify/add the keyboardTranslations resource in your resource file to include the definitions of the keys that you want to define. Use a keyboard action routine to define which action you want the key to perform. The definition in the right column in the KEYS window will no longer control the function of any keys that are defined with a keyboard action routine other than sas-function-key().
Modify/add the SAS.keysWindowLabels resource in your resource file. The SAS.keysWindowLabels resource specifies the set of valid labels that will appear in the KEYS window. Modify this resource only if you want to add new labels or modify existing labels in the left column in the KEYS window.
The SAS.keysWindowLabels resource defines only the mnemonics used in the KEYS window. For a specific key to perform an action, you must specify a SAS.keyboardTranslations definition for the key. For more information, see Modifying the SAS.keyboardTranslations Resource.
Start a SAS session and open the KEYS window.
In the right-hand column in the KEYS window, type a command name or other description of each key that you have defined.

Determining Keysyms

You can use the xev utility to determine the keysyms associated with the keys on your keyboard. Refer to your X Window documentation for more information about the xev utility.

The xev utility prints a message for each X event that occurs. The KeyPress event specifies the keysym for each key that is pressed.

Use the following steps to determine keysyms:

Start the xev utility on the X server for which you want to define keys. The xev client displays a small Event Tester window that lists the X events that occur. (The xev client generates a large amount of output, so you may want to save the output to a file for later review. You can issue the script command to save the output to a file.)
Give keyboard focus to the Event Tester window by clicking the mouse pointer on the window, if necessary.
Press the key that you want to define, and watch for the KeyPress event to be listed. The listing has a number of items that are separated by commas. One of the fields in the KeyPress event lists the keysym name that is associated with the key that was pressed.
For example, when the 0 key on the keyboard is pressed, it could generate output similar to the following:
```
KeyPress event, serial 14, synthetic NO,
  window 0x4400001,root 0x23, subw 0x4400002,
  time 507920400, (54,37),root:(67,66),
  state 0x0, keycode 30 (keysym 0xffb0, KP_0),
  same_screen YES,
  XLookupString gives 1 characters: "0"
```
In this example the keysym name is KP_0.

Modifying the SAS.keyboardTranslations Resource

The SAS.keyboardTranslations resource specifies the default set of key bindings for the SAS System to use in all SAS windows. User-specified translations for this resource may use the #augment or #override modifiers to define a previously undefined key or to override the default translation string with user preferences. This resource does not affect windows that are controlled by Motif resources, such as the Command window, the Open dialog box, and some other menu dialog boxes.

Note: Most SAS documentation uses angle brackets (<>) to indicate optional syntax. However, in this topic optional syntax is shown with square brackets ([ ]). The angle brackets that are shown are part of the syntax and should be entered exactly as shown. [cautionend]

Use the following syntax for the SAS.keyboardTranslations resource:

SAS.keyboardTranslations: #override \

[modifier] <Key>keysym : action-routine \n\

[modifier] <Key>keysym : action-routine
where

#override: indicates that this definition should override any existing bindings for the specific keys that you define without affecting any other keys. If you omit the #override directive, the new bindings replace all of the default bindings, and none of the other keys on the keyboard will be available to the SAS interface to Motif. For information on the #augment and #replace, see refer to the documentation for the X Window System.
modifier: can be Alt, Ctrl, Meta, Shift, Lock, Mod1, Mod2, Mod3, Mod4, Mod5, None, or a blank space. The list of valid modifiers varies depending on your keyboard.
<Key>: is required. It signals the beginning of the keysym.
keysym: is the key symbol recognized by X for the key that you are defining. For more information, see Determining Keysyms.
action-routine: is what you want the key to do. You can specify any action routine described in SAS Keyboard Action Names. Some action routines require parameters.
\n: allows the X translation manager to determine where one translation sequence ends and the next one begins. Do not enter \n after the end of the last translation.
\: prevents the new-line character at the end of the line from being interpreted as part of the definition. This is a stylistic convention that allows each translation to be listed on a separate line. Do not enter a backslash after the end of the last translation.

Note: The SAS System does not prevent you from specifying invalid keys in the SAS.keyboardTranslationsresource. In some case, invalid keys will produce warnings in the terminal window. [cautionend]

The following example overrides the default settings, binds the key sequence CTRL-K to the KEYS command, and binds CTRL-D to delete the character under the cursor:

SAS.keyboardTranslations: #override
    Ctrl<Key>k: sas-do-command(keys)\n
    Ctrl<Key>d: sas-delete-char()

Modifying the SAS.keysWindowLabels Resource

The SAS.keysWindowLabels resource specifies the set of valid labels that will appear in the KEYS window. This resource defines KEYS window internal and external mnemonics only. It is still necessary to have SAS.keyboardTranslations definitions for the specific X Windows keysym and modifier combinations that are bound to the sas-function-key() action, using the InternalKeyName as the sas-function-key() action routine parameter.

Note: Most SAS documentation uses angle brackets (<>) to indicate optional syntax. However, in this topic optional syntax is shown with square brackets ([ ]). [cautionend]

Use the following syntax for the SAS.keysWindowLabels resource:

SAS.keyWindowLabels: \

KeyWindowLabel [(InternalKeyName)] \n\

KeyWindowLabel [(InternalKeyName)]
where

KeyWindowLabel: is the label that you want to appear in the KEYS window. This label must be one to eight characters long.
InternalKeyName: is the character string that is passed to the sas-function-key() action routine in the corresponding keyboardTranslations key binding. InternalKeyName is used by the SAS System to correlate KEYS window entries to key definitions in the KEYS modules loaded from SAS catalogs or defined in the KEYS window. This name must be one to eight characters long. If the InternalKeyName is not specified, then SAS uses the KeyWindowLabel as the InternalKeyName.
\n: allows the X translation manager to determine where one translation sequence ends and the next one begins. Do not enter \n after the end of the last translation.
\: prevents the new-line character at the end of the line from being interpreted as part of the definition. This is a stylistic convention that allows each translation to be listed on a separate line. Do not enter a backslash (\) after the end of the last translation.

SAS Keyboard Action Names

The SAS System declares a set of keyboard actions during X initialization. You can think of these keyboard actions as dimple functions. When the actions are executed, they act on the window that currently has keyboard input focus.

Keyboard action names represent X Toolkit action routines that are registered by the SAS interface to Motif for use with X Toolkit keyboard-event translations. A set of default keyboard actions is supplied as part of the interface. You can override and augment these actions by supplying a suitably formatted X Toolkit translation string in the SAS.keyboardTranslations resource (see the description of the SAS.keyboardTranslations resource in Modifying the SAS.keyboardTranslations Resource).

The following list of keyboard actions represents action routines registered by the Motif interface for use with X Toolkit keyboard event translations:

sas-cursor-down()

moves the cursor down one line in a SAS window. The cursor does not wrap when it reaches the bottom of the SAS window interior.

sas-cursor-left()

moves the cursor left one character in a SAS window. The cursor does not wrap when it reaches the left side of the SAS window interior.

sas-cursor-right()

moves the cursor right one character in a SAS window. The cursor does not wrap when it reaches the right side of the SAS window interior.

sas-cursor-up()

moves the cursor up one line in a SAS window. The cursor does not wrap when it reaches the top of the SAS window interior.

sas-delete()

deletes all text in the current field.

sas-delete-begin()

deletes all text from the current cursor position to the beginning of the current text field.

sas-delete-char()

deletes the character under the text cursor and leaves the cursor in place.

sas-delete-end()

deletes text from the current cursor position to the end of the current text field.

sas-delete-prev-char()

deletes the character to the left of the text cursor and moves the cursor back one space.

sas-delete-prev-word()

deletes text from the current cursor position to the start of the previous word. If the cursor is in the interior of a word when the action is invoked, the text from the cursor position to the beginning of the word is deleted.

sas-delete-word()

deletes text from the current cursor position to the end of the current or next word.

sas-do-command()

accepts one or more text-string parameters that are interpreted as SAS commands to be executed when the action is invoked. The action can be invoked with multiple parameters, separated by commas. The parameters are concatenated, with semicolon delimiters that are supplied by the sas-do-command() action. The assembled SAS command string is then submitted for execution. For example, the following translation can be used to define a global HOME, SUBMIT key sequence for all SAS windowing environment windows:

SAS.keyboardTranslations: <Key>KP_F3: 
_sas-do-command(HOME,SUBMIT)

sas-function-key("InternalKeyName")

invokes the SAS commands associated with the function key identified by the InternalKeyName label. InternalKeyName is the character string (one to eight characters long) that is passed to the SAS.keysWindowLabel resource. You must enclose InternalKeyName in double quotation marks. For a description of internal key names, see Defining Key Translations. For a list of function-key parameters that SAS recognizes, refer to the sample SAS$XDEFAULTS.DAT file.

For example, the following keyboard translation designates the physical key KP_1 as a function key and associates the "Keypd 1" parameter with KP_1. The SAS System recognizes the "Keypd 1" parameter as being associated with the command LEFT (that is, scroll left) by default. Thus, it assigns the LEFT command to KP_1.

SAS.keyboardTranslations: ~Ctrl<Key>KP_1: 
_sas-function-key("Keypd 1")

If you specify a function-key parameter that SAS does not recognize, the function-key command is initially left unspecified.

sas-home-cursor()

is the equivalent of the HOME command. This action is provided for convenience so that the HOME action can be defined globally.

sas-insert-char(["InsertionString"])

inserts or overwrites the character typed into the input field under the text cursor. Insert or overstrike behavior is determined by the sas-toggle-insert()action, which has a mode that is reflected by the text cursor style displayed: the block cursor indicates overstrike mode, and the underline cursor indicates insert mode. Normally, sas-insert-char translates the XKeyEvent into the appropriate character and inserts it at the SAS text cursor location. If you specify the parameter, the text string represented by this parameter is inserted at the SAS text cursor location. Any spaces in the string are interpreted by the X Toolkit as a parameter delimiter unless you enclose the string in double quotation marks. For information about embedding quotation marks in the string parameter, refer to your X Window System documentation. To include an escaped quotation mark, use the following syntax:

Shift<Key>KP_1:\
   sas-insert-char("One\\"1\\" ")

This produces the text string One"1"at the SAS text cursor location.

Note: Most SAS documentation uses angle brackets (< >) to indicate optional syntax. However, in this topic optional syntax is shown with square brackets ([ ]). The angle brackets that are shown are part of the syntax and should be entered exactly as shown. [cautionend]

sas-kp-application()

sets the workstation's numeric keypad to allow function key translations to be reinstated. This toggle only works for those keypad keys that are bound to sas-function-key()actions. Keypad bindings to other actions are not affected by this translation.

sas-kp-numeric()

sets the workstation's keypad to generate numeric characters instead of its previous function key assignment. Note that this toggle only works for keypad keys that are bound to sas-function-key()actions. Keypad bindings to other actions are not affected by this translation.

sas-move-begin()

moves the cursor to the beginning of the current text field.

sas-move-end()

moves the cursor to the end of the current text field.

sas-new-line()

generates an end-of-line event when invoked. This is a context-sensitive action. If you are typing in the SAS command line, the text that you enter is submitted for execution. If you invoke the sas-new-line action in the SAS application client-area, then the action depends on the attributes of the text area that is under the cursor. In simplest terms, this action is the general line terminator for an input field.

sas-next-field()

advances the cursor to the next field in the SAS window client-area.

sas-next-word()

moves the cursor forward to the beginning of the next word in the current text field. Wrapping is supported; that is, if the sas-next-word() action does not find the beginning of a word in the current text field, it advances to the next SAS application field. However, if you are typing in the SAS command-line area of the window, the cursor will not wrap into the SAS window client-area.

sas-page-down()

scrolls the current window contents forward by one page.

sas-page-end()

moves the text cursor to the end of the current page.

sas-page-top()

moves the text cursor to the top of the current page.

sas-page-up()

scrolls the current window contents backward by one page.

sas-prev-field()

returns the cursor to the previous field in the SAS window client-area.

sas-prev-word()

moves the cursor backward to the start of the next word in the current text field. Wrapping is supported; that is, if the sas-prev-word() action does not find the beginning of a word in the current text field, then it returns to the end of the previous SAS application field. However, if you are typing in the SAS command-line area of the window, the cursor does not wrap into the SAS window client-area.

sas-to-bottom()

moves the text cursor to the absolute bottom of the window's text range.

sas-to-top()

moves the text cursor to the absolute top of the window's text range.

sas-toggle-insert()

toggles the line-editing behavior of the associated window between insert and overstrike modes. This action applies only to the SAS command line and to the SAS window client-area. The current mode is indicated by the style of the cursor:

block cursor: indicates overstrike mode.
underline cursor: indicates insert mode.

sas-xattr-key(<KeyType>[,<KeyParam>])

defines the extended attributes that are associated with extended-attribute keys. This action accepts two text-string parameters.

Note: Most SAS documentation uses angle brackets (< >) to indicate optional syntax. However, in this topic optional syntax is shown with square brackets ([ ]). The angle brackets that are shown are part of the syntax and should be entered exactly as shown. [cautionend]

The <KeyType> parameter must be one of the following:

XAATTR

sets a display attribute. If XAATTR is specified, then the second parameter must be one of the following:

HIGHLIGHT

turns on bold.

UNDERLINE

turns on underlining.

REVERSE

turns on reverse video.

BLINK

turns on blinking.

Note: The BLINK attribute is not supported in the Motif interface. However, if you specify the BLINK attribute, it will be displayed when the catalog is ported to other operating environments. [cautionend]

XACLEAR

clears all attributes. If XACLEAR is specified, then you must specify NULL as the second parameter.

XACOLOR

sets a color attribute. If XACOLOR is specified, then the second parameter must be one of the following:

BLACK: sets the text color to black.
BLUE: sets the text color to blue.
BROWN: sets the text color to brown.
CYAN: sets the text color to cyan.
GRAY: sets the text color to gray.
GREEN: sets the text color to green.
MAGENTA: sets the text color to magenta.
ORANGE: sets the text color to orange.
PINK: sets the text color to pink.
RED: sets the text color to red.
WHITE: sets the text color to white.
YELLOW: sets the text color to yellow.

For example, the following resource definition defines the CTRL-B key sequence to set the extended attribute for the color BLACK:

sas.keyboardTranslations:#override \ 
    Ctrl<Key>b:sas-xattr-key(XACOLOR,BLACK)

Default Keyboard Actions

Some keyboard-action routines are assigned to certain keys by default. Default Key Actions shows the default keyboard actions, which are defined by the SAS.keyboardTranslations resource. For more information about this resource, see Defining Key Translations.

Note: Most SAS documentation uses angle brackets (< >) to indicate optional syntax. However, in this topic the angle brackets that are shown are part of the syntax and should be entered exactly as shown. [cautionend]

Default Key Actions
Key Name Keyboard Action Routine

<Key>Home sas-home-cursor()

<Key>osfUp sas-cursor-up()

<Key>osfDown sas-cursor-down()

<Key>osfRight sas-cursor-right()

<Key>osfLeft sas-cursor-left()

<Key>Return sas-new-line()

Shift<Key>Tab sas-prev-field()

<Key>Tab sas-next-field()

<Key>osfBackSpace sas-delete-prev-char()

<Key>osfDelete sas-delete-prev-char()

<Key> sas-insert-char()

Shift<Key> sas-insert-char()

***Default Key Actions***
Key Name	Keyboard Action Routine
<Key>Home	`sas-home-cursor()`
<Key>osfUp	`sas-cursor-up()`
<Key>osfDown	`sas-cursor-down()`
<Key>osfRight	`sas-cursor-right()`
<Key>osfLeft	`sas-cursor-left()`
<Key>Return	`sas-new-line()`
Shift<Key>Tab	`sas-prev-field()`
<Key>Tab	`sas-next-field()`
<Key>osfBackSpace	`sas-delete-prev-char()`
<Key>osfDelete	`sas-delete-prev-char()`
<Key>	`sas-insert-char()`
Shift<Key>	`sas-insert-char()`

Extended-Attribute Key Resources

The SAS interface to Motif supports the use of attributes such as bold, reverse video, and underline. You can use the SAS.keyboardTranslations resource to control this feature.

Functions Provided through the SAS System Extended-Attribute Keys summarizes the functions that are provided through the SAS System extended-attribute keys.

Functions Provided through the SAS System Extended-Attribute Keys
Keyboard Chord Character Attribute Selected

Mod1<Key>b Blue

Mod1<Key>r Red

Mod1<Key>p Pink

Mod1<Key>g Green

Mod1<Key>c Cyan

Mod1 <Key>y Yellow

Mod1<Key>w White

Mod1<Key>m Magenta

Mod1<Key>o Orange

Mod1<Key>k Black

Mod1<Key>n Brown

Mod1<Key>a Gray

Mod1<Key>0 Clear extended attributes

Mod1<Key>1 Set highlight (bolding) attribute

Mod1<Key>2 Set underline attribute

Mod1<Key>3 Set reverse-video attribute

***Functions Provided through the SAS System Extended-Attribute Keys***
Keyboard Chord	Character Attribute Selected
Mod1<Key>b	Blue
Mod1<Key>r	Red
Mod1<Key>p	Pink
Mod1<Key>g	Green
Mod1<Key>c	Cyan
Mod1 <Key>y	Yellow
Mod1<Key>w	White
Mod1<Key>m	Magenta
Mod1<Key>o	Orange
Mod1<Key>k	Black
Mod1<Key>n	Brown
Mod1<Key>a	Gray
Mod1<Key>0	Clear extended attributes
Mod1<Key>1	Set highlight (bolding) attribute
Mod1<Key>2	Set underline attribute
Mod1<Key>3	Set reverse-video attribute

Chapter Contents
Previous
Next
Top of Page