I don't know how many times I've needed to end a CL program because a user, who just called the CL program to run a Query/400 routine, pressed the F3 or F12 key to exit without running the query. My CL had no way of knowing if the user pressed F3 to exit the Query prompt.

Likewise, I have a utility that allows users to run the WRKSPLF CL command after entering some criteria. If the user presses Enter or F12 to return, I want the system to perform one task; if the user presses F3, I want the system to do something else. But how?

You might think it would be impractical do something like this or require access to some mystical DSM API set. As it turns out, the solution was there all along; the Retrieve Job Information API (QUSRJOBI) actually returns two on/off-style flags that indicate whether F3 or F12 was pressed on an IBM-supplied screen.

Using this API to check for F3 or F12 isn't difficult, but it is somewhat stealthy. The location of the information is buried in the middle of some API data structure that contains other information that you just don't need when testing for F3 or F12.

You can either call the API directly or use the handy wrapper command that I've provided here. The wrapper allows you to use the RTVEXITKEY command to check for F3 or F12 by retrieving the values into CL variables. The command definition source for RTVEXITKEY and two command processing programs (you get to choose one) are listed below.

Here's the command definition source for RTVEXITKEY:

To use this command, compile it with the following options:

You have two choices for the program to call when this command is run. You can use either the CL example listed below or the RPG IV program listed after the CL (but not both!). The advantage of the CL is that it is quick and easy; the advantage of the RPG IV is that that you have more options and better control. For example, with the RPG IV version, you may specify the RTNF3 parameter, the RTNF12 parameter, or both; with the CL version, you must specify both return parameters.

Here's the CL version of the command processing program for RTVEXITKEY:

Here's the RPG IV version of the command processing program for RTVEXITKEY:

The following example illustrates how to use this command:

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.