Adding prompting to your user applications will help users translate cryptic codes into readable descriptions. Allowing selection by “human-readable” descriptions will allow users to find meaning in existing or new codes used in your applications.

We all remember the first day on the job, whether it’s your first job or your fifth. You’re excited—and you’re anxious to show the others what you can do. One of your newly acquired coworkers assigns you your first project. Apparently, there is a sales report that doesn’t seem to work quite right and is reporting incorrect sales data. Specifying a beginning and an ending item number, the program reports the units sold for the year. You quickly jump into the program to test it out. Then it hits you: Since you’re new to the company, you are not familiar with any of the item numbers used on the system. You think to yourself, “If only I could prompt on the item number parameter to select currently available items.”

Most relational databases include files known as master files. These files hold static information about unique entities used in your system. One example of a master file is the Item Number master file. In most cases, Item Number is the unique key for this file. It contains information about the item number, such as item description and item type. On some systems, the item numbers that are used really don’t have much recognizable meaning, or their meaning is so cryptic that it takes a user some time to figure out the naming system that is being used. Even then, the user ends up only memorizing the most frequently used item numbers.

A technique that could be used to help users find the item number they are looking for is called prompting. Some of you may be familiar with the concept of prompting and use it every day. Others may not be using prompting, whether it is from a lack of time or the lack of a good foundation on which to base your prompting program concepts. Prompting is really rather simple, and adds great functionality to any system. The prompting programs themselves are self-contained, reusable programs, generally using a subfile display listing available data.

The addition of prompting programs to any software is usually a simple task that can be done one program at a time. Whether your software is canned or homegrown, little modification is needed to existing applications to provide prompting. The minimum you need to add is processing for the prompting function key, usually F4, a couple of DDS keywords, and a subroutine to handle the prompting. Of course, a prompting program for each selectable entity is needed as well. I’ll start out by looking at a simple prompting program.

The Prompting Program Revealed

If you were to create a prompting program for the item file, users could simply prompt on an item input field and select the item number they are looking for from a list. The prompting program contains a simple subfile that displays the item description and any other information that will help users select an item number. At our shop, we prefer to use window subfiles, which give users the feeling that they haven’t really left the program they were running and that they are, instead, simply taking a small detour. Once they have selected the item number they want to use or cancelled out of the prompting program, control is returned to the original program and the Item Number field is filled in with the item number they selected from the list. See Figure 1 for an example of what the item number prompting window could look like.

You will notice that I have included one position to field and one select by field. Both of these fields add vast functionality to the prompting program, making the selection process even easier. They also can be used in conjunction with each other to push the usability of the prompting program even further.

The position to field is used to position the subfile to a particular item number. For example, users at an automotive accessory dealer might know they are looking for an item number starting with HC, which are the first two characters of all of the item numbers for hubcaps. But, since their plant produces many different types of hubcaps, the item numbers are sequenced following the HC with a style code, material code and size code. Giving users the ability to position the list to all of the item numbers starting with HC will allow them easier access to the item numbers they are looking for.

The select by field allows users to select items in the list by specifying a partial or entire item description. Using the same example as above, in which the users were looking for a hubcap item number, they could enter HUBCAP in this field, and every item with the text HUBCAP in its description will be displayed. The processing for this feature would check for the text entered on the select by field for a match anywhere in the item description during the subfile loading process.

The subfile column Sel is the field used to mark which record you wish to return to your calling program. When a user fills this column and hits the Enter key, the selected item number is returned to the calling program. The rest of the columns in the subfile window are simply for display.

With the code provided for this example prompting program, you should be able to produce a prompting program for any of your simple master files with little change. (All code examples are available for you to download from the MC Web site at www.midrangecomputing. com/mc/99/01.) In the display file (ISL001DF), you would change the output fields to display information about the entity that you are prompting for. This usually includes a description of some sort and any other data that makes the entity more “human readable.” In the RPG program (ISL001RG), the display file name and input file will change, as well as the subfile loading subroutine and the *ENTRY parameter list. At our shop, we like to name our prompting programs ending with SEL, which stands for “selection program.” This makes it easy to display a subsetted list of all the prompting programs’ source or program objects.

