VisualAge for RPG: Who Knew It Was So Much Fun?

by Shannon O'Donnell

IBM's VARPG tool has been around for a long time, but most iSeries programmers have never used it. Why? Probably because until just before OS/400 V4R5 came out, VARPG would run only on OS/2. Ugh! OS/2 barely ran on OS/2, let alone on other software. Those of us who were brave did use VARPG on OS/2 for a while, but it was so buggy, and OS/2 was such an unpopular operating system, that it just never caught on. The other reason most of us have never used VARPG before now is that it was relatively expensive. But all of that has changed. VARPG is now included as part of the WebSphere Development Studio suite of tools. And if you already own at least one compiler on iSeries, these tools are available to you for free.

Event-Driven Programming

So why is VARPG so much more fun than programming yet another 5250 display file? One reason is event-driven programming. Event-driven programming is simply forgetting about the traditional procedural-driven, top-down, logic-cycle style of programming and, instead, programming to react to user or operating system events.

So what's an event? An event is any "action" that happens to any part of your VARPG application. For example, when a user first executes a VARPG application, a "create" event is fired. When the user clicks on a button, the "press" event is fired, and so on. In VARPG you "trap" events so that when the user or the operating system does something, you can provide code to react to the event. For example, if the user presses a button to display some text, you'll provide some RPG code behind that event to make that code visible.

VARPG IDE

