by Jay Oswal

No more theories. No more practice samples. No more incomplete code. Here is a business-quality RPG Web program for file maintenance that actually works in the live production environment.

Most RPG programmers would love to deploy their interactive RPG applications via an Internet browser without sacrificing their hard-earned RPG skills, wasting years to learn some strange language, or navigating torturous learning curves. Figure 1a shows an actual file maintenance RPG program in production. This program can serve as a template for other programs and inspire RPG programmers who want to replace the 5250 screen with a Web browser but don’t know where to start.

The program, VM (Vehicle Maintenance), was written entirely in ILE RPG and performs common file maintenance functions (e.g., display, modify, insert, delete) against the Vehicle Master file (VEHMST). It uses two HTML documents — VMLST and VMDTL — as the user interface, as well as free APIs from IBM’s CGIDEV2 Toolkit. The interface uses the same theme as a traditional subfile and detail maintenance screens, and includes all error and completion messages. All of the objects used by this application reside on your iSeries, and users simply use an Internet browser to access them from their PCs on a shared TCP/IP network.

Although a good knowledge of HTML and JavaScript will definitely help you develop more advanced Web applications, you can get started now with just basic knowledge. You can learn from the thousands of HTML and JavaScript examples on the Internet; however, the best way to learn application development is to install a useful business-quality application that actually works, look at the result it produces, investigate the code that made it all possible, and then clone it to suit your particular needs.

This article explains how an ILE RPG program on the iSeries (VM in this case) can interface with the users via an Internet browser. This application lists the records from Vehicle Master file, then lets users not only display, add, change, and delete the records, but page up, page down, refresh, and position them as well.

It is crucial that you load and run the application before trying to understand how it works, and that you read the entire article before actually performing the instructions. Total estimated time to implement the application is two hours. I created VM on an iSeries running OS/400 V5R3M0. For a complete list of application requirements, see „Program Requirements“ on page ProVIP 18.

Getting Started

2006 Oktober2 Utility der NEWSolutions
Load´n´go	Load n Go Programm: A Business-Quality RPG Web Application by Jay Oswal

When you’re ready to begin, you’ll need to perform the following four steps.

Step 1. Install the CGIDEV2 Toolkit. Go to the IBM Web site and download the CGIDEV2 Toolkit (www-03.ibm.com/servers/eserver/services/assets/ebus_rpgcgitoolkit.html). Follow the instructions to load the CGIDEV2 Toolkit as well as to configure the HTTP server CGIDEV2APA to run your Web applications. Step 2. Deploy the application. This article provides four source members, a sample data file, and vehicle images:

• VEHMST(qddssrc.vehmst) — DDS source for a Vehicle Master physical file
• VEHMST(vehmst.vehmst) — Vehicle Master sample data file
• Files *.jpg and *.gif — Vehicle images referenced by VEHMST
• VMLST(htmlsrc.vmlst) — HTML source for the Vehicle Maintenance subfile
• VMDTL(htmlsrc.vmdtl) — HTML source for Vehicle Maintenance record details
• VM(qrpglesrc.vm) — ILE RPG source for the Vehicle Maintenance program

Download all of these files to a folder (e.g., c:\CGIDEV2) on your PC. Upload the following four files to library CGIPGMR using the FTP commands in Figure 2 (the record length of the HTMLSRC source file is 240 bytes):

• Upload qddssrc.vehmst to CGIPGMR/QDDSSRC .VEHMST.
• Upload htmlsrc.vmlst to CGIPGMR/HTMLSRC .VMLST.
• Upload htmlsrc.vmdtl to CGIPGMR/HTMLSRC .VMLST.
• Upload qrpglesrc.vm to CGIPGMR/QRPGLESRC .VM.

Next, run command ADDLIBLE CGIPGMR. Then, using WDSc or PDM, set the member types for the uploaded source members as follows:

• VEHMST PF

 

• VM RPGLE

 

 

• VMDTL HTML

 

 

• VMLST HTML

 

 

Compile the source member VEHMST to create an empty physical file VEHMST in library CGIPGMR (this is required for the next three steps). Create the RPG program VM using command

CRTBNDRPG PGM(CGIPGMR/VM)   
SRCFILE(CGIPGMR/QRPGLESRC) SRCMBR(VM) 
DFTACTGRP(*NO) ACTGRP(VM)       AUT(*USE)

Upload vehmst.vehmst to library CGIPGMR. It will replace the empty member of VEHMST with the sample data (Figure 3). Next, upload all the images (files with .gif and .jpg suffices) to IFS directory /cgipgmr (Figure 4). HTML members are not compiled.

