SET KEY

#### Search Results

Search

# SET KEY

This document covers the following topics:

- Function

- Syntax Description

- Making Keys Program-Sensitive and Deactivating Keys

- Assigning Commands/Programs

- Assigning Input DATA

- COMMAND OFF/ON

- Assigning HELP

- DYNAMIC Option

- DISABLED Option

- SET KEY Statements on Different Program Levels

- Assigning Names

- Example

## Function

The `SET KEY` statement is used to assign functions to the following types of keys:

- video terminal PA (program attention) keys,

- PF (program function) keys,

- CLEAR key.

When a `SET KEY` statement is executed, Natural receives control of the keys during program execution and uses the values assigned to the keys.

The Natural system variable `*PF-KEY` identifies which key was pressed last.

Note
If a user presses a key to which no function is assigned, either a warning message will be issued prompting the user to press a valid key, or the value `ENTR` will be placed into the Natural system variable `*PF-KEY`; that is, Natural will react as if the ENTER key had been pressed (this depends on the Natural profile parameter `IKEY` as set by the Natural administrator). Processing of PA and PF keys is also affected by the Natural profile parameter `KEY` as set by the Natural administrator.

See also Processing Based on Function Keys (in the Programming Guide).

Application programming interface: `USR4005N`. See SYSEXT - Natural Application Programming Interfaces in the Utilities documentation.

## Syntax Description

Several structures are possible for this statement.

For an explanation of the symbols used in the syntax diagrams, see Syntax Symbols.

Syntax 1 - Affecting All Keys:

`SET KEY` |  | `ALL` `ON` `OFF` |
`COMMAND` |  | `ON` `OFF` |
`NAMED OFF`

Syntax 2 - Affecting Individual Keys:

`SET KEY` |  |  | `PA` n `PF` n `CLR` `DYNAMIC` operand1 |  |  | `=` |  |  |  |  |
`ON` `OFF` `DISABLED`
`COMMAND` |  | `ON` `OFF` |

Syntax 3 - Affecting Individual Keys:

`SET KEY` |  |  | `PA` n `PF` n `CLR` `DYNAMIC` operand1 |  |  |  |  |  | `PGM` `` |  |  |  |  |  |  |  |  |  |  |
`PROGRAM`
`=` | operand2 `HELP` `DATA` operand3 |  | `NAMED` |  | operand4 `OFF` |  |  |
`ENTR` |  | `NAMED` |  | operand4 `OFF` |  |  |  |  |  |  |  |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` | C | S |  |  |  | A | U |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand3` | C | S |  |  |  | A | U |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand4` | C | S |  |  |  | A | U |  |  |  |  |  |  |  |  |  |  |  | yes | no

## Making Keys Program-Sensitive and Deactivating Keys

Making a key program-sensitive means that the key will be available for interrogation by the currently active program. If a key is made program-sensitive, pressing the key has the same effect as pressing ENTER. All data that have been entered on the screen are transferred to the program.

Note
PA keys and the CLEAR key, when made program-sensitive, do not cause any data to be transferred from the screen.

The program-sensitivity remains in effect only for the execution of the current program. See also the section SET KEY Statements on Different Program Levels.

Examples:

`SET KEY ALL` | This statement causes all keys to be made program-sensitive. All function assignments to any keys are overwritten.
`SET KEY PF2` `SET KEY PF2=PGM` | Each of these statements causes PF2 to be made program-sensitive.
`SET KEY OFF` | This statement de-activates all key settings. The Natural system variable `*PF-KEY` contains `ENTR` after `SET KEY OFF` has been executed.
`SET KEY ON` | This statement re-activates the functions assigned to all keys that had an assignment and re-activates the program-sensitivity of keys that were made program-sensitive before they were de-activated.
`SET KEY PF2=OFF` | This statement de-activates PF2. After execution of `SET KEY PF2=OFF`, the Natural system variable `*PF-KEY` contains `ENTR` if it contained `PF2` before.
`SET KEY PF2=ON` | This statement re-activates the function assigned to PF2 before it was de-activated or made program-sensitive. If no function had been assigned to PF2, it will be made program-sensitive again.

### Key Program-Sensitivity and Contents of *PF-KEY

The following example shows the relation between the program-sensitivity of a key and the contents of the system variable `*PF-KEY`.

Assume that PF2 has been made program-sensitive by means of `SET KEY PF2=PGM` and an `INPUT` statement is executed afterwards. The table below shows how user actions and executed Natural statements influence the contents of `*PF-KEY`.

Sequence | Natural Statement Executed / User Action | Contents of *PF-KEY
--- | --- | ---
1 | User presses PF2. | `PF2`
2 | `SET KEY OFF` | `ENTR`
3 | `SET KEY ON` | `PF2`
4 | `SET KEY PF2=OFF` | `ENTR`
5 | `SET KEY PF2=ON` | `PF2`
6 | `SET KEY PF3=OFF` | `PF2`

## Assigning Commands/Programs

You can assign a command or program name to a key, and you can delete such an assignment. When the key is pressed, the current program is terminated and the command/program assigned to the key is invoked via the Natural stack. When assigning a command/program, you can also pass parameters to the command/program (see third example below).

You can also assign a terminal command to a key. When the key is pressed, the terminal command assigned to the key is executed.

When operand2 is specified as a constant, it must be enclosed within apostrophes.

Examples:

`SET KEY PF4='SAVE'` | The command `SAVE` is assigned to PF4.
`SET KEY PF4=#XYX` | The value contained in the variable `#XYZ` is assigned to PF4.
`SET KEY PF6='LIST MAP *'` | The command `LIST`, including the `LIST` parameters `MAP` and `*`, is assigned to PF6.
`SET KEY PF2='%%'` | The terminal command `%%` is assigned to PF2.
`SET KEY PF9=' '` | The command and name previously assigned to PF9 are deleted.

