This article is aimed at RPG programmers who remain captives in the exclusive world of RPG III/IV text-based (green-screen) programming and have not yet adopted any graphical interface tool.

Perhaps you’ve already explored Visual Basic and, like me, found the learning curve a bit overwhelming and time-consuming.

IBM’s VisualAge for RPG (VA4RPG) offers another way to get you on the GUI bandwagon. By first exploring the use of the product’s subfile function (which IBM calls a part) and a few push button events, I’ll attempt to answer the question: Is it worth your shop’s time to run a pilot project using VA4RPG?

Prior to the current release, which appeared in April 1997, VA4RPG was available only for OS/2. Today it also runs under Windows NT/95 and can create both Windows NT/95 and 3.1 executable programs. The tool assumes that an AS/400 is available for both external file descriptions and as a file server for remote data and that all graphical-design tasks, program compilation, and program execution occurs solely on the PC.

My Project Scenario

For this first-time application, I rewrote an existing AS/400 inquiry. The original AS/400 green-screen application displayed a list of project header records from a DB2/400 file. This inquiry is a production program that I have used many times and that I have found quite awkward. What better way to demonstrate the utility of VA4RPG (and particularly the strength of the subfile part) than to apply it to a realistic situation?

As suggested by IBM’s documentation, I first gave some thought to the design of the three graphical windows that would be required by this application. I laid out these windows with VA4RPG parts. These parts included static text (constants) that provide

window titles and label fields, the subfile part and its fields (columns), push buttons, and a user entry field for positioning the subfile. Figure 1 shows the main inquiry window, while Figure 2 shows the Subset window, and Figure 3 shows the Detail window of this design.

The AS/400 environment I used consisted of OS/400 V3R2 (VA4RPG is also available for V3R7), IBM’s Client Access/400, and Windows 95. My connection to the AS/400 was through twinaxial cable. Because the AS/400 model that I used was a limited development machine, my environment’s performance statistics would not be very relevant for a real production shop. Consequently, I’ve not included them here.

A Demanding PC Tool

VA4RPG shifts the design and compilation processes (called building the project) from the AS/400 to your PC. The AS/400 really has only two functions: providing external file descriptions during the project build and acting as the file server for DB2/400 data during program execution. As a result, your PC will be performing some intensive processing that previously would have occurred on the AS/400.

To use VA4RPG, IBM recommends you use a PC with a minimum of 16MB of memory, a 486-based processor, and 100MB of free disk space. The company also specifies an optimal configuration, which includes 32MB of RAM, a Pentium 90 box, and 250MB of available disk space. For many developers, this will mean a hardware upgrade. I used a PC with 24MB of RAM and a 120MHz Pentium, and my project build performance was quite acceptable.

Samples Galore

Before getting underway, I checked out some small sample projects that were installed along with VA4RPG. I found out about the samples in a VA4RPG manual, and I saved considerable time by reviewing them before starting to code my own project. IBM has included demonstration projects for most of the standard parts. Some of the sample projects, like the one containing the subfile, include examples of how to access DB2/400 files. I found these projects and the sample RPG IV code to be extremely helpful. For instance, some of the window manipulation techniques are not immediately obvious to a novice, and the sample code helped me get over these initial hurdles.

Linking VA4RPG to the AS/400

VA4RPG assumes that a connection, such as Client Access/400, already exists between your AS/400 and your PC. Still, as part of each project, you must define certain AS/400-related system information. This definition includes the logon profile and password (not shown), and the server and file alias information. Figures 4 and 5 show the definition windows. Regardless of your system, library or file names, you must provide this alias information in order for the build process to work. In fact, defining a generic alias for the AS/400 server name (for example, HOST) has the advantage of allowing all subsequent file definitions to be associated with that server alias. If you use this technique, you won’t have to hard code all of the AS/400 file information during development and then redefine the information for production environments. By using this alias-naming technique and assuming that library names remain the same, only the AS/400 server alias needs to be changed when you install the project on a different AS/400.

Some Non-Visual Basics

VA4RPG lets you select from a palette of icons (called parts) to build your graphical interface. The parts palette is shown in Figure 6. These parts include the familiar push button part, the entry field part, the radio button part, and the check box part, and well as many others. A separate project window (shown in Figure 7) lists all parts you have used and neatly organizes all the parts created in a hierarchical tree structure that can be easily expanded or collapsed. This feature keeps track of the parts that you have used, the

parts that are contained in other parts, the part names, and their associated part types. If you’ve used Visual Basic, this approach should be familiar.

When I started up VA4RPG for the first time, I was presented with the parts palette, the project list window, and a default part window that was automatically created. This default part window, called a window with canvas, is the only window that is capable of containing other parts. To add a subfile part to this window with canvas, I simply dragged the subfile part icon from the parts palette and dropped it onto the window with canvas part. This started the process of defining the subfile. At this point I was thinking, “This is a piece of cake!”

New parts are assigned default names that should be changed right away. Except for the use of a consistent prefix, VA4RPG-assigned names are totally meaningless. Make sure you rename your parts before you write any program code that references them. It is important to establish a prefix naming convention that will give all parts meaningful names. I left VA4RPG’s names on a few parts in my example so you can see the names for yourself. See if you can determine what the parts with default names actually represent.