Step 3. Run the application. Open your Internet browser, type http://youras400:8030/cgipgmrp/vm.pgm into the address window, and press Enter. Doesn’t it look like a typical iSeries file maintenance program? Feel free to navigate all the windows by using the buttons; it’s the sample data anyway. Here is an idea: Back up the VEHMST to VEHMST.BKP, run command CLRPFM CGIPGMR/VEHMST to empty the file, and test the program to see the difference in the buttons. Then, copy the backup file back to the original file. Make sure that you try every button and input field to understand the functionality of the program. Let’s look at the application details next.

Step 4. Understand the application. By now you must realize that, as an RPG programmer, you have already written many programs such as this one using the 5250 display as the user interface. You need to learn only a handful of new items to start developing your next RPG program using the Internet browser as the user interface. Figure 5 shows a comparison between 5250 and Web programming in ILE RPG. It is important that you remember this comparison while dissecting the program to see how it works.

In summary, this is what happens:

• The user types http://youras400:8030/cgipgmrp/vm .pgm in the address box of an Internet browser window to call the program VM that resides at a location referenced by cgipmrp on „youras400“ system, using the transport services of an HTTP server running at port 8030.
• Upon receiving the user request via the HTTP server, OS/400 starts program VM in a job.
• Program VM retrieves input data from the HTML fields and populates the internal program variables (remember that HTML can handle only character variables).
• Based on the requested function, the program VM
  1. opens the copy of a suitable HTML member (e.g., VMLST to display a list or VMDTL to handle the record details)
  2. prepares the required response using RPG logic
  3. populates the HTML output fields (similar to DDS fields)
  4. writes the required HTML sections (similar to DDS records in a display file)
  5. hands over the finished HTML document to the HTTP server
  6. ends, along with the job it was running in
• When the user responds by clicking a button, the cycle repeats.

Application Details

Now let’s look at how the RPG program VM uses HTML documents VMLST and VMDTL as the new Web interface. The best way to learn the application details is to keep the following items open simultaneously and follow the explanation.

• Open the application by typing http://youras400:8030/cgipgmrp /vm.pgm into the browser’s address field.
• Open the HTML source members VMLST and VMDTL in Notepad.
• Open the RPG source member VM in Notepad.

Opening the source members in Notepad helps you scroll the code easily and enables you to make your own notes within the source members without affecting the originals. The Initial List — HTML Source Member VMLST Entering http://youras400:8030 /cgipgmrp/vm.pgm in the browser’s address field causes the HTTP server CGIDEV2APA to start the RPG program VM on the iSeries. The program uses several copy members to gain access to the required HTML APIs. For the sake of simplicity, I use two different data structures to hold the input and output fields named as such. The program VM overrides the VEHMST file to the one in library CGIPGMR because the HTTP server does not recognize the user’s library list. The program uses the ZHBGETVAR API to copy the contents of input variables from the HTML form into the input variables of the program. Unfortunately, the first time around there is no HTML form in the browser. Therefore, all the input variables are blank, and the subsequent Select statement executes subroutines BGNLST and REFRESH. The BGNLST subroutine uses the GETHTML API to access the HTML source member VMLST, determines the number of rows to display, updates two HTML fields using the UPDHTML VAR API, and copies the HTML section /$top into the program buffer using the WRTSECTION API. The REFRESH subroutine builds a list of VEHMST records starting at the first record in the file and updates the required output fields. It uses the subroutine WRTTABROW to build the list by repeatedly writing one HTML table row at a time into the buffer. The program compiles a Web page by sequentially writing the required sections, similar to writing DDS records to build a 5250 screen. It also writes the end part of the HTML table using the subroutine WRTTABEND. Finally, using the subroutine UPDPGMCTL, the program updates the remaining HTML output variables, writes the /$hidden section of VMLST to preserve the hidden variables in the Web page, writes the *fini section, closes the data file, and ends — losing all the information in its buffer. Let’s take a closer look at what’s happening here. The HTML section /$hidden is a secret between your RPG program and the HTML page in the browser. This is where you store the information necessary to run the next instance of your program whenever the user decides to make the next request. When a user clicks a SUBMIT button to submit the HTML form described in the browser page, VM starts again. The previously stored information is read back into your program via the GET HTMLVAR API for successive processing — for example, to page up or down, or to decide where to position, display, or modify the list. The section *fini is mandatory; it tells the WRTSECTION API to actually send the compiled Web page to the HTTP server. This in turn transmits the page to the user’s browser, which converts it into a graphical Web page.

Detail Functions — HTML Source Member VMDTL

