In the last issue, I started introducing you to the world of Common Gateway Interface (CGI) programming. CGI gives you the ability to communicate with a Web browser. My focus in this series of articles is to use RPG IV with CGI to allow you to create great applications with a browser-type interface.

To read data from the Web browser, either you call the QtmhGetEnv API to request the QUERY_STRING value or you read from standard input (stdin) by calling the QtmhRdStin API.

For CGI programs of any size, most CGI programmers use a CGI library to avoid programming the complicated details normally required by the CGI process. According to the Reader Poll in the last issue, most of you are not programming in CGI yet. But of those who are, the largest group is using a CGI add-on library (i.e., service program). The second largest group is using some of the cool third-party tools that generate Web-enabled programs. And virtually none of you are using the raw/native CGI APIs. This is good news! So this week, I want to show you how to write data back out to the Web browser. I will illustrate how to do some of that using the low-level CGI APIs and how to do it using one of the add-on libraries.

RPG for the Web

Using RPG to write data to the Web isn't all that tough. What is tough is learning all the ins and outs of this new environment. Let me start by giving you one of the most important clues about writing HTML to the Web: You have to tell the browser what you are going to send it before you actually send anything, or you could end up with an empty browser window.

Before sending data to the browser, you must send a CGI header. The term "header" is not unlike a report heading in that it appears first. This CGI header tells the browser to get ready to receive something. The "something" is identified in the header itself. You send the browser a CGI header followed by HTML. If you do not send the header, unpredictable results may occur.

To tell the browser that your RPG program is about to send it a bunch of HTML, you would send the following:

The so-called "content type" header tells the browser what to expect. It is to except, in this case, HTML in the form of plain text.

There are two other CGI headers: One allows you to tell the browser to open up an existing Web page, while the other allows you to tell the browser to display an error page.

CGI headers are terminated with a "line feed" symbol. This is required; otherwise, the header will not be recognized. In addition, a CGI header must be followed by an "empty line." In CGI terms, an "empty line" doesn't mean a blank line, but rather a second line feed character that immediately follows the first one.

In most languages, the symbol is used to represent a line feed character. So the content-type header would be represented as follows:

Note the two line feed symbols immediately after the CGI header. This indicates the end of the CGI header so that the browser knows there's no more header stuff coming. Unfortunately, RPG IV doesn't understand symbols the way C, C++, and Java do. In fact, you have to insert the EBCDIC equivalent of the ASCII line feed characters yourself. Originally, IBM misidentified the EBCDIC character that is translated into a line feed symbol in ASCII. Now, it is well-known that X'25' is the proper symbol to use for this purpose.

Once you've sent the content type header to the browser, you can start writing HTML. Use the QtmhWrStout API to write data to the browser. Include the CGI header unless you have a subprocedure wrapper that simplifies the call to the API.

The code in Figure 1 sends the content-type header and the two required line feed characters to the browser:

Figure 1: Write the CGI header.

The named constant LF (line feed) represents the in RPG IV (i.e., the X'25' character). The X'25' is translated to ASCII automatically.

Calling the QtmhWrStout API via the prototype STDOUT with the CALLP operation sends the CGI header to the browser. At this point, the browser is ready to receive subsequent stuff.

Unlike the QtmhRdStin API, the QtmhWrStout API may be called as many times as necessary to complete the HTML output process. So don't worry about trying to save the entire HTML in one large field before writing out to the browser.

Writing HTML to the Browser

Once you've sent the CGI header, you can start sending HTML. The question that you must answer now is "Where do I get the HTML?"

HTML is text, so it can be either stored in source members or IFS files, or embedded in the RPG IV calc specs or compile-time arrays. It's really up to you.

The structure of a Web page's HTML is important. HTML files are referred to as "HTML documents." HTML documents have a formal structure that includes a header and a body. The HTML header area contains the Web page's title and any scripts you're providing. The HTML body contains everything you see in the browser window.

I won't get into too much detail about HTML. There are, after all, thousands of books, as well as the www.w3c.org and www.htmlhelp.com Web sites, that can teach you everything about HTML you'd ever want to know.

The HTML source member named INDEX in QHTMLSRC is illustrated below.

To write this HTML out to the Web browser, create a simple read/write RPG IV program. The program will simply open the HTML source member, read a source line, and then write it out to the Web browser by calling the QtmhWrStout API. This technique is illustrated in Figure 2.

Figure 2: This RPG IV CGI program will read/write HTML.

Note that embedding data into the HTML is problematic. I used a simple technique here that compares each source line to the value . If it equals that value, I insert "dynamic HTML." That is HTML that I generate at run time. In this example, I insert the current time.

In the next issue, we will look at configuring the Apache Web server and using CGILIB to more easily merge data with HTML at run time.

Bob Cozzi is a programmer/consultant, writer/author, and software developer of the RPG xTools, a popular add-on subprocedure library for RPG IV. His book The Modern RPG Language has been the most widely used RPG programming book for nearly two decades. He, along with others, speaks at and runs the highly-popular RPG World conference for RPG programmers.