This section provides some background information about the tutorial application and CGIs in general. It is divided into the following topics:
These topics may be helpful, but you do not need to read them to do the tutorial. If you do not want to read them, proceed to Part 1. Configuring a New Application.
The review tool reads HTML documents stored on your computer, and displays them in the Web browsers of users accessing the tool. Users access the tool using a unique key value that identifies them. The tool implements different levels of authority for different users based on their keys:
This organization lends itself well to an inheritance structure in which a user class with more authority inherits from one with less authority, and overrides certain member functions of its base classes. When a document is requested, the tool generates a view of the document based on the user's authority level:
The files being reviewed do not need to be stored in a publicly accessible location. Normally, HTML documents need to be stored in a web server directory for users to view them. The tool acts as an intermediary between your documents and web users. If you want, you can modify the tool later to provide access control to sensitive documents on your system.
You will need a web server on your workstation to use the tool. The VisualAge Help Server provided with VisualAge C++ is sufficient for the purpose of trying out the tutorial, but should not be used for deploying a production-level web application. If you are using Windows NT, you can use Microsoft Peer Web Services instead, although additional setup may be required.
How CGI Applications Communicate with a Web Browser
CGI applications are short-lived: each time a user accesses the application from a browser, the application is loaded as a separate process, reads input, provides output, and terminates.
A CGI application receives requests from a user's browser in one of two ways: through an environment variable, or through the standard input device. Requests from an environment variable are called GET requests; requests through standard input are called POST requests. Normally, all requests are GET requests except for those submitted through an HTML form (such as the form for adding reviewers' comments).
When a request is sent to the server, the REQUEST_METHOD environment variable is set. Each time the CGI is invoked, it reads the REQUEST_METHOD environment variable to find out how the request was made. If the request method was GET, the CGI then reads the QUERY_STRING environment variable for the text of the request. If the request method was POST, the CGI determines the number of characters to read by reading the CONTENT_LENGTH environment variable, then reads that number of bytes of input from the standard input device.
The CGI sends output back to the user's browser by writing to standard output. First, the CGI writes a header to indicate what type of content is being returned (for example, plain text, HTML text, or a JPEG image), then the actual output is written.
Running the CGI with a Web Server Other Than the VisualAge Help Server
In the tutorial, it is assumed that you are using the VisualAge Help Server as your web server. If you choose to use a different web server, you will need to change your project configuration to reflect the path the web server uses to run CGIs; wherever the VisualAge Help Server directory is referred to, change this directory to your web server's CGI directory. You will also need to do some additional setup work to get the CGI working properly with dynamic link libraries (Windows NT, OS/2) or shared libraries (AIX) as explained below.
Normally, a CGI does not have access to environment variables other than those set by the web server. This means that any dynamic link libraries (OS/2 or Windows) or shared libraries (AIX) that are normally located through an environment variable, such as PATH or LIBPATH, are not accessible to the CGI. To make the CGI run under most web servers you must therefore either link the run-time libraries statically to the CGI, or else copy the necessary library files into the same directory as the CGI.
Static linking during development of a CGI increases build times significantly, because VisualAge C++ must locate the necessary code in the run-time libraries and link it statically to your application every time you build. You should use dynamic linking as you develop the CGI, and ensure that the CGI has access to the necessary run-time library files, either by copying them into the CGI directory, or by using the VisualAge Help Server as your web server during development. This help server preserves environment variables such as the PATH environment variable within the CGI environment.
If you are running Windows NT and you want to use Microsoft Peer Web Services instead of the VisualAge Help Server, copy the following dynamic link libraries from the VisualAge directories into the directory your CGI will run from. The CGI usually runs from X:\inetpub\scripts, where X: is a writable drive on your system. The DLLs to copy are in either the \runtime or \bin directories under the main VisualAge C++ directory. They should be copied into the CGI directory, rather than into a bin or run-time directory under the CGI directory:
Determining Which Library Files Are Needed for Any CGI
On any platform, for any CGI, you can determine what library files need to be copied to the CGI directory by following these steps:
SET PATH=.
On AIX Bourne-Shell or Korn-Shell, type:
EXPORT PATH=.
You can now proceed to Part 1. Configuring a New Application
