MapServer Demo Application
Installation Instructions

Pericles S. Nacionales
pnaciona@gis.umn.edu
02 February, 2002

This document provides basic instructions on setting up the MapServer Demo Application. It assumes that the MapServer CGI program (e.g., mapserv or mapserv.exe) has been installed on the web server's cgi-bin directory.

_______________________________________________________________________________

1. Introduction

3. Further Information

4. Acknowledgements

_______________________________________________________________________________

1. Introduction

This document describes how to set the map and template file parameters so that it works with the installed mapserver CGI software and the demo dataset. It is assumed that the MapServer CGI program (mapserv or mapserv.exe) has been compiled and installed in the web server's cgi-bin directory, and that the web server is running. Although this document might seem targeted for the Unix users, special instructions for Windows users are provided.

Note on WINDOWS, UNIX, and URL paths usage:
When specifying paths or subdirectories, WINDOWS uses the backslash (\) while UNIX uses the forward slash (/). When writing a path as URL, always use the forward slash.

2. Installation

If you have not already done so, download the MapServer 3.5 demo package from http://mapserver.gis.umn.edu/dist/itasca3.5.tar.gz. Save or copy the package into a web accessible directory (e.g. "/home/httpd/htdocs" or "C:\Inetpub\wwwroot"). Decompress and untar the demo files.

One of the two example commands below can do the trick for you.

gunzip -c itasca3.5.tar.gz | tar xvf -

tar xzvf itasca3.5.tar.gz

(If you have Windows, WinZip or similar utilities can decompress this package for you.)

As an example, I will extract my files in "/home/httpd/htdocs" which is also my web root directory. If I use Windows NT and IIS 4.0, I would have extracted the files in "C:\Inetpub\wwwroot". This should decompress several files in a directory tree as below:
/home/httpd/htdocs/itasca
                                            /CVS
                                            /data
                                            /graphics
                                            /perl
                                            /symbols

Or in Windows NT:
C:\Inetpub\wwwroot\itasca
                                            \CVS
                                             \data
                                             \graphics
                                             \perl
                                             \symbols

If you are using Apache on Windows platform, you may unpack the demo package under your htdocs directory, typically C:\Program Files\Apache Group\Apache\htdocs.

To make this demo application work with your MapServer, you will need to edit three files--the application initialization html file (demo_init.html), the map file (demo.map), and the main html template file (demo.html).

2.1 The demo_init.html file

One of the three files, in this demo, that the user has to edit is the "demo_init.html" file. This is an html form that submits the initial parameters to the MapServer CGI. You need to make sure that the correct MapServer CGI program is being called. In UNIX, the program is typically called "mapserv" and is invoked from the cgi-bin directory as "/cgi-bin/mapserv". In Windows NT, it's typically called "mapserv.exe" and invoked as "/cgi-bin/mapserv.exe". Look for the line:

and change as appropriate. Unix users typically don't have to change this and Windows users will have to add the ".exe" extension.

1.) Now, look for the line:

and change it with the new path of your demo.map. In my example, this should now look like:

or on Windows,

2.) If you are on Windows, look for the line:

and change it so that it now looks like:

3.) Look for the line:

If you are on Unix, you probably don't have to change it but if you are using Windows, replace it with something like this:

If you don't have the "tmp" directory under C:\Inetpub\wwwroot\, make sure to create it and allow users to have write permission to it. Windows 95/98 users probably don't have to worry about the write permission. It's the Windows NT/2000 folks who need to do it. This is the directory where MapServer will write all the map outputs to.

4.) Lastly, look for the line:

This is how the local "imagepath" should appear on your URL, relative to you website's root ("http://my.web.root"). That is all that needs to be done with this file.

2.2 The Map File

The map file is the MapServer application's configuration file. This is where you normally specify paths to the template files and datasets. This also where all the data layers are listed and "classified". For this demo, we only need to make sure that our "WMS_ONLINERESOURCE" line points to our demo_init.html file. So, look for the line "WMS_ONLINERESOURCE "http://localhost.localdomain/mapserver_demos/itasca/demo_init.html"" and replace it with your own URL. Your URL will look like this: "http://my.web.server/itasca/demo_init.html" (replace "my.web.server" with your real address, or use "localhost").

2.3 The HTML Template File

If you made the proper changes to your demo_init.html and demo.map files. You don't have to change anything on demo.html. Please note, however, how the layer names on your demo.map file are used in the demo.html template. This is important when you start making changes to the layers.

