In order to use the Map Server in a web/cgi-bin environment, a web server must be installed. Common web servers include Apache (on both Unix/Linux and Windows) and Internet Information Services - IIS (Windows only). To install a web server, follow its manufacturer's instructions.
The Map Server uses the Common Gateway Interface (CGI), which is supported by most of the web servers. It may also use the FastCGI version of the interface, which allows the map server executable to stay resident in memory and serve multiple map requests, instead of starting and exiting after each request.
In Unix/Linux environment, a bourne shell is used as a scripting language. In Windows environment, a perl scripting language also needs to be installed, so that the Map Server executable can be invoked by the web server. On Unix systems, a GlmScript bourne shell script that invokes the Map Sever is provided. On Windows, a GlmScript.pl perl script is provided.
If using Apache, cgi-bin scripts often reside in /usr/lib/cgi-bin directory. If using a web server other than Apache, see the manufacturers instructions on where cgi-bin scripts are located. A bourne shell script called GlmScript is provided with the Map Server and should be put in this directory.
The provided script must have execute permission for the user that the web server uses to invoke cgi-bin scripts. If a log file is used, it must also have write permissions for that user.
If using Apache, cgi-bin scripts often reside in the cgi-bin sub directory of the Apache installation directory. If using Internet Information Services (IIS), scripts reside in the Scripts sub directory of the Inetpub directory, which is created by IIS, and often resides on the C: drive.
On Windows, it is not possible to use a batch script to invoke the Map Server, because it is not secure, so a scripting language such as perl must be installed. A free implementation of perl can be downloaded at www.activeperl.com . Perl must be installed after the web server so that application bindings are properly installed.
To test if perl is working properly, create a file test.pl with the following contents:
print "If you are seeing this message, the script executed corretly";Then, from a command prompt on Windows or console session on Unix, execute the following command from the directory where test.pl resides:
perl test.plIf the message in the file is printed, then the script executed correctly.
In order to test if cgi-bin scripts work with the installed web server, create a file called test.pl with the following contents:
print "Content-Type: text/html\n\n"; print "If you are seeing this message,<br> the script executed correctly";Additionally, if using the Apache web server, the first line of the file must contain #! and the location of the perl executable.
Place the file into the directory where scripts for the web server reside, change its permissions accordingly, and enter the following URL in a web browser (where mywebserver.com is the location of the webserver):
http://mywebserver.com/cgi-bin/test.pl http://mywebserver.com/Scripts/test.plIf the message in the file is printed, then the script executed correctly.
The following components are required at run time and need to be copied into the web server's cgi-bin scripts directory:
The Map Server executable: GlmMap on Unix/Linux or GlmMap.exe on Windows.
The executable is located in the <glg_dir>/bin directory.
The cgi-script: GlmScript on Unix/Linux, GlmScript.pl on Windows or if perl setup is used.
The script is located in the <glg_dir>/map_server/cgi-bin directory.
The GIS data directory <glg_dir>/map_data.
The data directory may also be located outside of the cgi-bin scripts directory and pointed to by the GlmScript setup script.
Make sure GlmMap and GlmScript (or GlmMap.exe and GlmScript.pl) have execute permission.
To debug Map Server setup, create glm_err.log file in the cgi-bin scripts directory (or copy it from <glg_dir>/map_server/cgi-bin directory) and make it writable by the web server's cgi-bin scripts (www-data user and/or group in the default linux/apache configuration). This file will contain the Map Server's error messages. To debug Map Server setup, uncomment lines for extra logging and verbosity in the GlmScript script as described in the next chapter.
Note: The log file debugging output can be used only while debugging map server setup. It should be disabled in the production setup, as it will cause problems when multiple web clients cause simultaneous writing into the log file, resulting in CGI-bin HTTP errors.
The GlmScript is an easy-to-edit setup script that connects the web server with the Map Server executable. The script defines the location of the map server executable and its command line options, as well as the location of the GIS data. In addition to serving as a "glue" script, it also hides the details of the specific web setup from the web clients, presenting them with a logical interface to the map generation service.
The setup script starts with comments containing these setup instructions as well as sample HTTP requests for testing a map server setup using the sample GIS data. The rest of the setup script contains configuration variables that need to be changed according to the specific web server setup.
While a bourne shell called GlmScript is used in the Unix/Linux environment and a perl script called GlmScript.pl is used on Windows, the editing instructions are the same for both scripts:
Edit the MAP_SERVER_EXE variable in the script to point to the location of the Map Server executable.
Edit the DATASET variable in the script below to point to the location of the dataset's SDF file.
If an evaluation version of the Map Server is used, uncomment the GLG_EVAL_STRING variable setting and set the variable to the up-to-date evaluation code obtained from Generic Logic (www.genlogic.com). For the production or free non-commercial version of the Map Server, comment out GLG_EVAL_STRING setting.
To debug the Map Server setup, uncomment the command line near the end of the file for testing the map server installation and comment out the command line for the production setup, as instructed by comment next to the lines.
For the production setup, reverse it, commenting out the test line and enabling the production line.
FastCGI mode allows the Map Server executable to stay resident in memory and server multiple map requests compared with invoking a separate Map Server executable for each request in CGI mode and exiting when the request is processed. The FastCGI mode not only eliminates excessive executable start-up time, but also speeds up map generation requests by reusing data tiles in Map Server's cache.
In CGI mode, the content of the tile cache is lost when the Map Server executable exits. In the FastCGI mode, consecutive map requests reuse data tiles which have been already read by the previous map requests, saving on the data read time and speeding up map generation. The MAX CACHE SIZE parameter of the LIG file controls the cache size on per-layer basis.
To use the Map Server in the FastCGI environment, edit GlmScript (or GlmScript.pl on Windows) and replace -cgi option with -fcgi , then follow the FastCGI setup instructions for your web server.
To test the Map Server's setup, use the sample HTTP map requests listed in the comments section of the GlgScript file, for example on Unix/Linux:
http://my_web_server.com/cgi-bin/GlmScript?VERSION=1.3.0&or for the Windows-based setup:
http://my_web_server.com/cgi-bin/Scripts/GlmScript.pl?VERSION=1.3.0&Cut and paste one of the map requests into the address field of a web browser, change my_web_server.com to the real domain of your web server and press <Enter>. If everything was setup correctly, the requested map image will appear. Otherwise, an error message will indicate the origin of a problem. If logging is enabled, check the glm_error.log file for more information.
Try changing parameters of the map requests to see how they affect the generated map image.