Mapfile

Author

Steve Lime

Contact

steve.lime at dnr.state.mn.us

Author

Jeff McKenna

Contact

jmckenna at gatewaygeomatics.com

Last Updated

2021-03-27

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 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 LAYER. A layer is the combination of data plus styling. Data, in the form of attributes plus geometry, are given styling using CLASS and STYLE directives.

See also

An Introduction to MapServer for “An Introduction to the Mapfile”

Note

As you setup your server and mapfiles, it is strongly recommended to review the security steps for the MAP= call to the MapServer executable, by setting MS_MAP_PATTERN or MS_MAP_NO_PATH or hiding the MAP= parameter on public servers, as recommended in the document Limit Mapfile Access. All possible environment variables to secure your server are listed in Environment Variables.

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.

  • As of MapServer 7.0, Mapfiles are expected to be UTF-8 encoded. Non UTF-8 encoded mapfiles will need to be iconv’ed to UTF-8.

  • 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:

    • MAXCLASSES 250 (set in map.h)

    • MAXSTYLES 5 (set in map.h)

    • MAXSYMBOLS 64 (set in mapsymbol.h)

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

  • 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.

  • Comments are designated with a #. Since version 7.2 MapServer also supports single or multi-line C-style comments, as /* … */

  • 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.

  • 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.

  • Syntax coloring for .map files should be available for your favorite text editor (for example: Notepad++ steps)