For years, OS/400 programmers have used function keys to control interactive applications. All function keys are either Command Function (CF) keys or Command Attention (CA) keys. These two types of keys are effectively the same in their functionality except that CF keys return data from the screen to the application, whereas CA keys do not.

There are 24 standard function keys as well as a variety of other special-purpose keys, such as Help, Home, Rollup (page down), Rolldown (page up), Print, FieldExit, and so forth. The standard function keys can act as either CA or CF keys, but the special-purpose keys can be used only as CA keys.

Declaring a function key in your display file is relatively simple. Indicators are used to pass the function key requests to the RPG program. Traditionally, an indicator is assigned to the key when it is declared in the display file. An indicator is assigned by specifying the indicator within parentheses adjacent to the keyword. Specify a CFxx keyword when CF capability is needed or a CAxx keyword when CA capability is required.

In Figure 1, CA keys 3 and 5 are declared along with Rollup and Rolldown. In addition, CF key 4 is declared. When these keys are used to return control to the program, the corresponding indicator is set on in the RPG program.

By the way, these indicators are referred to as "command key response indicators," although lately the term "command key" has been replaced by the term "function key."

Figure 1: This is an example of traditional function key declarations in DDS.

Eliminating Response Indicators

My goal this week is to get you to consider abandoning these response indicators and use an alternative technique, one that avoids the use of indicators all together. One technique for doing this has been around seemingly forever and yet seems to have become a lost technology. It's my goal to resurrect this technique to help eliminate the use of indicators in RPG programs. After all, eliminating the using of indicators has been a long-standing goal of most RPG programmers; this technique simply helps us achieve that end.

To accomplishing this transition, relatively few changes need to be made to the way function keys are declared and processed. The first change is in the way function keys are declared in the DDS itself. The CAxx or CFxx keywords may be specified without a response indicator, as illustrated in Figure 2.

Figure 2: Here's an example of function key declaration without response indicators.

By avoiding the response indicator, the function key is simply specified by itself. Removing the response indicators is not strictly required for this technique. They may be specified if necessary for backward compatibility and then simply ignored in the RPG program.

Which Function Key Is Pressed?

So how does your RPG program know which function key was pressed when response indicators are not used? Answer: the INFDS.

Since the implementation of RPG II on the System/34 (and probably back as far as the System/3), the INFDS for display files, commonly referred to as the "workstation data structure" or simply "WSDS," has included a subfield containing the so-called Attention Identification Byte. Perhaps this subfield's name is ambiguous and is therefore ignored by most developers. But the Attention Identification Byte (sometimes called the "AID Byte") is nothing more than the scan code of the function key used to return control to the RPG program.

To declare the WSDS in RPG, the INFDS keyword is used on the File Continuation specification (in RPG III) and the File keyword area (in RPG IV).

In RPG IV, the WSDS is declared as follows:

In RPG III, the WSDS is declared as follows:

Once a workstation data structure is identified on the File specification, an actual data structure must be declared to receive the so-called I/O feedback information from the display file. This data structure will have several values stored in it; however, a little research (look on page 18 and 19 of The Modern RPG IV Language) reveals that the Attention Identification Byte or "scan code" is returned in position 369 of the WSDS.

Therefore, in RPG IV, we would code the following:

Whereas in RPG III, we would code this:

Let me put these pieces together. The RPG IV and RPG III code is similar, so, depending on which language you use, Figure 3a or Figure 3b contains the necessary code that provides access to the Function key scan codes.

Figure 3a: This is the RPG IV Workstation Data Structure (WSDS) with FKey subfield.

Figure 3b: This is the RPG III Workstation Data Structure (WSDS) with FKEY subfield.

The data structure subfield named FKEY is declared and can be used throughout the program. It can be used to determine which function key (if any) was used to return control to the program from an EXFMT or WRITE/READ combination.

There is no rocket science involved in this technique, and you have probably written code very similar to the WSDS examples from Figures 3a and 3b.

Testing for a Function Key

There are two more pieces to this technique, however, and both are very easy to implement. The first requires you to research which scan codes are returned for each function key. Normally, this could take some time, but rather than make you do it, I've created the following table with the scan codes (taken from chapter 1 of The Modern RPG IV Language) and listed them in Figure 4.

Figure 4: This table lists the Attention Identification Byte/function key scan codes.

Comparing the FKEY subfield in the WSDS from Figures 3a and 3b to a hexadecimal value isn't difficult, but how much more intuitive is

than

Not very intuitive.

To avoid hard-coding hexadecimal constants throughout the source code and to eliminate ambiguity, you will need to declare a set of named constants that identify each of the hexadecimal values from Figure 4. Of course, it would be easier if you, for example, named the constants for the function key scan codes the same as the function key names--that is, the named constant for the F3 key would be named F3 and represent a value of X'33'.

In RPG IV, named constants are declared on the Definition specification; in RPG III, they are declared using Input specifications.

A source member that may be used as a /COPY is listed in Figure 5. It includes a complete set of function keys and their hexadecimal scan codes for RPG IV.

Figure 5: FKey Named Constants--Use this source member as a /COPY.

To use this member, create a source member named something like FKEYS and store the code from Figure 5 in it. Then, use the /COPY or /INCLUDE directive to import the named constants into each interactive program that needs it.

It Just Keeps Getting Easier

And now the easiest part: To take advantage of this capability, all you have to do is insert a check of the FKEY subfield for the valid function key scan code (from Figure 5). Insert this check following an EXFMT or a WRITE opcode to a display file.

I like to use a SELECT/WHEN inline case group to detect which key was pressed, but you can use an IF/ELSEIF condition if you're on V5R1 or later. Figure 6 includes a simple example of the SELECT/WHEN test.

Figure 6: Use this example for RPG IV processing with the Attention Identification Byte.

A Do loop is used to keep the processes running until the user presses function key 3. Then, an EXFMT is issued to write the display file format and wait for the user to press Enter or some function key. When the user does this, a SELECT/WHEN inline case group checks to see which key is used to return control to the program.

You simply compare the value of the FKEY subfield of the WSDS data structure to the corresponding named constant. Even the ENTER key can be tested, as illustrated on line 4 of Figure 6.

I've brought everything together in one place in Figure 7. It contains the display file declaration and the INFDS keyword, the /COPY of the named constants, and the WSDS declaration including the FKEY subfield. Of course, it also illustrates the use of the subfield and the named constants in the Calculation specifications.

Figure 7: This sample code shows the completed Attention Identification Byte/scan code processing.

The combination of scan codes and named constants brings a level of clarity to RPG IV not previously available. It allows you to easily add new routines based on function keys without concern for indicators (no more worrying if indicator XX is being used someplace else in the program).

One of the objectives of RPG IV is to eliminate indicator usage entirely. While there is nothing you can do about a display file's requirement to use indicators, you can reduce your dependency on indicators in the RPG program through the use of the function key scan code and the FKEY subfield.

Bob Cozzi has been programming in RPG since 1978. Since then, he has written many articles and several books, including The Modern RPG IV Language --the most widely used RPG reference manual in the world. Bob is also a very popular speaker at industry events such as COMMON and RPG World and is the author of his own Web site, www.rpgiv.com, and of the RPG ToolKit, an add-on library for RPG IV programmers.