Suppose a user selects a record from the VMLST page by clicking the radio button and then pressing the Modify button (Figure 1). The HTML code in the /$buttons section indicates that when a user clicks the Modify button, the value of the document’s property when „pressed“ equals that of the button itself (i.e., Modify). Notice that the Modify button type is SUBMIT and that the

tag (at C) specifies onSubmit=“sbmform1(), which tells the browser to execute the JavaScript function sbmform1 (at A) and then submit the form to the server for processing. Now look at the code for function sbmform1().
JavaScript functions perform client-level logic without bothering the server application (i.e., your RPG program VM). Let’s see what the JavaScript function sbmform1 does for our application. First, it stores the value of the pressed button — in this case, Modify — into the hidden input variable Irequest. Then, if the button pressed is Pageup, Pagedown, or Refresh, it sets the target window for the next form as the same one (i.e., VMLST). Otherwise, it sets a blank window as the target for the next form (VMDTL, in this case), thereby not erasing the original VMLST window.

How does your program know which record the user selected for modification? In the HTML section /$tabrow, the input field Iselect, which is the radio button that the user clicks to select the desired record, contains the vehicle ID (vhid) that belongs to the record. We need to examine all the radio buttons to see which one is checked and copy the vehicle ID to another hidden variable named Iselkey. This is what the function sbmform1 does (at B); it initializes Iselkey to blanks, assigns the numeric value of the number of displayed records from the hidden field Idsprows to the variable nnn, loops through all the radio buttons, and assigns the value of the checked field Iselect to the Iselkey variable to be returned to the RPG program. And, because the Modify button is of the type SUBMIT, all the fields within the form are automatically submitted to the HTTP server, which in turn calls the program VM to process them.

Let’s review some important points before handling the Modify request from the user:

tags).

