Problem solve Get help with specific problems with your technologies, process and projects.

How does RPG talk to a browser?

Using your existing RPG skills and a little knowledge of HTML, you can be programming for the Web in no time.

You know that most applications are moving towards a browser interface. IBM tells you that the way to go is with...

Websphere Application Server, JSPs and Java Servlets. But there is an easier way to program for the Web -- use your existing RPG skills. With just a little knowledge of HTML, you can be programming for the Web in next to no time.

One of the advantages of ILE is that it made a whole lot of APIs available to RPG, including the HTTP APIs, which allows an RPG program to write and read HTML to and from a browser. These APIs are part of the implementation of Common Gateway Interface (CGI) on the iSeries.

If you have a masochistic tendency you can take to the manuals and inflict the pain of learning about the intricacies of using the CGI APIs. Alternatively, you can go to and download the CGI Development Toolkit (either RPG or COBOL). The toolkit is free and the entire source is provided along with a couple of sample applications and a few tutorials and guides on HTML, Javascript, CGI and other useful bits and pieces. Did I mention that it is free?

More Information

I will be writing about the CGI Development Toolkit in a following article, but in this article I want to try to explain what you have to do to get an RPG program to talk to a browser. Based on feedback at conferences, I am convinced that this is one of the major stumbling blocks that RPG programmers have about programming for the Web; they think it is a lot more complicated then it is. Actually, it is a lot (and I mean a lot) easier to write a program for a browser interface then it is for green screen. Yes, there are difficulties, new things to learn and new problems to deal with, but none are as difficult as many imagine.

What is an HTTP server?
Figure 1 shows a representation of an HTTP server. A browser sends an HTTP request to a port on a server. The HTTP server determines if the request is for a static document (in which case the document is returned to the browser) or if the request is for a CGI script (in which case the script is called and it uses APIs to sent data to the HTTP server which sends it to the browser). On the iSeries, an HTTP server is a number of jobs running in the subsystem QHTTPSVR.

Figure 1: An HTTP server

But how does the HTTP server know if the request is for a static document or a CGI script? The HTTP server is configured to direct requests based on the directory entered in the URL. For example, in the URL, it is the directory of cgiseminar that dictates whether it is a request for a static document or a CGI script.

How do you configure an HTTP server?
The HTTP server on iSeries is the industry standard Apache server. There used to be support for a traditional HTTP server, but it was discontinued with V5R2. To configure an HTTP server, you must first start the administration server. You can do this from the server's function in iSeries Navigator or you can enter the following command:


Once the administration server is running, you open your browser and enter this URL:


where iseriesservername is the name of your iSeries. When you log in, take the option to Create HTTP Server, as shown in Figure 2, and follow the wizard. There is extensive help available, but there are a couple of points worth noting: The name you give the wizard is the name that will be used for the corresponding server jobs in QHTTPSVR, and when testing, do not use the default port of 80 but use a port in the range 1024 to 2000. That means you will have to enter the port number after the server name (as with :2001 in the example above).

Figure 2: Creating a HTTP server

Once the basic server has been defined, you need to add definitions for the directories. Take the option to run the Add a Directory to the Web wizard. You must indicate if the directory is to serve static web pages or CGI programs, as shown in Figure 3.

Figure 3: Add a directory to the Web

When defining a CGI directory you specify the serving directory (i.e. the library containing the RPG programs to be called), as shown in Figure 4, and the alias (i.e. the directory name that is entered in the URL), as shown in Figure 5. In other words, when the alias directory is entered, the HTTP server determines that it must call a program in the serving directory (the name of the program is entered after the alias directory).

Figure 4: Specify the serving directory

Figure 5: Specify the alias

When you have added the directory, you can change the URL mapping to save the amount of information that has to be entered in the URL. For example, you don't have to enter the extension of .PGM on the program name, as shown in Figure 6.

Figure 6: URL mapping

You can have a look at any of the other features (such as security), but this is all you need to start with CGI programming.

Start the server
Now that you have defined the server, you need to start it. Start and stop buttons are available in the HTTP Administration window or you can enter the following commands to start and stop the server:

You will spend a lot of time stopping and starting servers during testing.

A CGI program
Now that the server is up and running, you need to write a program to ensure that it is working properly. Figure 7 shows the complete code for the program HELLOTHERE, which is used to generate the Web page shown in Figure 8. The binding directory CGIBNDDIR contains an entry for the service program QHTTPSVR/ QZHBCGI, which contains all of the CGI APIs. WriteWebData is a prototype for the QtmhWrStout API, which is called to write HTML text from the program to the HTTP server. QtmhWrStout expects three parameters: a character field containing the HTML to be written, the length of the characters string being passed (i.e. the characters in the first parameter) and the standard API error data structure. The program places the required HTML in a character field, passes it to the server by calling the API and the program ends. The most important thing about the HTML being passed is that it must start with

'Content-type: text/html' 

followed by two carriage return/linefeed characters (hex '15'). The rest of the data is standard HTML.

 H Debug DatEdit(*DMY/)  Option(*srcstmt : *nodebugio)          
 H DftActGrp(*No) BndDir('*LIBL/CGIBNDDIR') 
 D WriteWebData    Pr                  ExtProc('QtmhWrStout')   
 D   Data                              Like(WebData)            
 D   Length                      10I 0 Const                    
 D   Error                             Like(APIError)           
 D APIError        DS                  Qualified                
 D  BytesP                       10I 0 INZ(56)                  
 D  BytesA                       10I 0                          
 D  MsgID                         7                             
 D  Reserverd                     1                             
 D  Data                         40                                    
 D WebData         S           2048                                    
 D NewLine         C                   X'15'  
      WebData = 'Content-type: text/html' + NewLine + NewLine          
                   + '<html><head><title>' + NewLine                   
                   + 'Test RPG CGI' + NewLine                          
                   + '</title></head><body>' + NewLine                 
                   + 'Hello There! Well Done!! You have managed to '   
                   + 'connect to a working RPG CGI Program' + NewLine  
                   + '</body></html>' +  NewLine;                      
      WriteWebData(WebData : %Len(%Trim(WebData)) : APIError);         
      *INLR = *On;                                                     

Figure 7: A simple CGI program

You can run the program by entering this URL:


Figure 8: Output from a CGI program

The big difference
Unlike 5250 sessions, browsers are not conversational.

The conversation is "question and answer". The browser sends a request to the HTTP server (a job running in QHTTPSVR), the server processes the request, the server sends back a Web page and the conversation ends. The next request could go to a different server.

Up and running
It is as easy as that! The configuration of the Apache server is a one-time operation, and you can see how easy it is to "call" a program from the browser. The next step is to start coming to grips with the CGI Development Toolkit.

About the author: Paul Tuohy is CEO of ComCon, an iSeries consulting company. He is the author of Re-Engineering RPG Legacy Applications and is one of the quoted industry experts in the IBM Redbook "Who Knew You Could Do That With RPG IV?"


Dig Deeper on iSeries CL programming