Simpol Limited

If you already have a web server running on your desktop, then you need to consult the documentation for it to find out how to run CGI programs using it. If the server runs as a service, you will need to open the Services applet from the Control Panel and then modify the service entry for your web server to allow it to Allow service to interact with desktop. This is needed if you wish to be able to debug your CGI programs in the Simpol Professional IDE. Then set it up to execute programs that end in the file extension .smp as CGI programs. This may well need to know the location of the program used to run the applications and its name. The name of the program varies, depending on whether you are debugging or not. See the discussion of the Apache configuration below to learn about the various issues.

As mentioned earlier, the Apache web server is a freely downloadable product which is part of the offering from the Apache Software Foundation (http://www.apache.org). To get the latest release (always recommended) retrieve it from http://httpd.apache.org. There is also a very recent release included on the distribution CD of Simpol Professional in the Extras directory. Regardless of where you get it from, the first question you will have to answer is, "Which version?". Apache is available in three stable releases, versions 1.3.x, 2.0.x, and 2.2.x at the time of writing. Apache 2 is a reengineered version of the Apache 1.x web server with a major effort having been made to remove large pieces of the architecture from the web server kernel and place them into loadable modules. All of the following documentation will be based on the Apache 2 web server, but the configuration information is identical for both so there should be no problem regardless of which is installed. Downloading the web server is quite straightforward. Please use one of their mirrors closest to your location. If you can use the *.msi version, please download that, since it is considerably smaller than the *.exe version. Once you have downloaded it, run the package and accept all of the default values. The normal location is C:\Program Files\Apache Group\Apache2. One of the questions that you will be asked on a Windows NT, Windows 2000, Windows XP, Windows Vista, or Windows 7 operating system is whether to install as a service. We recommend that you answer this question with a no. The reason for this is that as of Windows Vista, services run in a separate Terminal Server instance and therefore cannot communicate with programs running on the desktop, which means that the debugging facility of the IDE would not work.

	Note
	If this is being installed on Vista or later, it is recommended to not install into the C:\Program Files directory. This directory is specially protected on Vista and trying to work with the configuration files of Apache within this directory may present considerable unnecessary problems.

Before we can run our program we also need to configure Apache. This section will discuss the changes that need to be made to the httpd.conf file.

Note

This section describes the minimal configuration required to develop and deploy web applications using SIMPOL and should not be considered to be a replacement for reading and understanding the documentation of the web server! Deploying a web server can be a complex operation depending upon the level of use it is expected to sustain. There is an entire branch of the industry that handles the deployment and maintenance of high-availability web servers for e-commerce sites. Please don't confuse basic configuration of a single web server with the knowledge required to deploy a web server that should be handling thousands of hits per second on a continuous basis.

After the web server has been successfully installed (no reboot of the computer is normally required), in the root directory of the Apache installation there will be a number of directories that concern us. These are:

The cgi-bin directory is where the programs normally reside. The conf directory is where the configuration files can be found. The htdocs directory is the default location for your web site (to use a different one is outside of the scope of this document, but see the section on virtual directories in the Apache documentation) and the logs directory is the place where the access and error logs are stored. The error log will be very important when trying to figure out why some program isn't working correctly. Often some useful information will show up in the log, such as an error message from SIMPOL.

Of the above, the error directory is not really covered here, but is worth a mention. If a page is not found on a web site, typically an error number 404, "File not found" is returned. That doesn't help the user all that much and it can be far nicer to provide a replacement page that offers the user access to the site's search engine, etc. or at least a link to the home page. Most web servers allow for this and Apache is no exception. Look into the documentation on how to create your own error pages for the errors that might be worth handling yourself rather than leaving them to the web server defaults.

To configure Apache for use in general, there are only a few changes that need to be made to the configuration files that are created during installation. The first thing that you may need to change should only be changed if you are running on Windows 9x. That is the following parameter:

# WinNT MPM
# ThreadsPerChild: constant number of worker threads in the server
# process
# MaxRequestsPerChild: maximum number of requests a server process
# serves
<IfModule mpm_winnt.c>
ThreadsPerChild 250
MaxRequestsPerChild  0
</IfModule>

The number of threads per child should be changed to 6. For local development you won't need many anyway but if you try and use the default the web server may fail to even start. The next item to change is the ServerAdmin parameter:

# ServerAdmin: Your address, where problems with the server should
# be e-mailed. This address appears on some server-generated pages,
# such as error documents. e.g. admin@your-domain.com
#
ServerAdmin johndoe@johndoe_world.com

Set the ServerAdmin parameter to your email address (or to whomever should be handling server problems). The next parameter of importance is the ServerName parameter. If you don't have a DNS name for your workstation, you can get around this problem by assigning a name and domain in the hosts file which can be found in the WINDOWS directory on Windows 9x machines and otherwise in the WINDOWS\SYSTEM32\DRIVERS\ETC directory on Windows XP and in the WINNT\SYSTEM32\DRIVERS\ETC directory on Windows NT 4 and Windows 2000. In the worst case you can also always use the name localhost to identify the machine. In our examples we will use localhost in the browser URLs so as to be unambiguous.

# ServerName gives the name and port that the server uses to
# identify itself. This can often be determined automatically, but
# we recommend you specify it explicitly to prevent problems during
# startup.
#
# If this is not set to valid DNS name for your host, server-
# generated redirections will not work.  See also the
# UseCanonicalName directive.
#
# If your host doesn't have a registered DNS name, enter its IP
# address here. You will have to access it by its address anyway,
# and this will make redirections work in a sensible way.
#
ServerName www.mytestdomain.com:80

The next parameter should need no adjustment at this stage. You may wish to experiment with it later. This parameter is the DocumentRoot parameter.

# DocumentRoot: The directory out of which you will serve your
# documents. By default, all requests are taken from this
# directory, but symbolic links and aliases may be used to point
# to other locations.
#
DocumentRoot "C:/Apache2/htdocs"

The ScriptAlias parameter for the /cgi-bin/ directory is one of the more important parameters for our project. That and the associated Directory parameter should be set up to look like the following:

# ScriptAlias: This controls which directories contain server
# scripts. ScriptAliases are essentially the same as Aliases,
# except that documents in the realname directory are treated as
# applications and run by the server when requested rather than as
# documents sent to the client. The same rules about trailing "/"
# apply to ScriptAlias directives as to Alias.
#
ScriptAlias /cgi-bin/ "C:/Apache2/cgi-bin/"

#
# "C:/Apache2/cgi-bin" should be changed to wherever your
# ScriptAliased CGI directory exists, if you have that configured.
#
<Directory "C:/Apache2/cgi-bin">
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>

No other parameters are required, but if you intend to run SIMPOL programs outside of the cgi-bin directory, then you will also need the AddHandler parameter. Now save the httpd.conf file. That completes the Apache portion of the configuration.

If you chose to install as a service (this does not work on Vista and later), to enable the ability to debug server program within the Simpol Professional IDE, it is necessary to configure the service to interact with the desktop. Open the Control Panel, Select Administrative Tools and from within that group select the Services applet. When it starts the window should look something like the following:

The Services applet window

Double-click on the Apache2 service and on the second tab of the resulting window, checkmark the box entitled Allow service to interact with desktop as shown below:

The Apache2 properties window

Click OK to close the window and store the changes.

	Note
	Although there is a similar little box in the dialog in Vista, it does not do what it did before. It merely allows the service to show dialogs that can be reacted to by the user, in a special mode of operation, but it does not allow the service access to the session in which the user code is running, making it useless for our purposes on Vista and later.

Once the configuration is complete, if you are running Apache as a service you will need to restart Apache. If you are using Apache 2, then in the Windows taskbar you will find an icon for the Apache control utility, which looks like a white circle containing a triangle on its point and a red feather off to the left upper side. Below is a picture to help you.

The Apache 2 control icon

Left-clicking on the icon will provide a menu with the options to Stop, Start, and Restart. Select the Restart option.

If you are using Apache 1.3.x then you will find menu items in the Windows Start menu for stopping and starting the web server. Stop the server and then start it again.

Alternatively, if you are running as a console application, you simply select the Start menu and navigate to the location that says Start Apache in Console. To close Apache later, just click the Close gadget.

At this point you should be ready to start writing, running, and debugging SIMPOL web server programs. Before you go any further however, you should open your browser and enter the URL http://localhost/. If you don't see a screen like the one below, you may have made an error in your configuration of the Apache web server. You will need to correct that before you can go on. Check the Apache documentation, and look at the log files. They may tell you what is wrong.

The Apache test home page

Once you ensure that the web server is working, you are ready to go on to the final part of this tutorial, actually running and debugging your web server programs.