Refining the Subfile Part

Next, I added the subfile fields, or columns. Since you can use fields from an AS/400 file and stand-alone work fields in a subfile, I decided to use both. When you right-click on the subfile part, a pop-up window is invoked. From this window, you can select the Properties menu item. All parts, including the window itself, give you the ability to define the part’s properties, although the contents of those properties may differ according to the type of part that you select.

I clicked the notebook tabs labeled General and Field Lists to complete my definition of the subfile. The General tab contains the part name, which I renamed SF1, and the Field List tab, which is where I defined the database and the work fields. (See Figure 8 to see how this appears.) To add fields from an AS/400 file, you would click the Add Before/After button on the Properties notebook. This will display information from the DB2/400 database file, and will allow you to define the column headings and reference fields.

It is simpler and easier to define parts by defining the fields from an DB2/400 field reference file. To do this, you click on the Server menu. This menu displays a tree view of your AS/400 and easily expands to include authorized libraries, files, and record formats. Once you display the record format of your desired AS/400 file, the fields can be dragged directly onto the subfile part (see Figure 9). This step was easy to accomplish, and I was pleased that it worked as smoothly as it did.

Field-level definitions are found within the subfile field’s Properties notebook. To complete my definition of the fields in my example, I only needed to specify a column header and to assign the edit codes for the numeric fields. One thing I really liked about the subfile part is the fact that I didn’t have to do anything extra to obtain vertical and horizontal slider bars. You can include fields that extend beyond the right border of the initial display and—depending on the size of the file—you could load the entire DB2/400 file into the subfile and simply let the user scroll through all the entries. No more fussing with the conditioning of “More...” and “Bottom.”

Push My Buttons

Finally, I added static text (constants), an entry field, and a push button for positioning the subfile, plus three more push buttons to the bottom of the main window. The three push buttons let you subset the list of displayed records, show you the details of a selected project header record, and exit the program. Once again, I found that adding the entry field and push buttons was as easy as dragging and dropping, but there’s still more to this easy programming interface. VA4RPG also provides some handy alignment

capabilities for spacing parts evenly. This let my final window design present a more professional look.

So how hard was all this? Excluding the time I spent reading the IBM reference manuals (twice), it took about two hours to get the windows designed the way I wanted them. By the time I finished, I was actually enjoying the entire GUI design/layout experience.

The Press Event

What had been fun turned somewhat more difficult when I entered the world of event-driven programming. The time I saved in the subfile data description specifications (DDS) and related RPG coding went into learning how to actually make action subroutines work. This process—the process of coding the event-driven logic—is where you can expect the major learning curve to occur.

Let’s look at the Exit push button on the main window. By right-clicking on the push button part, you will display a pop-up menu that includes a menu item for Events. If you click this item a list of all the possible part events will be displayed. Event examples for a push button include Create, Destroy, MouseMove, and Press. If you click the Press event, the project’s source member will be opened and a skeletal action subroutine will be inserted into the code. VA4RPG provides some customizable standard header information for the routine, as well as a Begin Action (BEGACT) statement, with the event’s name, the part’s name and the window’s name in the appropriate Factor and Result fields. It also creates an End Action (ENDACT) statement at the bottom of this skeletal subroutine. I then entered my own RPG IV statements within the boundaries of the action routine, just as you would when working with any RPG subroutine.

Within VA4RPG, action subroutines are a new extension to RPG IV. They contain the program code that is executed when a certain part on a window incurs some predefined event that you need to handle. However, you don’t need to write code for every event, and not every event is complicated. For example, to use the Press event on the Exit push button, you only need only to set on *INLR (see Figure 10, Label A). No other events need to be coded for this push button. If an uncoded event occurs, the program will not take any action.

The Main Event