Putting Your Prompting Program to Work in an Existing Application

Now that the item number prompting program has been put together, all that is left is to change programs that have an item number as an input field to use this program. These programs could range from an item number maintenance application to applications that include the item number as an input parameter used in generating reports. For simplicity’s sake, I have provided the source for a simple display screen (IDS001DF) and processing program (IDS001RG)—also available on our Web site—that asks the user to input an item number, and displays the item description and quantity on hand. The DDS for my Item master file is also provided to give you a point of reference as to where the data is coming from.

The first thing that needs to be changed is the DDS for the Item Display application. If you don’t already have the Return Cursor Location (RTNCSRLOC) keyword coded in your DDS, this is the first step. If you are unfamiliar with the RTNCSRLOC keyword, read “Turning Pop-ups into Home Runs” (MC, August 1998) for a thorough explanation. Next, you will need to add two parameters to the RTNCRSLOC keyword in the record format containing the input field to which you would like to add the ability of prompting. In my example, the WSRCD field returns the name of the record that is displayed when the screen is processed. The WSFLD field will return the field name that the cursor was on when the read operation took place. In this case, you are only concerned with this when the user presses the prompt function key. Then, simply define these two fields as hidden character fields with a length of 10 bytes in the record format. (See Figure 2 for example code that includes these keywords.)

Don’t forget to add the prompting key, along with its keyword, to the list of function keys. Again, our shop uses F4 for the prompt simply because it is used as a standard not only with IBM, but with many software packages. We also like to add a highlighted plus sign (+) next to any field that allows prompting. This will tell the users on which fields they can use the prompt function key.

The next thing you need to do is add the prompting logic to the Item Display program. The first addition was to the function key processing Select statement. The added statement provides instructions for when the field is prompted. Figure 3 contains a code snippet to show you what code was added. It is a simple statement that tells the program to execute subroutine $Prompt when the F4 function key is pressed.

Now, you need to add the code for the $Prompt subroutine. This subroutine contains a Select statement with all valid fields that can be prompted on for the current screen. Figure 4 shows the simple code for the $Prompt subroutine used in the Item Selection program. For each promptable field, call the corresponding prompting program. The final “other” instance in the Select statement should be coded to display an error message to the user that the cursor is not on a valid prompt location.

Kick It Up a Notch

Now that you have seen the basics of prompting, and how little work it takes to provide what I feel is invaluable assistance to user applications, feel free to take this example and expand on it. There are a couple of openings to begin experimenting with ILE concepts here that shouldn’t require you to know everything there is to know about binding, modules, service programs, or binder source. Your experimentation might simply provide a good chance for you to get your feet wet and improve the functionality and ease of maintenance of your software.

One other addition would be to create prompting programs that return multiple values. At our shop, we do this by creating a file in the QTEMP library, filling it with the selected values, and then reading that same file after we return to the original program.

Since the purpose of the “RPG Building Blocks” column is not only to provide you with usable source for your software applications, but also to provide the spark for ideas on how to use the latest technology available, I feel that this would be a good point to start honing your ILE skills. Prompting is a feature that your shop may have lived without, and you don’t need to notify users about it until you have it entirely working (which will allow

you to tinker with the programs without interrupting production). After all, you have to start somewhere, right?

References

Application Display Programming (SC41-5715-00, CD-ROM QB3AUK00) ILE RPG for AS/400 Programmers Guide (SC09-2507-00, CD-ROM QB3AGY00)

Figure 1: The item number prompting window

A RTNCSRLOC(&WSRCD &WSFLD)

A WSRCD 10A H

A WSFLD 10A H

Figure 2: RTNCSRLOC keyword and parameters

C dow (W$KEY <> F3)

C EXSR $Display

*

C select

C when (W$KEY = F3)

C ITER

C when (W$KEY = F4)

C EXSR $Prompt

C endsl

*

C enddo

Figure 3: Code added to execute $Prompt subroutine

C $Prompt BEGSR

*

C select

C when (WSFLD = 'WSITM')

C CALL 'ITMSEL'

C PARM WSITM

C other

* Display error that the cursor is not on a promptable field.

C endsl

*

C ENDSR

Figure 4: $Prompt subroutine