Welcome to the MapServer 5.

x Tutorial
Contents: Introduction Prerequisites MapServer Installation

Timeframe OS/Platform Issues Go to the Tutorial

About the Data Other Resources

Introduction This tutorial was designed to give new users a quick (relatively speaking) introduction to the concepts behind MapServer. It is arranged into four sections with each section having one or more examples and increasing in complexity. Users can jump to any section at any time although it is recommended that absolute beginners work on the first three sections sequentially. Section one focuses on basic MapServer configuration concepts such as layer and class ordering, using vector and raster data, projections and labeling. Section two provides examples on how to use HTML templates to create a simple interface for an interactive web mapping application. Section three introduces the use of HTML templates to provide a "query" interface. Finally, section four introduces some advanced user interface concepts. <top> Tutorial Timeframe While some users can go through this tutorial in one day, those who work on each example in detail can probably expect to finish in one week. <top> Tutorial Data The dataset used in this tutorial was taken from the U.S. Department of the Interior's National Atlas of the United States. You can visit their web site at http://www.nationalatlas.gov. The dataset was clipped to the upper great lakes region (Minnesota, Michigan, and Wisconsin) to reduce storage size. Additional raster images were added courtesy of the TerraSIP project at the University of Minnesota. When using this tutorial, you are encouraged to use your own dataset. Like MapServer itself, this tutorial is open and customizable to anyone. This was done in the hope that someone (or some folks) will help design and develop it further. <top> Before Using the Tutorial There are some prerequisites to using this tutorial: Users will need to have a web server installed and running on your computer. This web server has to have

support for common gateway interface (CGI) programs. Users should have a basic understanding of web servers and internet security. A poorly configured web server can easily be attacked by malicious people. At the very least your software installation will be corrupted and you'll lose hours of productivity, at worst your computer can be used to attack other computers on the internet. It is recommended that users of this tutorial read the "HOWTO for Getting Started With MapServer" before proceeding with this tutorial. To use this tutorial, users will need to have a web server and a MapServer CGI program (mapserv or mapserv.exe) installed in their systems. MapServer source code is available for download at http://mapserver.gis.umn.edu/dload.html. Documentations exist on how to compile and install MapServer--for UNIX users, please read the "MapServer UNIX Compilation and Installation HOWTO". Windows users can read either the "MapServer Win32 Compilation and Installation HOWTO" or the "MapServer Cygwin Compilation and Installation HOWTO". In addition, Windows users can also download precompiled binaries from http://mapserver.gis.umn.edu/win32binaries.html. <top> Windows, UNIX/Linux Issues This tutorial was created in Linux/UNIX but should work with minimal changes on Windows platform. The main differences are the paths in the map files. Windows users need to specify the drive letter of the hard disk where their tutorial files reside. Here's an example: A UNIX map file might include a parameter like this--SHAPEPATH "/data/projects/tutorial/data". In Windows, the same parameters might look like this--SHAPEPATH "C:/data/projects/tutorial/data" or this--SHAPEPATH "C:\data\projects\tutorial\data". Notice that either slash or backslash works in Windows. The usual backslash may work well for you if you want to make a distinction between virtual (as in URLs or web addresses) and local paths in your map file. However, if you plan to move your application to UNIX at some point, you'll have the tedious task of switching all backslashes to slashes. While we're on the subject of paths, keep in mind that paths in mapfiles are typically relative to the system's root directory--the slash ("/") in UNIX or some drive letter ("C:") in Windows. This is true except when specifically asked to enter a URL or when referencing a URL. When working with HTML template files, paths are relative to the web server's root directory--i.e., "/projects/tutorial35/" is relative to "http://terrasip.gis.umn.edu/". Please read http://www.alistapart.com/stories/slashforward/ for a few insights on URLs. Another issue is that UNIX executable files don't require a .EXE or .COM extensions. They do in Windows. If you are using Windows, append .exe to all instances of "/cgi-bin/mapserv" or "/cgi-bin/mapserv50" to make it "/cgi-bin/mapserv.exe" or "/cgi-bin/mapserv50.exe". <top> Other Resources Other documentations exist to give you better understanding of the many customizations MapServer offer.

Please visit the MapServer documentation page at http://mapserver.gis.umn.edu/doc.html. There you will find several HOWTO documents--from getting started to using MapScript, a scripting interface for MapServer. <top> Installation Instructions | Go to the tutorial | Download the tutorial Acknowledgements Created by Pericles S. Nacionales Last updated: 20071020

Example 1.1: Map with a Single Layer