The assignment remains in effect until it is overwritten by another `SET KEY` statement, until the user logs on to another application, or until the end of the Natural session. See also the section SET KEY Statements on Different Program Levels.

Note
Before a program invoked via a key is executed, Natural internally issues a `BACKOUT TRANSACTION` statement.

## Assigning Input DATA

You can assign a data string (`operand3`) to a key. When the key is pressed, the data string is placed into the input field in which the cursor is currently positioned, and the data are transferred to the executing program (as if ENTER had been pressed).

When `operand3` is specified as a constant, it must be enclosed within apostrophes.

Example:

    SET KEY PF12=DATA 'YES'

For the validity of a `DATA` assignment, the same applies as for a command assignment, that is, it remains in effect until it is overwritten by another `SET KEY` statement, until the user logs on to another application, or until the end of the Natural session. See also the section SET KEY Statements on Different Program Levels.

## COMMAND OFF/ON

With `COMMAND OFF`, you can temporarily de-activate any function (command, program, or data) assigned to a key. If the key had been program-sensitive before the function was assigned, `COMMAND OFF` will make it program-sensitive again.

With a subsequent `COMMAND ON`, you can re-activate the assigned function again.

Examples:

`SET KEY PF4=COMMAND OFF` | The function that has been assigned to PF4 is temporarily de-activated; if PF4 had been program-sensitive before the function was assigned, it is now made program-sensitive again.
`SET KEY PF4=COMMAND ON` | The function assigned to PF4 is re-activated again.
`SET KEY COMMAND OFF` | All functions assigned to all keys are temporarily de-activated; those keys which had been program-sensitive before functions were assigned to them, are now made program-sensitive again.
`SET KEY COMMAND ON` | All functions assigned to all keys are re-activated again.

With `SET KEY PFnn=''` you can delete the function assigned to a key and at the same time deactivate the program sensitivity of the key.

## Assigning HELP

You can assign `HELP` to a key. When the key is pressed, the helproutine assigned to the field in which the cursor is currently positioned will be invoked.

The effect is the same as when entering the help character in the field to invoke help. (The help character - default is a question mark (?) - is determined by the Natural profile parameter `HI` as set by the Natural administrator.)

Example:

    SET KEY PF1=HELP

For the validity of a `HELP` assignment, the same applies as for program-sensitivity, that is, it remains in effect only for the execution of the current program. See also the section SET KEY Statements on Different Program Levels.

## DYNAMIC Option

Instead of specifying a specific key with the `SET KEY` statement, you can use the `DYNAMIC` option with a variable (`operand1` ), and assign a value (`PFn`, `PAn`, `CLR`) to this variable in the program. This allows you to specify a function and make it dependent on the program logic which key this function is assigned to.

Note
`SET KEY` cannot be used if `operand1` is a dynamic variable.

Example:

    ...
    IF ...
       MOVE 'PF4' TO #KEY
    ELSE
       MOVE 'PF7' TO #KEY
    END-IF
    ...
    SET KEY DYNAMIC #KEY = 'SAVE'
    ...

## DISABLED Option

Graphical user interface (GUI) elements, such as push buttons, menus, and bitmaps, are implemented as PF keys. With the `DISABLED` option, you can disable the use the of a GUI element assigned to a PF key. Push buttons and menu items will then be displayed grey.

To cancel the effect of `SET KEY PFnn=DISABLED`, you use `SET KEY PFnn=ON`.

Example:

`SET KEY PF10=DISABLED` | Disables the use of the GUI element assigned to PF10.

The `DISABLED` option can only be used within a processing rule.

## SET KEY Statements on Different Program Levels

When an application contains `SET KEY` statements at different levels, the following applies:

- When keys are made program-sensitive, the program-sensitivity also applies to all lower level (called) programs, unless these programs contain further `SET KEY` statements. When control is returned to a higher level program, the `SET KEY` assignments made at the higher level come into effect again.

