Configuring the Apache Web server isn't too difficult as of V5R1 and later. Previously, it was, shall we say, "challenging."

To configure a new Apache server instance, you need to start a preinstalled "administrator" instance of the Web server. IBM ships this with your iSeries as HTTPSVR(*ADMIN) on the STRTCPSVR command. To start the administrator's instance, issue the following CL command:

After a few seconds, the *ADMIN instance will be visible via the WRKACTJOB's command. To view the instance along with any other running Web servers, run the following CL command:

The job named ADMIN is the *ADMIN instance of the Web server. The *ADMIN instance waits on port 2001 and routes you to the IBM-supplied Web pages that allow you to configure and manage other instances of the Web server.

To load up the administrator instance, type the following into a browser: http://xxxxx:2001.

Here, xxxxx is either the IP address of the iSeries running your Web server or the equivalent domain name.

Follow the relatively easy-to-use prompts to create a new Web server. If you already have a Web server configured, use the prompts to manage that Web server.

Since the focus of this series of articles has been CGI RPG IV programming, I am only interested in the configuration statements that relate to CGI programming. (Click here for more information on the entire set of Apache configuration directives. I would bookmark that page as it proves invaluable during the initial configuration period.)

The first thing you need in your Web server configuration file is a Listen statement. For example:

This tells the Web server what IP address this configuration applies to. You can optionally add a port number, as follows:

The port 1024 is now assigned to this configuration. You can use just about any port you'd like, but some are reserved. For example, port 80 is used for the standard configuration (the one that you run your Web site from), and ports 2001 and 2010 are used for the administrator's instance.

To get CGI running for this instance, you need to add the ExecCGI statement, as follows:

Many Apache directives use multiple lines to specify their values. In the example above, the MYCGI directory has CGI enabled and allows users to use the content of that directory. However, in the old CERN Web server, to enable CGI program mapping, you would code the following:

Then, to enable/run the CGI program, the following statement would be required:

The following are the equivalent statements in the Apache configuration:

In the examples above, the AS/400 library named MYCGI is set up to allow CGI programs to be run from it.

CGI Programming, Part 3: Merging Data with HTML

In my last article, we talked about sending HTML to the browser. I also showed you how to use a very primitive scan/replace routine to merge data with the HTML. This week, I want to illustrate how you can use substitution tokens to easily merge data with HTML.

HTML is a static piece of text. It does not change unless you write a JavaScript to dynamically modify what is displayed in the browser. You can use other languages, such as Java, and Microsoft's Internet Explorer allows you to embed programs in the browser window (which is the source of most IE-based viruses, I might add).

But other that than, you need to insert the data in your browser using a CGI language. Since this is the RPG Developer newsletter, I won't show you how to do that with Net.Data or Java; instead, I'll illustrate how to merge your live data using HTML and good old RPG IV.

The term "token" has been around for decades, and it is used today in computer programming to represent a symbol found on a statement. It is a generic name for a "thing" on a source line.

For example, how many tokens are in the following RPG IV statement?

There are either seven or eight, depending on how you count. If you include the opcode, there are eight. Each field is a token, as is each math operator, and the equals sign (=) is also a token.

To insert data in HTML, we have to come up with a scheme to substitute a token for some useful data; otherwise, we would have a difficult time to say the least.

We have a couple of models to steal ideas from; one is the old System/36 OCL. It used ?1? tokens to represent parameter values. Another is the System/38 messaging system, still used today on iSeries and i5 platforms. It uses &1 tokens to represent substitution values in the form of message data.

From these two models, we learn that we need some type of relatively unique token capability along with an ability to uniquely identify each token. Numbering tokens is probably out of the question, as HTML pages can have huge amounts of data added to them, far beyond the ability to manage numeric tokens. So that leaves us with alphanumeric tokens. Tokens also need some type of symbol that makes them stand out from the rest of the text.

Mel Rothman of IBM Rochester (now retired) implemented a substitution token schema for HTML when he was building the CGIDEV2 library several years ago. This schema has since been used in the contemporary CGILIB service program and continues to be popular with the CGIDEV2 library.

The Rothman schema is based on an alphanumeric token ID surrounded by unique symbols that identify each token. The symbols he chose are illustrated below:

To begin a token ID name: /%

To end a token ID name: %/

To specify a substitution token in your HTML, you specify /%, followed by the token name, followed by %/. For example:

The token ID is /%CMPNAME%/, and it is your job to replace that token with some real data, presumably the real company name.

Suppose the company name you wanted to replace it with is Rocketplane, Ltd. The resulting HTML would look like this:

The CGILIB service program (as well as the CGIDEV2 library) makes this kind of substitution possible by handling all the scan/replace functionality for you. You simply load the HTML source code into an internal work buffer and then set each substitution token's value using an easy-to-call subprocedure. For example:

To make things even more dynamic, you might read a record from a database file and then call cgiSetVar(), as follows:

Note the use of the %TRIMR() built-in function to avoid sending excess blanks to the browser. While the browser would delete them anyway, line traffic is increased, so %TRIMR is used to avoid sending excess blanks.

The HTML needed to display a full customer record might appear in the HTML editor, such as Microsoft FrontPage 2003, as follows:

Figure 1: Here's your HTML layout view. (Click images to enlarge.)

The source for this HTML table would be as follows:

Figure 2: This HTML table source shows the substitution tokens.

To prepare the HTML by merging the data from a database with the HTML, you could use the following RPG IV code:

Figure 3: This RPG IV source uses CGILIB to merge data with HTML.

Once the above RPG IV code runs, the HTML will be ready to send to the browser. It will appear in the browser (once cgiWrtSection() is called) as illustrated in Figure 4.

Figure 4: And now, here's your HTML page after substitution variable assignment using CGILIB.

Merging live data with HTML does not need to be rocket science. Simple helper tools such as CGIDEV2 and CGILIB can make writing with CGI a pleasure.

Now get back to work.

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.