MapServer can create an image and dump it to a local directory or send it directly to the requesting web browser, as in this example. You can view it without the need for an html page, just enter this URL: http://<insert hostname or IP address here>/cgi-bin/mapserv.exe? map=/ms4w/apps/tutorial/htdocs/example11.map&layer=states&mode=map (Remember to replace "<insert hostname or IP address here >" with your web server's name, e.g. "localhost", or its IP address, e.g. "127.0.0.1"). This URL can be broken into three parts: the first part, http://<insert hostname or IP address here>/cgi-bin/mapserv.exe?, calls the MapServer CGI program. If you invoke it as is you will get this familiar message: No query information to decode. QUERY_STRING is set,

but empty. The next three parts are what make up the query string. The query string contains the CGI parameters (variables and their values), with each parameter separated by an ampersand (&). So, looking at the query string, the first parameter "map" has a value "/ms4w/apps/tutorial/htdocs/example1-1.map"--this tells the MapServer CGI program (mapserv or mapserv.exe) what mapfile to process/parse. The next parameter "layer=states", tells mapserv.exe to "turn on" the states layer--recall that we named our layer object "states". The last parameter, "mode=map", tells mapserv.exe what to do with the output from the mapfile. In this case it tells mapserv.exe to dump the image directly to the web browser (the client), without first creating a temporary image on the server. The MapServer "mode" CGI variable takes values other than "map". For example if you use "mode=browse", MapServer will dump the image to a temporary directory on the server. The browse mode will not work now but we'll come back to it again later.

This is what the mapfile looks like (Example1-1.map):

The mapfile is MapServer's basic configuration mechanism. It is made up of "objects" and each object can have keywords or other objects. It has a hierarchical structure such that some objects fall under other objects... on top of this hierarchy is the MAP object, all other objects belong to it. This example shows a very straightforward heirarchy of objects. As you go through each example, the complexity of these hierarchical trees will increase. A few quick notes about mapfiles: we define each object in the mapfile with the object name and we close it with "END" and we precede comments with a pound (#) sign. Let's break "example1-1.map" down by objects. Its structure looks like this:
MAP |-LAYER |-CLASS |-STYLE

Let's look at the keywords (parameters) within the MAP object: MAP

Every mapfile starts with the MAP object--the entire mapfile is the MAP object. IMAGETYPE The keyword IMAGETYPE is used to define which image format the MapServer CGI program should use for output. In this case we are using indexed color PNG (similar to GIF). This could be GIF, if we compiled the GD library with GIF support, WBMP, or JPEG. We can also specify other output options (PDF, SWF, GeoTIFF) provided that we compiled support for them and specify them with the OUTPUTFORMAT object. The OUTPUTFORMAT goes beyond the scope of this tutorial but you can find out more about by reading through documentations in the MapServer web site. EXTENT This parameter specifies the output extent of our map--the bounding box of our initial map. The EXTENT values are given in this format: <Lower Left X> <Lower Left Y> <Upper Right X> <Upper Right Y>, with spaces separating each value. This needs to be in the same units as the data or, if specifying a different output projection, in the same units as the output projection. In this example our data is in geographic projection so the units are in decimal degrees. You can use the utility "ogrinfo", which is part of the GDAL/OGR library package, to get the extent of a particular shapefile (or other supported vector formats). Here is the command I used to get the extent for this example:
ogrinfo -al -so states_ugl.shp

This returned the following output:

INFO: Open of `states_ugl.shp' using driver `ESRI Shapefile' successful. Layer name: states_ugl Geometry: Polygon Feature Count: 204 Extent: (-97.238976, 41.619778) - (-82.122902, 49.385620) Layer SRS WKT: (unknown) AREA: Real (12.3) PERIMETER: Real (12.3) STATESP020: Real (11.0) STATE: String (20.0) STATE_FIPS: String (2.0) CLASS: String (5.0)

You can also use ArcView or other open source GIS packages--Quantum GIS, Thuban, etc. Feel free to change the values of EXTENT to get a better understanding of

