Step by Step: RPG IV and Interactive Web Pages

March 31, 2004 Shannon O'Donnell

[The code for this article is available for download.]

I’m always surprised to talk to AS/400 programmers and discover how many shops still are not taking advantage of the Web. Most shops decide not to move from green-screen applications because they think the learning curve for Java is too steep or that learning CGI concepts and programming is too much work, and no one has offered any clear, simple examples. This article explains how easy it is to use RPG programming skills to build interactive Web pages.

THE CONCEPT

The basic concept of this article is to make the chore of learning how to use RPG to build and read dynamic, interactive web pages simple. Here’s what you will accomplish if you follow the steps in this article:

• Set up an HTTP server instance on your iSeries for interactive Web pages and configure it for Common Gateway Interface (CGI) services.

• Create a library in which to store your new CGI programs.

• Create a database in which to store data read from a CGI form.

• Identify the CGI APIs you need in order to write, read, and parse Web pages.

• Identify the HTML code required to push data from Web pages to the iSeries.

• Build an RPG IV program to write data to, and read data from, a Web page.

This sounds like a lot, and it is. However, the idea behind this article is to make things simple. To accomplish that, I am going to give you the steps required to make all this happen, without spending a whole lot of time explaining each piece. The way I look at it, if you are reading Four Hundred Guru, you already know how to look up anything you don’t understand. It is more important to have a simple example to follow, which you can implement immediately to see how it all works, than it is to explain the theory behind every little step.

Step 1: Create a New HTTP Server Instance

(Note that the following example assumes you are using OS/400 V5R2, although the same instructions should work on V5R1.)

1. From an AS/400 command line, enter the command WRKACTJOB SBS(QHTTPSVR).

2. Ensure that the HTTP server instance named ADMIN is running; if not, enter the following command, from a command line, and press Enter:

STRTCPSVR *HTTP HTTPSVR(*ADMIN)

3. From a Web browser on your PC, enter http://YouriSeriesIPAddress:2001. (YouriSeriesIPAddress is the TCP/IP address of your iSeries.)

4. Click IBM HTTP Server for iSeries.

5. Click Create New HTTP Server.

6. Click HTTP Server Powered by Apache. Then click Next.

7. Name your Web server Demo. Then click Next.

8. Click No, for basing your new server on an existing server. Then click Next.

9. Accept the defaults for the remaining panels. Then click Next until you get to the Finish button, and click that.

10. Click the Manage newly created Server link.

11. Click the Edit Configuration File link, in the left-hand pane, near the bottom of the page.

12. Scroll to the bottom of the configuration file, in the center of your screen, and type the following, after the last entry:

ScriptAlias /cgi-bin/  /QSYS.LIB/CGIDEMO.LIB
<Directory /QSYS.LIB/CGIDEMO.LIB>
     Options +ExecCGI 
     SetHandler cgi-script 
     order allow,deny 
     allow from all 
 </Directory>

13. Click the OK button to save your work.

Step 2: Create a Library for Storing CGI programs

From an OS/400 command line, enter the following command:

CRTLIB LIB(CGIDEMO) TEXT('CGI Demo Library')

Step 3: Create a Database for Storing Data Read from a CGI Form

Add two new source file members to your new library. One will be used for storing DDS source and the other for storing RPG IV source:

CRTSRCPF FILE(CGIDEMO/QDDSSRC) TEXT('DDS Source')

CRTSRCPF FILE(CGIDEMO/QRPGLESRC)  RCDLEN(112) TEXT('RPGIV Source')

Using SEU or CODE/400, or whatever source code editor you prefer, create a new physical file on your iSeries, with the following layout, and name it CUSTDB:

  A          R RCUST                          TEXT('CUSTOMER DB')    
  A              CUSTNO         6A         TEXT('CUSTOMER #')     
  A              CNAME         30A         TEXT('CUSTOMER NAME')  
  A          K CUSTNO                                           

Save the source in the QDDSSRC source member, in CGIDEMO, and then compile it:

CRTPF FILE(CGIDEMO/CUSTDB) SRCFILE(CGIDEMO/QDDSSRC)  SRCMBR(CUSTDB)

