.. index::
   single: Mapfile

.. _mapfile:

*****************************************************************************
 Mapfile
*****************************************************************************

:Author: Steve Lime
:Contact: steve.lime at dnr.state.mn.us
:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com
:Author: Jean-François Doyon
:Contact: jdoyon at ccrs.nrcan.gc.ca

The Mapfile is the heart of MapServer.  It defines the relationships
between objects, points MapServer to where data are located and
defines how things are to be drawn.

The Mapfile consists of a :ref:`MAP` object, which has to start with
the word `MAP`.

There are some important concepts that you must understand before you
can reliably use mapfiles to configure MapServer.  First is the
concept of a :ref:`LAYER`.  A layer is the combination of data plus
styling.  Data, in the form of attributes plus geometry, are given
styling using :ref:`CLASS` and :ref:`STYLE` directives.

.. seealso::
    :ref:`introduction` for "An Introduction to the Mapfile"

.. toctree::
   :maxdepth: 1

   symbology/construction
   class
   cluster
   labelencoding
   expressions
   feature
   fontset
   grid
   include
   join
   label
   layer
   legend
   map
   outputformat
   projection
   querymap
   reference
   scalebar
   style
   symbol
   symbology/examples
   template
   union
   variable_sub
   web
   xml_mapfile


Notes
-----------------------------------------------------------------------------

* The Mapfile is NOT case-sensitive.

* The ``Mapfile is read from top to bottom by MapServer``; this means
  that LAYERs near the top of your Mapfile will be drawn before those
  near the bottom.  Therefore users commonly place background imagery
  and other background layer types near the top of their mapfile, and
  lines and points near the bottom of their mapfile.

* Strings containing non-alphanumeric characters or a MapServer
  keyword MUST be quoted. It is recommended to put ALL strings in
  double-quotes.

* For MapServer versions < 5, there was a default maximum of 200
  layers per mapfile (there is no layer limit with MapServer >= 5).
  This can be changed by editing the map.h file to change the value of
  MS_MAXLAYERS to the desired number and recompiling.  Here are other
  important default limits when using a MapServer version < 5:

  .. index::
     single: MAXCLASSES

  * MAXCLASSES 250 (set in map.h)

  .. index::
     single: MAXSTYLES

  * MAXSTYLES 5 (set in map.h)

  .. index::
     single: MAXSYMBOLS

  * MAXSYMBOLS 64 (set in mapsymbol.h)

  MapServer versions >= 5 have no limits for classes, styles, symbols,
  or layers.

.. index::
   single: File paths

* File paths may be given as absolute paths, or as paths relative to
  the location of the mapfile. In addition, data files may be
  specified relative to the SHAPEPATH.

* The mapfile has a hierarchical structure, with the MAP object being
  the "root". All other objects fall under this one.

.. index::
   single: Comments

* Comments are designated with a #.

* Attributes are named using the following syntax: [ATTRIBUTENAME].

  .. note::

    that the name of the attribute included between the square
    brackets *IS CASE SENSITIVE*. Generally ESRI generated shape data
    sets have their attributes (.dbf column names) all in upper-case
    for instance, and for PostGIS, *ALWAYS* use lower-case.

.. index::
   single: Regular expressions

* MapServer Regular Expressions are used through the operating
  system's C Library.  For information on how to use and write Regular
  Expressions on your system, you should read the documentation
  provided with your C Library.  On Linux, this is GLibC, and you can
  read "man 7 regex" ... This man page is also available on most
  UNIX's. Since these RegEx's are POSIX compliant, they should be the
  same on Windows as well, so windows users can try searching the web
  for "man 7 regex" since man pages are available all over the web.