Wed, Apr
5 New Articles

A GUI Experiment with IBM's VisualAge for RPG

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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)

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG06-00.jpg 400x300

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

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG06-01.jpg 400x320

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG07-00.jpg 400x270

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

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG07-01.jpg 400x288

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG08-00.jpg 400x288

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

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG09-00.jpg 300x633

Figure 6: The Parts Palette

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG10-00.jpg 400x358

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

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG10-01.jpg 400x320

A_GUI_Experiment_with_IBMs_VisualAge_for_RPG11-00.jpg 400x304

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 Eval *INLR = *ON




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

* Part . . . : Window with Canvas *

* Event . . : Create *

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





C Clear SF1


C Move *Blanks ProjNo


C *IN30 DowEQ *Off
C Z-add OrgBud Budget
C MoveL(P) Desc Desc35
C Budget Sub TotalPOs Variance
C EndDo




* 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 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 *



* Window . . : Subset Criteria *

* Part . . . : Cancel push button *

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





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

Figure 10: Program Source Code



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: