Back in the Dark Ages, when I was a kid, all cash registers had numbers on them and no brains inside them. People had to know how to count money and make change. Nowadays, most cash registers have a sheet of plastic with words like hamburger and fries printed on it. As long as the cashier punches the right spots on the membrane, everything is copacetic.

A local businessman explained the reasons for this change in the cash register user interface. First, cashiers don’t have to remember prices. Second, job applicants can’t do math. The cash register manufacturers have had to develop what I call a “lowest common denominator” user interface: one that just about anybody should be able to use.

The Web browser is a sort of “lowest common denominator” user interface. I don’t mean that Web browsers are designed with morons in mind. I mean that almost anybody can learn to point and click. That’s not a bad thing. If your applications use a Web browser, new employees are productive sooner and existing employees don’t require as much training when you roll out a new program.

Making a server communicate with a Web browser is known as Common Gateway Interface (CGI) programming. CGI is not the ideal way for everybody to communicate with a computer. It’s rotten for heads-down data entry, for example. But if you’re looking for a strategy to modernize applications, you should consider CGI. It works well for inquiry, simple data entry, and light maintenance applications. If you’re a programmer, you should learn how CGI works and how to write CGI applications.

UNIX Fundamentals

To understand certain Internet concepts requires that you learn something about UNIX. CGI is one of those concepts.

First, the UNIX file system, like the PC filing system, is organized into directories. Directories can contain other directories and files. A file can contain anything—data, source code, object code, graphics, text, you name it. Second, UNIX predefines a group of files called standard input (stdin), standard output (stdout), and standard error (stderr). By default, stdin is the keyboard of an interactive session; stdout and stderr are assigned to the CRT. Programs can use these files without having to declare them. Third, UNIX was designed on ASCII machines, so ASCII is a presupposition of UNIX applications.

Do you see a problem? Instead of storing a directory structure of untyped files, the AS/400 stores strongly typed objects in libraries. RPG and COBOL, the most commonly used AS/400 application development languages, know nothing of stdin, stdout and stderr. The AS/400 runs on EBCDIC, not ASCII.

Nevertheless, the AS/400 can do CGI, provided the programmer is aware of such differences and accounts for them.

It Begins with a Request

The typical way to make an AS/400 program begin to run is by typing a number or command name on the command line of a green-screen menu and pressing the Enter key.

Under CGI, the user sends a URL to the server. The user can type the URL into the Location box of the Web browser or click on a link for an anchor tag (). The URL consists of three parts: protocol, subprotocol, and data source. In the case of CGI, the protocol is HTTP, and there is no subprotocol. The data source consists of an IP address or domain name followed by a file name and, optionally, any parameters to be passed to that file. The file name may be a simple text file containing HTML source code or an executable script or program, and it may include the names of directories that indicate the location of that file on the server. The following URL shows how CGI applications are typically executed:

http://www.phoaks.com/cgi-bin/get_page?QUERY_TYPE=poster;

The domain name of the URL is www.phoaks.com. The file to be executed is get_page, which is located in the cgi-bin directory. One parameter, QUERY_TYPE, with a value of poster, is passed to the executable file.

If you’ve done any Web surfing at all, you’ve probably seen the cgi-bin directory name many times. Web developers have adopted this as an unofficial standard directory in which to store CGI Web applications. Since the AS/400 is not a directory-based machine, you have to tell it to route requests for the cgi-bin directory to a library of your choosing. You do this with an Exec directive in the HTTP configuration file as follows:

Exec /cgi-bin/* /QSYS.LIB/MYCGI.LIB/*

The Exec directive says that requests to the cgi-bin directory are to be processed from the library called MYCGILIB. This is similar in principle to a file override that tells the system to use one file instead of another.

So much for the first problem. Now to get around the other ones. CGI programs read the predefined file stdin and write to the predefined file stdout. The languages commonly used on UNIX systems, such as C and Perl, already understand these files. For example, C’s printf and fwrite functions automatically send output to stdout.

It would be nice if you could code stdin and stdout as device names in an RPG program or if you could code an F spec for a combined file called stdio or something of the sort. Then you’d be able to use op codes like READ and WRITE. Hey, you’d even be able to use the RPG cycle! Unfortunately, IBM didn’t choose to add such features to the RPG compiler. Instead, they gave us the APIs shown in Figure 1.

These APIs are not difficult to use, but they do cause the programmer to generate some messy code. If you’re interested in learning how to use these APIs, see “Writing Your First RPG CGI Data Entry Program,” MC, January 1998.

The Easy Way

IBM has developed a library called CGIDEV for RPG and REXX programmers. CGIDEV contains template RPG and REXX source code from which you can develop CGI

programs. It also contains source code for commands, modules, service programs, and programs for developing CGI programs. You must be at V3R2 or above to use this library.

CGIDEV is well-designed. Here are some of its best features:

• CGIDEV lets you store HTML in a source member. This means you can use SEU to make changes to HTML source without having to recompile your CGI program. You can divide an HTML source member into named sections so that you can send portions of the member to the browser as needed. You can embed substitution variables in the source code. These are strings that are preceded and followed by percent symbols. At runtime, your programs can replace these variables with data values before sending the HTML to the browser.

• CGIDEV makes easy work of processing the data that comes back from the browser. CGIDEV can extract all input values regardless of which method—GET or POST—was used to format the data.

• CGIDEV includes debugging aids. CGI programs are harder to debug because they run under the HTTP server, not from a dumb terminal through an interactive subsystem. The template program includes logic to send an error message to the browser when something goes wrong and logs information about errors into a physical file.

To get the CGIDEV library, point your Web browser to the IBM code snippets Web site at www.as400.ibm.com/snippets and download the save file of the CGIDEVD library with a binary download. Create a save file called CGIDEVD on the AS/400 and FTP the downloaded file, in binary mode, to this save file. Then use the Restore Library (RSTLIB) command to restore this save file to library CGIDEV. At that point, read the instructions in source physical file README.

HTML on the Fly

Storing HTML in a source member is one way to go with CGI. The other way is to make a program generate HTML dynamically. I consider this to be the inferior method, but a lot of CGI programming on the Web is done dynamically.

For more about this method, see Bradley V. Stone’s excellent articles “RPG and CGI: Code Word—Dynamic!” and “RPG and HTML: Another Winning Team” in the April and May 1999 issues of MC respectively. Brad has developed subprocedures that take much of the grunt work out of RPG CGI programming. (Look for his upcoming book e- RPG: Building Web Applications with RPG, which is due out in the middle of February.)

Widespread and Ordinary

The word common has several meanings. It can mean “plain and ordinary” or even “course and unrefined.” CGI fits these definitions. There’s nothing elegant or excellent about the lowest common denominator. But the other definitions—“prevalent,” “widespread,” and even “universal”—are what CGI is all about. Learn to develop “lowest common denominator” programs and take them to the Web.

REFERENCES AND RELATED MATERIALS

• Cool Title About the AS/400 and Internet, Redbook (SG24-4815-01)
• e-RPG: Building Web Applications with RPG. Bradley V. Stone. Carlsbad, California: MC Publishing Co., 2000
• IBM code snippets Web site: www.as400.ibm.com/snippets
• “RPG and CGI: Code Word—Dynamic!” Bradley V. Stone, MC, April 1999
• “RPG and HTML: Another Winning Team,” Bradley V. Stone, MC, May 1999
• “Writing Your First RPG CGI Data Entry Program,” Richard Shaler, MC, January 1998

API Name Function

QtmhGetEnv Get environment variable QtmhRdStin Read stdin QtmhWrStout Write to stdout QtmhCvtDb Convert CGI input based on a database file format

Figure 1: RPG programmers must use APIs to get functions built into UNIX languages.