how it changes your map. SIZE This is the size of the image (the map) that MapServer will generate, in pixels. So our map is 400 pixels wide by 300 pixels high. Again, change this to your heart's content and see how it affects your map. SHAPEPATH This is the path to your data layers. You can provide absolute paths (i.e. "/ms4w/apps/tutorial/data" or "C:/ms4w/apps/tutorial/data") or paths relative to your mapfile's location (in this example, you'd use "../data"). This path doesn't have to be web accessible, and probably shouldn't be unless you want anyone to download your raw data. It has nothing directly to do with the web so don't even think of URLs here--just make sure that the user running the web server (usually "nobody" or "apache" in the *nix world) can READ the data in the SHAPEPATH. IMAGECOLOR This is the background color of your map. The values are RGB values so 255 Red, 255 Green, and 255B which results in a white background. Go ahead and play with this values.

Now let's look at the LAYER object parameters: LAYER Marks the beginning of a LAYER within the MAP object. You can specify as many layers as you'd like although you are limited to 100, by default. To change this limit, you will have to edit the map.h header file (in the soure tree) and recompile MapServer. NAME This is the layer identifier. MapServer uses this name to toggle the layer on and off. It won't work in this example as we have the layer STATUS set to default. We will get back to this in later examples. DATA The name of the data (shapefile in this case). MapServer supports vector data formats other than ESRI's shapefile through the use of OGR library (part of the GDAL software package). Please visit the GDAL project web site at http://www.gdal.org/ and read http://www.gdal.org/ogr/index.html to know more about the different vector formats MapServer supports. In addition, Jeff McKenna and Tyler Mitchell have written a detailed guide to using vector data in MapServer. You can download this guide (PDF) from http://dl.maptools.org/dl/docs/mapserv/ .

TYPE What type of data is it? If it's a vector data, you can specify whether it is a POLYGON, LINE (you use LINE even if your data is technically a POLYLINE), or a POINT. You can also specify RASTER or ANNOTATION data. Here we want to display POLYGON. STATUS Layers are turned on or off based on their STATUS. DEFAULT is always on. ON or OFF works when the LAYER name is passed as part of the query string.

Let's look at the CLASS object parameters: CLASS Marks the beginning of a CLASS object within the LAYER object. You can specify as many classes within a layer although you are limited to 50 by default. You'll have to recompile MapServer to change this default value. NAME The descriptive identifier for this CLASS. LAYER objects can have multiple classes, just like MAP objects can have multiple layers. CLASS names are used by MapServer as labels for the legend so make sure to use an appropriate descriptive name when naming classes. We will talk about legends later in this tutorial.

And finally, let's look at the STYLE object parameters: STYLE Marks the beginning of the STYLE object. You can define multiple styles within a class--this is useful when you want to overlay a style over another. COLOR This is the fill color of the polygon. In case the TYPE is LINE, this is the line color. The values are in RGB format. OUTLINECOLOR This is the outline color of the polygons. The values are in RGB format. MapServer doesn't draw polygon outlines by default, so if you want to see polygon boundaries, you will want to define an OUTLINECOLOR.

This ends the first example in this tutorial. You are encouraged to change the values of the keywords in the mapfile. It will help you understand what

these keywords do.

Back to Section 1 | Back to the Sections Page | Proceed to Example 1.2

Installing the MapServer CGI Program and the Tutorial

Before you can actually go through the tutorial, you'll need to make sure you have your web server running and the MapServer CGI program (mapserv or mapserv.exe) installed in your "cgi-bin" directory. For those working in Microsoft Windows environment, it is recommended that you use the MapServer for Windows (MS4W) package available at http://dl.maptools.org/dl/ms4w/. This is a complete web mapping environment for Windows and includes the Apache web server, GDAL, Proj.4, MapServer, and all required libraries and useful utilities. To install the tutorial under MS4W, simply unzip the tutorial.zip archive to C:\ (or whichever drive MS4W is installed) and restart the web server. The tutorial files will be installed under \ms4w\apps\tutorial and an Apache configuration snippet will be installed as \ms4w\httpd.d\httpd_tutorial.conf. For those who are already familiar with web programming and would like an alternative MapServer binaries, Hobu provides Windows binaries at http://hobu.biz. You will need to install a separate web server and other utilities yourself. Another alternative is Frank Warmerdam's FWTools which includes MapServer and a host of other open source GIS utilities. You can also try to compile MapServer yourself. There are two versions of Win32 compilation how-to,one for MS Visual C++ compiler and the other one for compiling under the Cygwin environment. If you don't have a compiler or don't want to waste precious time compiling MapServer (and libraries), just download from one of the sites mentioned above. For Unix and Unix-like operating systems, you can search google for binary distribution for your particular platform.

If nothing turns up, you can always ask the MapServerUsers mailing list if such binaries exist. If all else fail, you'll have to compile MapServer and the associated libraries. The compilation and installation how-to for Unix is available at http://mapserver.gis.umn.edu/doc/unixinstall-howto.html. s Assuming you've got the MapServer CGI program, follow the steps below to install: 1a. If compiled in Unix, just copy the binary "mapserv" to your "cgi-bin" directory. On a locally compiled Apache server this will be on "/usr/local/apache/cgibin/" or /usr/local/apache2/cgi-bin". If your web server comes as part of your OS distribution, look for the "cgi-bin" directory or consult your OS's documentation. 1b. If you compiled on Win32 platform, copy the binary "mapserv.exe" to your "cgi-bin" or "scripts" directory. If you compiled the projection support for MapServer, copy the contents of "proj-4.4.7\nad" subdirectory to "C:\Proj\nad". You'll also need to copy all your supporting libraries to a directory that's part of your system PATH. This would typically be "C:\Windows\System" or "C:\Winnt\System32" but you can always add a different directory in your system (not user) path. If your web server is Apache, the "cgi-bin" directory is typically in "C:\Program Files\Apache Group\Apache\cgi-bin". If you are using Microsoft IIS, the "cgi-bin" directory is typically called "scripts" and is located in "C:\Inetpub\scripts". As with Unix, consult your web server's documentation for more information about "cgi-bin" and CGI programs. 1c. If you are using Win32 binaries downloaded from the MapServer web site, unzip the package to "C:\MapServer". From "C:\MapServer" copy "mapserv.exe" to your "cgi-bin" directory. In Apache this would typically be "C:\Program Files\Apache Group\Apache\cgi-bin" and in Microsoft IIS it is "C:\Inetpub\scripts". Copy the files from "C:\MapServer\lib" to C:\Windows\System or C:\Winnt\System32, whichever is appropriate for

your Windows version. (Alternatively, you can edit your system PATH to include "C:\MapServer\lib". In this way you don't have to copy the library files to your system directory.) Move "C:\MapServer\Proj" to "C:\Proj". This is required for projection support. As with Unix, consult your web server's documentation for more information about "cgi-bin" and CGI programs. 2. Test to make sure that your MapServer CGI program is working. With your web server running, open this URL on a web browser: http://localhost/cgibin/mapserv? (on *nix) or http://localhost/cgibin/mapserver.exe? or http://localhost/scripts/mapserver.exe? (on Windows). You should get the following message: No query information to decode. QUERY_STRING is set, but empty. This means that MapServer is working but you haven't supplied it with anything to process. If you've gotten this far and you've got a different message than above, the first thing to do is to check your error log and see what cause the message to appear. This typically means that you are missing your library files (dll's). Rectify the problem if you can, or check the MapServer FAQ. Failing that, check the MapServer Users mailing list archives, and if the archive isn't helpful, send an e-mail to the MapServer Users mailing list (you must be subscribed to send email to the list). 3. If you downloaded a copy of the tutorial, change the name of "mapserv" or "mapserv.exe" to "mapserv50" or "mapserv50.exe". The other option is to change each occurence of "mapserv50 "or "mapserv50.exe" back to "mapserv" or "mapserv.exe" in the example files--a very tedious process. This tells you that you can rename the MapServer CGI binary to whatever you want. It isn't recommended but if you run several versions of MapServer on the same machine, you really don't have a choice. If you downloaded the MapServer tutorial, the easiest

4.

way to install it is to unzip the archive to your web server's document root directory--that's the "htdocs" directory in Apache or "C:\Inetpub\wwwroot" in IIS. You will then have to edit your html files to change every occurence of "map=/data/projects/tutorial/example*.map" to "map=/your/htdocs/directory/tutorial/example*.map" (Example: for example1-1.html, you'd change the occurence of "map=/data/projects/tutorial/example11.map" to "map=C:/Inetpub/wwwroot/tutorial/example11.map") The "*" means change whatever character/s follow after "example". You can make this changes as you go through the examples. 5. You need to make a "tmp" directory and the easiest way is to create "tmp" directory within Apache's "htdocs" directory or IIS's "wwwroot" directory. You want to make sure that your web server user account (that's usually "nobody" in Unix and "IUSR_MACHINENAME" in IIS-MACHINENAME is the name of your computer). For security, You also want to make sure that users don't have execute permission in this directory. (In Unix and while working as "root", run the commands "chmod a+w /your/htdocs/directory/tmp" and "chmod a-x /your/htdocs/directory/tmp". In Windows, you can use IIS management console to change the permissions.) You will then need to change the value of every occurence of the IMAGEPATH mapfile keyword from "/data/tmp/" to "/your/htdocs/directory/tmp/" (or in Windows, "C:/your/htdocs/directory/tmp" or "C:/Inetpub/wwwroot/tmp").

If you followed the directions up to this point you can now begin your journey into the MapServer realm... Good luck! Go to the tutorial | Download the tutorial Acknowledgements Created by Pericles S. Nacionales

20031004 326