At this point you are basically done. Make sure that your web server and the MapServer CGI program are running properly. Try typing "http://localhost/cgi-bin/mapserv or "http://localhost/cgi-bin/mapserv.exe". This should return the following message:
No query information to decode. QUERY_STRING is set, but empty.

If it does, your MapServer CGI program is running properly. You may now try your demo by typing demo_init.html's web address: http://localhost/itasca/demo_init.html. Congratulations you've installed the MapServer Demo app. Well, if you run into errors, check the messages below.

2.4 Common Error Messages

Pointing a browser at http://host/itasca/demo_init.html and slapping the 'initialize' button yields:

msLoadMap(): Unable to access file. (/itasca/demo.map)

You probably forgot to specify the complete path to the map file in demo_init.html. For example, change:

<input type="hidden" name="map" value="itasca/demo.map">

to:

<input type="hidden" name="map" value="/var/www/htdocs/itasca/demo.map">

loadSymbol(): GD library error

This can occur if you have a new version (>1.6(?)) of the GD library installed which doesn't support GIF images, And, you have a symbol file which contains a gif image. A workaround is to comment out all sections of the .map file which refer to the gif-containing symbol file, and the layers which refer to those symbols. For example:

#MARKERSET symbols/marker.sym
...
#LAYER
# NAME roads
# MAXSCALE 300000
# STATUS ON
# DATA ctyrdln3
# TYPE ANNOTATION
# LABELITEM "road_name"
# CLASS
#    COLOR 255 255 255
#    SYMBOL 'county_highway_shield' # <= the 'bad' line
#    LABEL
#      MINFEATURESIZE 40
#      MINDISTANCE 150
#      POSITION CC
#      SIZE TINY
#      COLOR 0 0 0
#    END
# END
#END # county road annotation

Alternatively just comment out the CLASS section rather than the whole layer.

msDrawReferenceMap(): GD library error. Unable to initialize image.

This is probably the same problem as the previous one: no GIF support. Check and see if the REFERENCE image is a .GIF. If it is comment out the REF code block. (This is a workaround, not a fix)

msLoadMap(): Premature End-of-File. Undefined symbol.

You have an unclosed object or class construct and the End Of File was encountered before mapserve found and END statement. Usually means an END statement was forgotten or inadvertantly commented out. (All object constructions must have an END. Study the LAYER construct in the previous section for an example).

Windows users, please read:
When running MapServer on Windows 2000 and IIS 5.0, clicking on the "Initialize" button the user gets prompted to save and download the mapserv (or mapserv.exe) file.

This is an IIS permission problem. Make sure that mapserv.exe had read and execute permission for the IUSR account. Also, using the Internet Services Manager, navigate to the "Scripts" (or cgi-bin) folder. Right click on the Scripts folder and select "Properties". Check to make sure that the "Execute Permissions" on the "Virtual Directory" tab is set to "Scripts and Executables". If not, change it. Restart the web service. (This requires administrative privileges to accomplish.)

2.5 Debugging Error Messages

How to interpret the error messages you may see. For an example we'll use:

loadString(): Incorrect data type. (105):(3)

The function "loadString" failed because it was fed an incorrect data type; It was expecting a string and recieved a number. The error occured in line# 3 of the .map file (the line count starts at 0).

The last set of brackets contain the line number:

(3) # line 3

the previous brackets contain the value mapserv choked on:

(105) # the line in the mapfile was: NAME 105d11

So mapserver parsed "NAME 105d11" as an integer when a
string was expected. In this example the solution is to make
sure you quote values when you need them interpreted as
characters rather than numbers:

NAME "105d11"

3. Further Information

The instructions provided here is meant to get your demo application working. By changing the template and map files, you should be able to get a good idea of the basic capabilities of MapServer. If you need further examples beyond what this demo gives, there is a MapServer tutorial available at http://terrasip.gis.umn.edu/projects/tutorial. For the Windows NT version of this tutorial, please visit http://128.101.73.80:82/projects/tutorial. Of course, documentation and other forms of support, including the mapserver-users listserv archives can be found at http://mapserver.gis.umn.edu.

4. Acknowledgements

This demonstration application was created, and is being provided, by Steve Lime, e-mail: steve.lime@dnr.state.mn.us.
The sections Common Error Messages and Debugging Error Messages were kindly provided by Matt Wilkie, e-mail: Matt.Wilkie@gov.yk.ca.

Last updated: 10/23/2000 14:12:01 -0500

[Homepage] [Download] [Documentation] [Support] [Gallery]

MapServer Demo Application Installation Instructions

Table of Contents

MapServer Demo Application
Installation Instructions