Easytrieve PF Keys

PF Keys in the Interaction Cycle

Recall the terminal cycle: the program sends a screen, the operator works in the fields, then presses an action key to submit. That action key is the trigger that ends the wait and returns control to your AFTER-SCREEN procedure. Enter, Clear, and the PF keys all serve as triggers, but they carry different intent. Enter typically means process my entries. A PF key means perform a named function. Because the key press is what wakes your program, PF keys are inseparable from the AFTER-SCREEN logic that reacts to them.

Defining Keys on the SCREEN

You tell Easytrieve which function keys a screen supports by defining them, commonly with a KEY clause associated with the SCREEN. Each definition ties a physical key to a label and often a displayed description so the operator sees a legend such as F3=Exit F8=Forward at the bottom of the screen. Defining keys does two things: it documents intent for the operator, and it lets the runtime recognize the key rather than ignoring it.

1
2
3
4
5
6
SCREEN NAME CUST-LIST
  KEY F3  NAME 'Exit'     EXIT
  KEY F7  NAME 'Backward'
  KEY F8  NAME 'Forward'
  KEY F1  NAME 'Help'
  * field layout follows

The exact KEY syntax and the options it accepts vary by Easytrieve release. Some releases let you attach an immediate action (such as EXIT) directly to a key; others expect you to handle the key entirely in AFTER-SCREEN. Confirm the precise KEY grammar in your SCREEN statement reference. The concept is constant: declare the keys you support, label them for the operator, and handle the rest in code.

Detecting the Pressed Key

After the operator presses a key and the runtime returns control, you need to know which key it was. Easytrieve exposes the pressed action key through the screen runtime—either as a system field you test or through the KEY definitions you declared. Your AFTER-SCREEN logic reads that indicator and branches. The pattern is a simple decision tree: if exit was pressed leave the activity, if forward was pressed advance the list, otherwise treat it as Enter and process the typed fields.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
AFTER-SCREEN. PROC
   CASE PRESSED-KEY
      WHEN 'F3'
         PERFORM LEAVE-SCREEN
      WHEN 'F7'
         PERFORM PAGE-BACKWARD
      WHEN 'F8'
         PERFORM PAGE-FORWARD
      WHEN 'F1'
         PERFORM SHOW-HELP
      OTHERWISE
         PERFORM PROCESS-ENTER
   END-CASE
END-PROC

Here PRESSED-KEY stands for however your release reports the action key. The name and values are release-specific, so verify them against your documentation; the branching structure is what matters. Always include an OTHERWISE (or equivalent) branch so an unexpected key has defined behavior instead of silently doing nothing.

Standard PF Key Conventions

Operators move between many mainframe applications, so following common conventions reduces training and mistakes. The IBM SAA/CUA guidelines established meanings that most shops still honor. You are free to deviate, but do so deliberately and document it, because an operator who expects PF3 to exit will be surprised if it deletes a record.

Routing Actions Cleanly

Keep AFTER-SCREEN readable by delegating each key to a named procedure rather than inlining large blocks. PERFORM PAGE-FORWARD, PERFORM LEAVE-SCREEN, and PERFORM SHOW-HELP each isolate one function, so the key decision tree stays short and the individual actions are easy to test. This also lets several keys share logic—both Enter and a refresh key might PERFORM the same reload routine. Validate typed input only on the paths that need it: an exit key should leave immediately without complaining about a blank required field, while Enter should validate before proceeding.

Exit paths should not validate

A classic usability bug is forcing validation on every key. If PF3 exits, the operator must be able to leave even with a half-filled screen. Branch on the exit key first and PERFORM the leave routine before any field validation runs, so operators are never trapped by an error message on a screen they are trying to abandon.

Displaying a Key Legend

Operators should not memorize which keys a screen supports. Paint a legend line, usually at the bottom, listing the active keys and their meanings: F3=Exit F7=Bkwd F8=Fwd F1=Help. If your KEY definitions carry a NAME description, some releases can build this legend for you; otherwise populate an output field in BEFORE-SCREEN. Keep the legend accurate—showing F8=Forward on the last page when paging is disabled misleads the operator.

Testing PF Key Handling

1. Press each defined key and confirm it triggers the intended action.
2. Press an undefined key and confirm the OTHERWISE path handles it gracefully.
3. Verify the exit key leaves even when required fields are blank.
4. Check paging keys at the first and last page for correct boundary behavior.
5. Confirm the on-screen key legend matches the keys actually handled.

Common PF Key Mistakes

• Handling a key in code but never defining it, so the runtime ignores the press.
• Validating input before checking for the exit key, trapping the operator.
• Ignoring unexpected keys instead of providing a default branch.
• Breaking conventions (making PF3 do something other than exit) without documentation.
• Showing a key legend that does not match the keys the screen actually supports.
• Assuming a system field name for the pressed key without checking the release reference.

Explain It Like I'm Five

PF keys are like the special buttons on a game controller. The A button jumps, the B button goes back, the start button pauses. When you press a button, the game looks at which one you pressed and does that thing. In our screen, PF3 is the go-back button and PF8 is the next-page button. The game only checks your button after you press it—not while you are just holding the controller. And there is a little label on screen telling you what each button does, so you do not have to remember.

Exercises

1. Define four keys on a SCREEN with NAME descriptions for a list display.
2. Write AFTER-SCREEN CASE logic branching on exit, backward, forward, and Enter.
3. Explain why the exit branch must run before field validation.
4. List the conventional meanings of PF1, PF3, PF7, and PF8.
5. Build a bottom-line key legend and describe when to update it.