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 dont have to remember prices. Second, job applicants cant 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 dont mean that Web browsers are designed with morons in mind. I mean that almost anybody can learn to point and click. Thats not a bad thing. If your applications use a Web browser, new employees are productive sooner and existing employees dont 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. Its rotten for heads-down data entry, for example. But if youre looking for a strategy to modernize applications, you should consider CGI. It works well for inquiry, simple data entry, and light maintenance applications. If youre 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 anythingdata, 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 youve done any Web surfing at all, youve 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, Cs 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 youd be able to use op codes like READ and WRITE. Hey, youd even be able to use the RPG cycle! Unfortunately, IBM didnt 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 youre 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 methodGET or POSTwas 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. Stones excellent articles RPG and CGI: Code WordDynamic! 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. Theres nothing elegant or excellent about the lowest common denominator. But the other definitionsprevalent, widespread, and even universalare 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 WordDynamic! 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.
LATEST COMMENTS
MC Press Online