- For keys which are defined as `HELP` keys, the same applies as for keys which are program-sensitive.

- When a function (program, command, terminal command, or data string) is assigned to a key, this assignment is valid at all higher and lower levels - regardless of the level at what the assignment is made - until another function is assigned to the key or it is made program-sensitive, or until the user logs on to another application or the Natural session is terminated.

### Example of SET KEY Statements on Different Program Levels

## Assigning Names

With the `NAMED` clause, you can assign a name (`operand4` ) to a key. The name will then be displayed in the PF-key lines on the screen; this allows the users to identify the functions assigned to the keys:

                      ?   Help
                    .   Exit
                   ---- ----------------------------------------------------
           Code ..: ?   Library ..: *_______
                        Object ...: *_______________________________________
                        DBID .....: 0__    FILENR ...: 0__

       Command ===>
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help        Exit  Last        Flip                                Canc

The display of the PF-key lines is activated with the session parameter `KD` (see the Parameter Reference). You can control the way in which the PF-key lines are displayed by using the terminal command `%Y` (see the Terminal Commands documentation).

The maximum length of a name to be assigned to a key is 10 characters. In normal tabular PF-key line format (`%YN`), only the first 5 characters are displayed.

When `operand4` is specified as a constant, it must be enclosed within apostrophes (see examples below).

You cannot assign a name to a key without assigning a function to it or making it program-sensitive. To the ENTER key, however, you can only assign a name, but no function.

With `NAMED OFF`, you delete the name assigned to a program-sensitive key.

Examples:

`SET KEY ENTR NAMED 'EXEC'` | The name `EXEC` is assigned to the ENTER key.
`SET KEY PF3 NAMED 'EXIT'` | PF3 is made program-sensitive, and the name `EXIT` is assigned to PF3.
`SET KEY PF3 NAMED OFF` | PF3 is made program-sensitive, and the name that has been assigned to PF3 is deleted.
`SET KEY NAMED OFF` | All names that have been assigned to any program-sensitive keys are deleted.
`SET KEY PF4='AP1' NAMED 'APPL1'` | The program `AP1` and the name `APPL1` are assigned to PF4.

When you use normal tabular PF-key line format (`%YN`), the following applies:

- If you omit the `NAMED` clause when assigning a command/program to a key, the command/program name will be displayed in the PF-key line; if the command/program name is longer than 5 characters, `CMND` will be displayed.

- If you omit the `NAMED` clause when assigning input data to a key, `DATA` will be displayed in the PF-key line.

- If you assign (with the NAMED clause) a name in Unicode format to a PF-key, the name might not be correctly positioned under the respective headers. This problem, however, may occur only when you are using the Natural Web I/O Interface and only for "wide" characters. In this case, the sequential PF-key line format (`%YS` or `%YP`) is recommended.

When you use sequential PF-key line format (`%YS` or `%YP`), only those keys to which names have been assigned will be displayed in the PF-key line; that is, if you omit the `NAMED` clause when assigning a command/program/data to a key, the key will not be displayed in the PF-key line.

See also Processing Based on Function Key Names in the Programming Guide.

## Example

    ** Example 'SKYEX1': SET KEY
    ************************************************************************
    DEFINE DATA LOCAL
    1 #PF4 (A56)
    END-DEFINE
    *
    MOVE 'LIST VIEW' TO #PF4
    *
    SET KEY PF1 PF2
    SET KEY PF3 = 'MENU'
            PF4 = #PF4
            PF5 = 'LIST VIEW EMPLOYEES' NAMED 'Empl'
    *
    FORMAT KD=ON
    INPUT ////
          10X 'The following function keys are assigned:' //
          10X 'PF1: Function for PF1      ' /
          10X 'PF2: Function for PF2      ' /
          10X 'PF3: Return to MENU program' /
          10X 'PF4: LIST VIEW             ' /
          10X 'PF5: LIST VIEW EMPLOYEES   ' ///
    *
    IF *PF-KEY = 'PF1'
      WRITE 'Function for PF1 executed.'
    END-IF
    IF *PF-KEY = 'PF2'
      WRITE 'Function for PF2 executed.'
    END-IF
    *
    END

#### Output of Program SKYEX1:

    The following function keys are assigned:

    PF1: Function for PF1
    PF2: Function for PF2
    PF3: Return to MENU program
    PF4: LIST VIEW
    PF5: LIST VIEW EMPLOYEES

### On this page

- Function
- Syntax Description
- Making Keys Program-Sensitive and Deactivating Keys
- Assigning Commands/Programs
- Assigning Input DATA
- COMMAND OFF/ON
- Assigning HELP
- DYNAMIC Option
- DISABLED Option
- SET KEY Statements on Different Program Levels
- Assigning Names
- Example