Assuming you have the WebSphere Development Studio tools installed on your workstation, start the VARPG GUI Designer tool. (If you don't have them installed, you should do so before continuing.) When you do, you'll see a screen very similar to the one shown here:

When you want to add "parts" to the window (or Form), click on the part you want to add--say a button--and drag it to where you want it to reside on the window. You can also resize the button (or whatever part you dragged to the screen) and set various properties for it.

To trap for an event on a part--say a user pressing a button--right click that component and select the appropriate "event" from the Events menu item on the pop-up menu that will appear.

Now let's create a simple, new application so that you can see how the whole process works!

Hello, World

If you haven't done so already, start the VARPG GUI Designer and let it create a new project with one generic window. If the Parts Catalog does not appear, or if you want to change it's view from Catalog to Float, click the IDE's Options menu item, then click Parts Palette and, finally, either Float or Catalog. You can also drag the Parts Catalog around the screen by clicking once in the blue title bar of the catalog and then dragging it to where you want it to go and then releasing it.

OK! Let's add some stuff to our window.

Before we do that, let's change the name of our window to something more descriptive and add a title to it.

1. Double-click the blue bar section of the window (where it says "Window with Canvas") to display the window's Properties panel.

2. Change the text in the Part Name field to WIN1.

3. Change the text in the Title field to Hello World Application.

4. Close the Properties panel by clicking the OK button.

Now we need to add a couple of buttons to the window. One button will allow the user to display some text. The other will close the window.

1. Click the "Push Button" part from the Parts Catalog and drag it to your window. Once there, double-click the new push button you just added (or right-click and select Properties) to display the button's Properties panel.

2. Change the text in the Part Name field to PSBEXIT.

3. Change the text in the Label field to Exit.

4. Click on another "Push Button" part from the Parts Catalog and drag it to the screen. Place it somewhere near the first push button. Double-click the new push button to display its Properties panel.

5. Change the text in the Part Name field to PSBSHOW.

6. Change the text in the Label field to Display Text.

Note: The values PSBEXIT and PSBSHOW are arbitrary. That is, you can name them anything you want to. I always try to use a name that is descriptive, but feel free to name one Flamingo and the other Snail, if that ‘s what turns your crank.

Now let's add a Static Text field.

1. Click the Data Entry tab on the Parts Catalog to find the "Static Text" part, and then drag one "Static text" part to the window. Place it somewhere in the middle. If you are using the floating parts palette instead, look for the big A and small A (AA) that signifies the "Static text" part.

2. Double-click the "Static Text" part you just added to this window to display the Property panel for this text.

3. Change the Part Name field to MYTEXT.

4. Blank out whatever text is currently in the Text field. We'll dynamically add some text to it later on.

5. Locate the Visible box on the Properties panel. It should have a check mark in it. Click once to uncheck it.

At this point, your screen should look something like the one shown here:

Time to Add Some Code

Now it's time to trap some events and add some code. This is where you get to see how easy it is to trap events and to use your existing RPG skills to create Windows applications.

1. Right-click the Exit button on your window.

2. Click the Events menu item, and then click Press.

We'll trap the Press event (what happens when the user clicks the Exit button).

The Exit button is going to be used to close our program, so we need to add code to end the program. How do you do that in VARPG? The same way you do it in RPG: You code an EVAL *INLR = *ON statement!

When you clicked the Press event, VARPG automatically opened a generic, skeleton RPG source file in CODE/400's CODE/Editor. Notice that you are automatically taken to the PSBEXIT Action subroutine. Notice also that instead of the familiar BEGSR (Begin Subroutine) op code, there is a new op code: BEGACT. This indicates to the VARPG compiler that this is the start of an ACTION (or event). A BEGACT action subroutine is terminated by an ENDACT (End Action) op code.

To add a new line of code, press the Enter key. A new, empty, C-spec is added for you automatically to the source member. Modify this line of code so that it looks like this:

C                   Eval      *Inlr = *On

Once you've entered the code, click the Save button in your toolbar and close the CODE/400 window.

Now let's go back to the GUI Design screen again.

1. Right-click the Display Text button.

2. Select the Events menu item.

3. Click the Press event.

Once again, the CODE/Editor will open, this time to the PSBSHOW Action subroutine. What we need to do now is two things. First, we need to set the value of the Text property for the MYTEXT Static Text field. Second, we need to set that Static Text so that it is visible. Add the following lines of code to the PSBSHOW Action subroutine, then save and close the CODE/400 window:

  C          Eval     %Setatr('WIN1':'MYTEXT':'Label')=              
  C                          'Hello World'
  C          Eval     %Setatr('WIN1':'MYTEXT':'Visible')=1 

The %Setatr (Set Attribute) is a new built-in function, valid only in VARPG, and it is used to set the various properties of a part. In this example, we are setting the value in the Label property (which is the text the user will see), of the Static Text part named MYTEXT, which resides on WIN1, to the value of Hello World. The next line of code sets the Static Text field named MYTEXT, which resides on the window named WIN1, so that it's Visible property is "true." This last line of code will display the text to the user. We'll cover the %SETAR and the other new op codes and built-in functions you'll use in VARPG in future articles.

Building and Running Hello World

The next step is to build a native Windows application from the GUI you created. To do this, locate the tool bar that looks something like a skull cap with little wavy lines hanging below it. It's just to the left of the tool bar icon that looks like a coffee pot. If you're not sure which toolbar item to use, move your mouse over each toolbar item in the list, and pause. The icon's hover text will appear to identify that toolbar item. Hover until you find hover text that says, "Build the Windows NT/95/98 version of the project."

Find it? Good! Click it. You'll be prompted to save your application. Since this is the first time you've attempted to save the application, you'll need to enter a name for it in the Application Name field. Call your application Hello World. Click once in the Source File field to automatically copy the name you gave to your project to the Source File field. Don't worry if the entire name doesn't fit in the Source File field; it's for internal use only anyway. Click the OK button to save your project, and start the Build process. If you followed these instructions exactly, everything should compile cleanly. If not, you'll get a list of errors. Double-click each error, to be taken to that spot in the code where you can edit/fix the error, save it, and try to build it again.

If everything built correctly, it's time to run the application. To run it, locate the icon of a little running man and click it. The Hello World application will appear. Click the Display Text button to see your text appear. Click the Exit button to end the program.

What Fun!

Programming in VARPG is a lot of fun, especially when you get into some of the more complex features such as subfiles, list boxes, ActiveX components, Java Beans, and all the other cool things available to you. The example shown in this article is very simple, but it does help you get your feet wet. In future issues, I'll cover more advanced, and more useful, topics that show you just how useful VARPG can be.