• The RPG program updates the only HTML fields that are surrounded by /% and %/ (e.g., /%vhtag%/).
• The RPG program can read from any field as long as it’s inside an HTML form (i.e., between the and

Writing the *fini section signals the HTTP server to send the compiled Web page to the browser. It must be spelled as shown, but you can name all other HTML sections as you like.

JavaScript is an object-oriented language. It uses methods to manipulate object properties and values. For example, „var nnn = parseInt(document.form1 .Idsprows.value, 10);“ will parse the character value of variable Idsprows located in the form form1, which is a property of the current document, into a 10-base integer and assign it to local variable nnn.

JavaScript code can directly refer to its own local variables (e.g., nnn), but it needs to use the .value property for all other variables (e.g., Iselkey.value).

JavaScript can validate user input to a certain degree (e.g., the function chknum can be used to allow only the numeric input).

If you have multiple forms in a single HTML source member, give them different names.

When a user makes a request to modify a specific record by clicking a radio button from the list, the program must present its fields in input-capable format for the user to modify them in a separate window, based on the HTML member VMDTL. When the program VM restarts, the uppercase value MODIFY in the variable Irequest directs the Select statement to execute subroutines BGNDTL and MODIFY. Subroutine BGNDTL gains access to the HTML member VMDTL, updates a couple of variables, and writes the /$top section of the Web page. Subroutine MODIFY needs to determine the origin of the request, which is stored in the variable Ipageid. If the request originated from the List page (i.e., VMLST), then the subroutine reads the VEHMST record using VHID as the key, and updates the input capable fields in the HTML section fldsin. Then it writes the HTML sections fldsin for user input, keysout for output fields, and cnfchg to solicit confirmation. If the request originated from the Modify page (i.e., VMDTL), then the Modify subroutine tries to update the record using the user input. If the update is successful, it writes the section okchg, indicating a success message. If it doesn’t find the record to update, it writes the section notfound. It writes the section cnfok to get the user’s permission to close the window by using JavaScript method window.close. The other requests (e.g., Display, Insert, Delete) are processed in the similar fashion. Before moving on, take a few moments to examine the various JavaScript functions used in the source member VMDTL. Note that the confirm functions are called alerts. All of these functions run in the browser and are independent of the RPG program.

The List Functions

What happens when a user requests Pageup, Pagedown, or Refresh? When programming in RPG for the 5250 interface, you get some built-in assistance for the automatic Pageup and Pagedown functions for your subfiles. However, when using HTML as your interface, you must code the logic for paging the record list. The first list that a user sees is generated by subroutine Refresh, using the first VEHMST record as the beginning of the list and the field dftrows as the number of rows to display. A user can customize this list by

• specifying a desired number of rows (nnn=Ireqrows) to be displayed per page
• specifying a desired vehicle ID to begin the list at (Iposnto)
• clicking Refresh to update the page with the specified number of rows, to start the list at specified vehicle ID, and to get the latest updates
• clicking Pageup to display the previous nnn rows
• clicking Pagedown to display the next nnn rows

Refresh

When a user clicks the Refresh button, the program executes the Bgnlst and Refresh subroutines, where it performs the following tasks to properly populate the list page VMLST:

• determines the beginning key (the vehicle ID) using field value for Iposnto
• checks to see whether there are any records before the requested beginning key so that it can display the Pageup button
• writes the requested number of rows
• reads an additional record to see whether more records are in the file so that it can display the Pagedown button
• writes the table end, updates the hidden variables, writes the required sections, and ends

Pagedown

When a user clicks the Pagedown button, the program executes the Bgnlst and Pagedown subroutines, where it performs the following tasks to properly populate the list page VMLST:

• ignores the requested beginning key value in field Iposnto; it’s irrelevant
• checks to see whether any records have key equal to or less than the currently displayed ending key (Iendkey) so that it can display the Pageup button
• reads and writes the requested number of rows
• reads an additional record to see whether more records are in the file so that it can display the Pagedown button
• writes the table end, updates the hidden variables, writes the required sections, and ends

Moving Forward

When you use HTML, JavaScript, and RPG to create your own interactive Web applications, be sure to consider the following points.

• Using HTML. VMLST lists the database records and offers common database maintenance functions. VMDTL lets users work with a selected database record. Here are some HTML tips to remember:
  • Tags (e.g., ,) direct the browser to format a Web page.
  • Sections (e.g., /$top, /$tabrow) are similar to DDS records; you divide the HTML code into various sections in such a way that when assembled, it yields a meaningful Web page based on the program logic. The program writes sections to construct a Web page the same way it writes DDS records to construct a 5250 screen.
  • JavaScript (the code between <script> and </script>) lets you code client-based logic to perform functions such as data validation, messaging, and dynamic controls.
  • Forms are the vehicle to transport data between the Web page and the RPG program on the server. Only the data inside a form can be returned to the RPG program; however, the RPG program can write data either inside or outside a form.
  • Tables allow for cleaner presentation and the ease of programming. To achieve these benefits, always organize your data on the Web pages using rows and columns of tables.
  • Data fields allow you to assign the prefix „I“ for Input and „O“ for output, with respect to the RPG program. The program reads the values from Ixxxx fields and writes the values to Oxxxx fields; the output fields are actually substitution variables and act as the values for the real HTML Ixxxx fields.
• Using JavaScript. HTML documents use JavaScript functions to perform on-the-fly client tasks without consulting the RPG program on the server. Following are some JavaScript tips:
  • You can start learning this language by analyzing the sample functions.
  • Keep all the JavaScript functions inside the <body> </body> tags to assure that they always get loaded, no matter how you format the rest of the page.
  • Try to use JavaScript functions for as many tasks as you can accomplish on the browser page without making unnecessary trips to the server asking the program for help.
  • JavaScript can handle character and numeric variables.
• Using RPG. The RPG program VM acts as a Common Gateway Interface (CGI). It performs input and output operations to HTML using CGIDEV2 APIs and to the file VEHMST using the RPG opcodes. You must always keep the following points in mind when writing an RPG program for the Web:
  • Program VM is activated as a new instance every time a user POSTs a form to the HTTP server, with no regard to previous instances. It relies solely on the data posted via a form in the HTML document. Values of the variables in data definition section of the previous instance of the program are not available; therefore, you must record all the necessary data in the form fields for the program to use to produce the desired outcome. Also remember, you must treat all the HTML fields as characters and provide the required logic for conversion.
  • Unlike a traditional subfile, an HTML document has no built-in automatic page-up and page-down capability. You must use the HTML fields to write and read the end-record IDs, indicators, and required clues for the program to respond to user requests and format the Web pages.
  • CGI does not honor your iSeries library list. You must explicitly qualify the files you want to use, as well as open and close them as necessary.
  • An HTML member simply represents the collection of code and sections, and their relative positions within the source member are not important to formatting a page. How the Web page will look depends upon which HTML fields you updated and in what order you wrote the HTML sections in the RPG program.
  • To prevent the distraction of multiple programs and subroutines, this sample application uses a single program to do everything and repeats the code for each function. In commercial development, try to create single-function programs for improved performance and ease of maintenance.

Now You’re Ready to Write

By now, you have a good idea of how to write Web programs in RPG and may want to try writing your own application. CGIDEV2 may or may not give you everything you want, but it sure beats waiting for something simpler and more perfect to come along. I encourage you to get started with Web programming, or at least get acquainted with its fundamentals. If and when IBM provides a better Web programming tool that leverages your RPG expertise, you will be ready to take advantage of it with a very short learning curve. Better yet, why not write to IBM requesting new RPG opcodes to talk to the Web browser?