<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>MapServer Demonstration Installation Instructions</title>
</head>
<body bgcolor="#ffffff">
<table width="600" align="center">
<tr>
<td>
<h1>MapServer Demo Application<br>
Installation Instructions</h1>
<p>
Pericles S. Nacionales<br>
<a href="mailto:pnaciona@gis.umn.edu">pnaciona@gis.umn.edu<br>
</a>22 October, 2000</p>
<p>
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.</p>
<p>_______________________________________________________________________________</p>
<h2>Table of Contents</h2>
<h3><a href="#intro">1. Introduction</a></h3>
<h3><a href="#install">2. Installation</a></h3>
<ul>
<li><a href="#init">2.1 The demo_init.html file</a></li>
<li><a href="#map">2.2 The map file</a></li>
<li><a href="#template">2.3 The HTML template file</a></li>
</ul>
<h3><a href="#info">3. Further Information</a></h3>
<h3><a href="#ack">4. Acknowledgements</a></h3>
<p> </p>
<p>_______________________________________________________________________________</p>
<h3><a name="intro">1. Introduction</a></h3>
<p> 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.</p>
<p><b>Note on WINDOWS, UNIX, and URL paths usage:<br>
</b>
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.</p>
<h3> </h3>
<h3><a name="install">2. Installation</a></h3>
<p>If you have not already done so, decompress and untar the
ms_demo package into a web accessible directory (e.g. "/home/httpd/htdocs"
or "C:\Inetpub\wwwroot").</p>
<p>One of the two example commands below can do the trick for
you.</p>
<p><font face="Courier"> gunzip ms_demo.tar.gz | tar xvf -</font></p>
<p><font face="Courier"> tar xzvf ms_demo.tar.gz</font></p>
<p>(If you have Windows, WinZip or similar utilities can
decompress this package for you.)</p>
<p>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:<br>
/home/httpd/htdocs/ms_demo<br>
/data<br>
/graphics<br>
/perl<br>
/symbols</p>
<p>Or in Windows NT:<br>
C:\Inetpub\wwwroot\ms_demo<br>
\data<br>
\graphics<br>
\perl<br>
\symbols</p>
<p>To make this demo application work with your MapServer, you will need to edit
three files--the application initialization html file, the map file, and the
main html template file.</p>
<h4> </h4>
<h4><a name="init">2.1 The demo_init.html file</a></h4>
<p>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/maserv.exe". Look for the line:</p>
<p><font face="Courier"> <form method=GET action="/cgi-bin/mapserv"></font></p>
<p>and change as appropriate. Unix users typically don't have to
change this and Windows users will have to add the ".exe" extension.
Now, look for the line:</p>
<p><font face="Courier"> <input type="hidden" name="map"
value="ms_demo\demo.map"></font></p>
<p>and change it with the new path of your demo.map. In my
example, this should now look like:</p>
<p><font face="Courier"> <input type="hidden" name="map"
value="/home/httpd/htdocs/ms_demo/demo.map"></font></p>
<p>or in Windows NT,</p>
<p><font face="Courier"> <input type="hidden" name="map"
value="c:\Inetpub\wwwroot\ms_demo\demo.map"></font></p>
<p>That is all that needs to be done with this file.</p>
<p> </p>
<h4><a name="map">2.2 The Map File</a></h4>
<p>The map file is the MapServer application's configuration
file. This is where you specify paths to the template files and datasets. The
demonstration map file, demo.map, contains such paths which must be edited before the
application actually works.</p>
<p>Open demo.map in your favorite text editor. If you are using
Windows, this is where the slashes becomes problematic. Most of the paths
specified in the map file refers to the local subdirectories and not the URL paths.
There is, however, an instance where you need to specify a URL path and that is
with the keyword IMAGEURL. Look at the lines:</p>
<p><font face="Courier"> IMAGEPATH "/usr/local/apache/htdocs/tmp/"<br>
IMAGEURL "/tmp/"</font></p>
<p>In my example, I will have to replace the IMAGEPATH line with:</p>
<p><font face="Courier"> IMAGEPATH "/home/httpd/htdocs/tmp/"</font></p>
<p>If I don't have a "tmp" subdirectory in "/home/httpd/htdocs",
I will have to create it and make sure that web users have write permission to it.
Make sure to have the extra slash at the end of the path.</p>
<p>In Windows NT, I will have to change the IMAGEPATH line to:</p>
<p><font face="Courier"> IMAGEPATH "C:\Inetpub\wwwroot\tmp\"</font></p>
<p>If this "tmp" subdirectory doesn't exist in my web
server, I would have to create it and give web users permissions to write to it.
I will leave the IMAGEURL line as it is. IMAGEURL tells
mapserver where the mapserver-generated images are located, relative to the web
root directory.</p>
<p>These should be the only things you need to change in "demo.map".</p>
<h4> </h4>
<h4><a name="template">2.3 The HTML Template File</a></h4>
<p>The HTML template file is used by MapServer to provide an interface and as a
mechanism for delivering the generated graphics and other data. For the
purpose of this demo application, you only need to make sure that the line</p>
<p><font face="Courier"> <form
method=GET action="/cgi-bin/mapserv"></font></p>
<p>points to the proper CGI program. This is probably correct for UNIX but
will need to be modified to</p>
<p><font face="Courier"> <form
method=GET action="/cgi-bin/mapserv.exe"></font></p>
<p>for Windows.</p>
<p> </p>
<p>After completing all the changes to the three files above, you should now
have a working demo application. To test your application, open a web
browser and enter the URL to the "demo_init.html". This should
be something like this:</p>
<p> <font face="Courier"> </font><a href="http://your.host.name/ms_demo/demo_init.html"><font face="Courier">http://your.host.name/ms_demo/demo_init.html</font></a></p>
<p>where "your.host.name" should be replaced by your web server's
address.</p>
<p><Need to add common error messages here!></p>
<p> </p>
<h3><a name="info">3. Further Information</a></h3>
<p>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
<a href="http://terrasip.gis.umn.edu/projects/tutorial">http://terrasip.gis.umn.edu/projects/tutorial</a>.
For the Windows NT version of this tutorial, please visit <a href="http://128.101.73.80/projects/tutorial">http://128.101.73.80/projects/tutorial</a>.
Of course, documentation and other forms of support, including the mapserver-users
listserv archives can be found at http://mapserver.gis.umn.edu.</p>
<p> </p>
<h3><a name="ack">4. Acknowledgements</a></h3>
<p>This demonstration application was created, and is being provided, by Steve
Lime.</p>
<p> </p>
</td>
</tr>
</table>
</body>
</html>