Since I wanted the subfile part to have all records from the file loaded upon its first display, I used the Create event against the main inquiry window itself (FRA0000B) to load the subfile. The design called for this window to be opened immediately upon execution of the application, which results in an automatic Create event for the window. I found that loading the subfile records into the subfile was easier than I expected. The project number field (PROJNO) from the AS/400 file matched the subfile field name and loaded automatically. Calculated fields simply had to be coded before the Write operation was issued against the subfile part SF1 (see Figure 10, Label B.

My experience with this subfile load example leads me to recommend that during all group database operations, an informational message should be displayed to the user. Even with a small number of records, the initial load took longer than expected (about 20 seconds for 50 records on my machine). Nevertheless, it was fun to watch the vertical slider bar reduce in size as records seemed to magically load into the subfile. In case you are keeping track, at this point I had put a total of three hours into creating an operational subfile.

I now wanted to allow the user to click on a subfile record and then click the Details push button to display the detail window. Again, I used the Press event for the Details push button. Unexpectedly, I had a difficult time getting something as simple as the display of the project header details to work. The problem was that references to any of a window’s parts are actually ignored until the Show Window (SHOWWIN) operation code is

executed. See Figure 10, Label C to see how I fixed this problem. You should know that if the new Show Window (SHOWWIN) operation code (which “shows” a window that is not initially displayed) only makes the window active in memory. It doesn’t actually display the window when executed. Apparently, this occurs when the action subroutine ends.

The SubSet Push Button

Finally, I wanted to give the user the ability to subset the record list based on certain criteria, similar to the PDM command key 17 function. In setting up this function, I learned a number of interesting things: how to read values entered into a window by the user, how to clear and rebuild the contents of the subfile, and how to remove the Subset window from view and return to the main window.

Again, I used the Press event for Subset push button. While you can always issue a SHOWWIN and then a CLSWIN (Close Window) operation, the VA4RPG sample projects demonstrate a more efficient method. Using a flag field, the program executes the SHOWWIN the first time only. Subsequent requests to display the window need only to set the window’s attributes on for Visible and Focus. To remove the window, the window’s Visible attribute is set off.

So, what’s an attribute? Each part has certain characteristics or attributes. Some of these attributes can be set at design time and/or manipulated at execution time. Two important attributes available for controlling windows are Visible and Focus. You can set the visible attribute off at execution time, which allows a window to remain in memory without being displayed. By the same token, the Focus attribute forces a part to be selected—that is, active—and ready to receive a user action, such as a click on a push button. If the Focus attribute isn’t turned on, the user must click on the window first to make it active. Other common attributes control background color, font, window height and width, and the part’s name. Two new operation codes to Set Attributes (SETATR) and Get Attributes (GETATR) are available (you can also use their equivalent built-in functions, %setatr and %getatr). They allow you to manipulate eligible attributes at execution time. Examine the sample code to see how the window logic allows the window to stay in memory and simply be hidden when not needed (see Figure 10, Label D). While not covered extensively in my project, controlling attributes for parts consumed a significant amount of design consideration and coding.

Worth a Pilot?

This first-time project demonstrates some of the graphical design and programming tools available in VA4RPG, the simplicity of connecting to an AS/400, and the ease with which a subfile can be designed and coded. It also shows you where the significant learning curves are to be found: in the GUI design of the collection of parts and the event- driven approach to handling a wide variety of potential user actions. All in all, I conclude that if you’re looking for a simple and direct method of providing GUIs to your users, then this product is definitely worth a pilot project in your shop.

References IBM Web Site: www.software.ibm.com/ ad/varpg Getting Started with VisualAge for RPG (SC09-2448-00) Programming with VisualAge for RPG (SC09-2449-00) VisualAge for RPG Language Reference (SC09-2451-00)

Figure 1: Main Window for the Project Master Inquiry Figure 2: The Subset Criteria Window

Figure 3: The Project Header Details Window Figure 4: Define AS/400 Information—The Servers Alias

Figure 5: Define AS/400 Information—The Files Alias

Figure 6: The Parts Palette

Figure 7: The Project Parts Collection Figure 8: The Subfile Parts Properties Notebook

Figure 9: Define AS/400 Reference Fields

Note: This is not the complete listing of the code, but only the samples representing the points made in the
text of Jef’s article.

*********************************************************************

* Window . . : Main window *

* Part . . . : Exit Push button *

* Event . . : Press *

*********************************************************************

*

C PSBEXIT BEGACT PRESS FRA0000B

*

C Eval *INLR = *ON

*

C ENDACT

*********************************************************************

* Window . . : Main window for display of Subfile *

* Part . . . : Window with Canvas *

* Event . . : Create *

* Description: Fill the subfile with records from the header file

*********************************************************************

*

C FRA0000B BEGACT CREATE FRA0000B

*

C Clear SF1

*

C Move *Blanks ProjNo
C ProjNo SETLL CIPHEAD
C Read CIPHEAD 30

*

C *IN30 DowEQ *Off
C Z-add OrgBud Budget
C MoveL(P) Desc Desc35
C Z-Add VXCOMH TotalPOs
C Budget Sub TotalPOs Variance
C WRITE SF1
C Read CIPHEAD 30
C EndDo

*

C ENDACT

*********************************************************************

* Window . . : Project Master Inquiry *

* Part . . . : Subset push button *

* Event . . : Press *

* Description: Display the subset window. Issue ShowWin first time. *

* Thereafter, set attributes for Visible and Focus. *

*********************************************************************

*

C PSBSUBSET BEGACT PRESS FRA0000B

*

C SubFlag IfNe *ON
C Move *ON SubFlag 1
C ShowWin ‘FRA0001E’
C Else
C Eval %SetAtr(‘Fra0001E’:

C ‘Fra0001E’:
C ‘Visible’) = 1 *

C Eval %SetAtr(‘Fra0001E’:
C ‘Fra0001E’:
C ‘Focus’) = 1
C EndIF *

C ENDACT

*********************************************************************

* Window . . : Subset Criteria *

* Part . . . : Cancel push button *

* Event . . : Press. Set Visible attribute off to hide the window. *

*********************************************************************

*

C PSBCANCEL BEGACT PRESS FRA0001E

*

C Eval %SetAtr(‘Fra0001E’:
C ‘Fra0001E’:
C ‘Visible’) = 0
C ENDACT

Figure 10: Program Source Code