Step 4: Identify APIs Needed to Write, Read, and Parse Web Pages

You will use the following CGI APIs to manipulate Web pages using RPG. Please refer to IBM’s online API documentation for complete details on what each of these APIs can do.

• QtmhGetEnv: Get environment information.

• QtmhRdStin: Read from standard input (browser).

• QtmhCvtDb: Convert (parse) form data into physical file fields.

• QtmhWrStout: Write data to standard output (browser).

These four APIs are all you need to communicate with a user’s browser. Step 6 explains how they actually work in an RPG IV CGI program.

Step 5: Identify HTML Code Required to Push Data from Web Pages to iSeries

When you build HTML forms, either dynamically with an RPG IV CGI program or ahead of time using an HTML editor, such as DreamWeaver or Microsoft FrontPage, you will need to include a FORM line much like the following:

<FORM  id="FormName"  method="POST"  
   action=http://YouriSeriesIP:Port/cgi/YOURCGI.PGM>

The HTML syntax identifying the content after it as being part of a FORM is <FORM. That is, by inserting the <FORM> tags, your browser knows that when the user presses the Submit button, everything between those tags should be sent to the server identified on the “action” parameter. The id=FormName is simply the unique name you want to give to the HTML form on this page. The method=POST indicates that you want to use the “POST” method of submitting data to the host.

There are two ways to push HTML form data to a server. You can use either GET or POST. Both methods work equally well. I prefer POST, as the content of the HTML Form is not part of the URL, as it is with GET. This provides a minimal amount of security above using GET, in that it would be harder for a hacker to intercept and modify the HTML request via POST than using GET, simply because GET sends the entire request as part of the URL.

The action=http//YouriSeriesIP: tells the browser where to send the form data. Replace YouriSeriesIP with the actual IP address or URL of your iSeries.

The :Port is the port number you assigned to the HTTP server instance created in step 1. If you took all the defaults, this port number will be 80, in which case you can omit :Port from the parameter. If you used a port other than the default port of 80, you will need to include :Port to identify the correct port your server is listening on.

The /cgi/ alerts the server that the form data should be routed to the CGI program identified next.

The /YOURCGI.PGM is the name of the CGI program you will create in the next step.

In addition to the above HTML code, add the following code to the bottom of each of your HTML form documents:

<Input Type="Submit">

Also add the following:

</FORM>

The first adds a submit button to the form, which users will press to send data to the server. The second identifies the bottom of the form.

Step 6: Build an RPG Program to Write Data to, and Read Data from, a Web Page

Create a new RPG IV source file and name it CUSTCGI.

Use the RPG source code, CustCGI, to read from and write to a Web page.

TEST YOUR CGI PROGRAM

You are now ready to test the CGI program you just created.

First, ensure that the HTTP server instance you created is running, by using the WRKACTJOB command to view the QHTTPSVR subsystem. If the server instance named DEMO is not running, enter the following command, from a command line, and press Enter:

STRTCPSVR *HTTP HTTPSVR(DEMO)

From a Web browser, enter the following URL in the address bar, replacing YouriSeriesIP with the actual IP address or URL of your iSeries IP address, and enter the appropriate port number if you used anything other than the default port of 80 when you created the HTTP server instance:

http://YouriSeriesIP:Port/cgi-bin/CUSTCGI.PGM   

Now you should be presented with an HTML form that prompts you to enter a customer number. If you enter a customer number that is not in the CUSTDB database created earlier, you will be prompted to enter a name for this new customer and add it to the database. If the customer number already exists, you will be allowed to update the customer name.

DONE!

That’s it. You are now a full-fledged RPG IV CGI Web programmer. Actually, there are lots of things happening here and in the RPG program that I did cover. However, now that you have a working example to learn from, you should be able to look up online anything you do not fully understand and improve your skills. Have fun!

Editor’s Note: This article has been corrected since it was first published. The URL http://YouriSeriesIP:Port/cgi/CUSTCGI.PGM was changed to:

Guild Companies regrets the error. [Change made 4/1/04.]