Personal tools
You are here: Home → Documentation → References
Navigation
 

CGI MapServer

Document Actions

Note: This is the print view with all the Reference Manual pages on one page. The paginated version is available here, if you prefer that.

Mapserv is the CGI portion for the MapServer package. It handles user input and directs image creation or query requests. The program accepts input via either "GET" or "POST" methods and can be used in an interactive manner or as an image engine.

1. Introduction

General notes regarding the MapServer CGI.

Notes

  • Variable names are not case sensitive.
  • In cases where multiple values are associated with a variable (eg. mapext), the values must be seperated by spaces (or their escaped equivalents for GET requests).
  • Variable contents are checked for appropriate data types and magnitude as they are loaded.
  • Any CGI Variable not listed below is simply stored and can be referenced within a template file.

Changes

From MapServer version 4.x to version 5.x

  • Modifying map parameters through a URL has changed to allow for chunks of a mapfile to be modified at once. The syntax has changed accordingly, so please see the Changing map file parameters via a form or a URL section.

From MapServer version 3.x to version 4.x

  • New way to perform attribute queries: No longer do you set a layer filter, but rather you pass a query string (and optionally an query item) to the query function. To do this 2 new CGI parameters were added to MapServer: QSTRING and QITEM.
  • SAVEMAP is switched off: The SAVEMAP functionality is considered insecure, since the saved files are accessible by everyone.
  • TEMPLATE has been removed, since the map_web_template syntax can be used to alter a template file. Simplifies security maintenance by only having to deal with this option in a single place. Note that the TEMPLATEPATTERN of the mapfile has to be used to enable this feature.

2. Controls

The mapserv CGI binary accepts various CGI variables as described below.

Variables

BUFFER [distance]
A distance, in the same coordinate system as the map file, used in conjunction with MAPXY to create an new map extent.
CONTEXT [filename]
Path to a context file. Path is relative to the map file to be used, or can also be a URL path (See the section "Map Context Support Through CGI" below for more details).
ICON [layername],[classindex]
Used in MODE=legendicon to generate a legend icon for a layer. The class index value is optional and defaults to 0.
ID [id-string]
By default MapServer generates a uniq session id based on system time and process id. This parameter overwrites the default.
IMG

The name associated with the inline map image used to record user clicks. What actually is passed are two variables, img.x and img.y.

For the CGI Applications this is an essential variable, see the examples for sample usage.

IMGBOX [x1] [y1] [x2] [y2]
Coordinates (in pixels) of a box drag in the image. Most often used in conjunction with Java based front ends to the MapServer.
IMGEXT [minx] [miny] [maxx] [maxy]
The spatial extent of the existing inline image, that is, the image the users can see in their browser.
IMGSHAPE [x1 y1 x2 y2 x3 y3 ...]

Shape given in image coordinates.

An arbitrary polygon shape to be used for query purposes. Multiple instances simply add parts to the shape so it is possible to construct a shape with holes. Used with modes NQUERY and NQUERYMAP.

IMGSIZE [cols] [rows]
The size (in pixels) of the exiting inline image.
IMGXY [x] [y]
Coordinates (in pixels) of a single mouse click. Used most often in conjunction with Java based front ends to the MapServer.
LAYER [name]
The name of a layer as it appears in the map file. Sending mapserv a layer name sets that layer's STATUS to ON.
LAYERS [name name ...]

The names of the layers to be turned on. Layer names must be seperated by spaces.

Version 4.4 and above: passing 'LAYERS=all' will automatically turn on all layers.

MAP [filename]
Path, relative to the CGI directory, of the map file to be used.
MAPEXT [minx] [miny] [maxx] [maxy] , MAPEXT (shape)

The spatial extent of the map to be created.

Can be set to shape as an alternative option. In this case mapextent is set to the extent of a selected shape. Used with queries.

MAPSIZE [cols] [rows]
The size (in pixels) of the image to be created. Useful for allowing users to change the resolution of the output map dynamically.
MAPSHAPE [x1 y1 x2 y2 x3 y3 ...]

Shape in map coordinates.

An arbitrary polygon shape to be used for query purposes. Multiple instances simply add parts to the shape so it is possible to construct a shape with holes. Used with modes NQUERY and NQUERYMAP.

MAPXY [x] [y] , MAPXY (shape)

A point, in the same coordinate system as the shapefiles, to be used in conjuction with a buffer or a scale to construct a map extent.

Can be set to shape as an alternative option. In this case mapextent is set to the extent of a selected shape. Used with queries.

MINX | MINY | MAXX | MAXY [number]
Minimum/Maximum x/y coordinate of the spatial extent for a new map/query. This set of parameters are the pieces of MAPEXT.
MODE [value]

Mode of operation. The following options are supported (note that all of the query modes also support map-only modes, e.g. ITEMQUERYMAP, which for brevity are not all listed):

BROWSE
Fully interactive interface where maps (and interactive pages) are created. This is the default mode.
QUERY
A spatial search (finds closest) is triggered by a click in a map.
NQUERY
A spatial search (finds all) is triggered by a click in a map or by user-define selection box.
ITEMQUERY
A text search of attribute data is triggered using a layer QSTRING. Returns 1st match.
ITEMNQUERY
A text search of attribute data is triggered using a QSTRING. Returns all matches.
FEATUREQUERY
A spatial search that uses one feature from SLAYER to query other layers.
FEATURENQUERY
A spatial search that uses multiple features from SLAYER to query other layers.
ITEMFEATUREQUERY
A text search of attribute data is triggered using a QSTRING. Returns first match. Layer to be searched is defined using slayer parameter. The results of this search are applied to other searchable layers (which can be limited using the QLAYER parameter).
ITEMFEATURENQUERY
A text search of attribute data is triggered using a QSTRING. Returns all matches. Layer to be searched is defined using slayer parameter. The results of this search are applied to other searchable layers (which can be limited using the QLAYER parameter).
LEGENDICON

A legend icon is returned. The ICON parameter must also be used to specify the layername and a class index. Class index value is optional and defaults to 0. For example:

mapserv.exe?map=/ms4w/apps/gmap/htdocs/gmap75.map&MODE=legendicon&ICON=popplace,0
MAP
The created map is returned. Used within an <img ... > tag.
REFERENCE
The created reference map is returned. Used within an <img ... > tag.
SCALEBAR
The created scalebar is returned. Used within an <img ... > tag.
LEGEND
The created legend is returned. Used within an <img ... > tag.
ZOOMIN
Switch to mode BROWSE with ZOOMDIR=1
ZOOMOUT
Switch to mode BROWSE with ZOOMDIR=-1
INDEXQUERY
Looks up a feature based on the values of SHAPEINDEX and TILEINDEX parameters. SHAPEINDEX is required, TILEINDEX is optional and is only used with tiled shapefile layers.
COORDINATE
To be clarified.
QLAYER [name]
Query layer. The name of the layer to be queried as it appears in the map file. If not specified then all layers are searched in turn.
QITEM [name] (optional)
The name of an attribute in a layer attribute table to query on. The parameter is optional and used in conjunction with the QSTRING for attribute queries.
QSTRING [expression]
Attribute queries: Query string passed to the query function.
QUERYFILE [filename]
Used with BROWSE or NQUERY mode. This option identifies a query file to load before any regular processing. In BROWSE mode this result in a query map being produced instead of a regular map. This is useful when you want to hilite a feature while still in a pan/zoom mode. In NQUERY mode you'd gain access to any of the templates used in normally presenting the query, so you have access to query maps AND attribute information. See the SAVEQUERY option.
REF

The name associated with the inline reference map image used to record user clicks. What actually is passed are two variables, ref.x and ref.y.

For the CGI Applications this is an essential variable when reference maps are used, see the examples for sample usage.

REFXY [x] [y]
Coordinates (in pixels) of a single mouse click in the reference image. Used in conjunction with Java based front ends to the MapServer.
SAVEQUERY
When used with any of the query modes this tells the MapServer to save the query results to a temporary file for use in subsequent operations (see QUERYFILE). Useful for making queries persistent.
SCALEDENOM [number]
Scale to create a new map at. Used with mapxy. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated SCALE parameter.
SCALE [number] - deprecated
Since MapServer 5.0 the proper parameter to use is SCALEDENOM instead. The deprecated SCALE is the scale to create a new map at. Used with mapxy. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
SEARCHMAP
It is possible to do pan/zoom interfaces using querymaps. In these cases you will likey want information about the contents of the new map rather than the previous map which is the normal way queries work. When searchmap is specified the new map is created and it's extent is used to query layers. Useful with NQUERY mode only.
SHAPEINDEX [index]
Used for index queries (in conjunction with INDEXQUERY).
SLAYER [name]
Select layer. The name of the layer to be used for any of the feature (i.e. staged) query modes. The select layer must be a polygon layer. The selection feature(s) are available for presentation to the user.
TILEINDEX [index]
Used for index queries (in conjunction with INDEXQUERY), used with tiled shapefile layers.
ZOOM [number]

Zoom scaling to apply to the creation of the new map. Values greater than 0 resulting in zooming in, 0 is a pan, and values less than zero are for zooming out. A value of 2 means "zoom in twice".

ZOOM can be used as a shortcut for the combination ZOOMDIR/ZOOMSIZE. The zoom is limited by the MINZOOM/MAXZOOM settings compiled into the MapServer (-25/25) by default.

ZOOMDIR [1 | 0 | -1]
Direction to zoom. See above.
ZOOMSIZE [number]

Absolute magnitude of a zoom. Used with ZOOMDIR.

ZOOMDIR is limited to MAXZOOM compiled into the MapServer (25 by default).

Changing map file parameters via a form or a URL

Begining with version 3.3 it is possible to change virtually any map file value from a form or a URL. The syntax for this is fairly straight forward, and depends on what version of MapServer you are using. One potentially very powerful use of this ability to change mapfile parameters through a URL involves changing class expressions on-the-fly. Try it out.

Using MapServer version >= 5

Previous versions of the MapServer CGI program allowed certain parameters to be changed via a URL using a cumbersome syntax such as map_layer_0_class_0_color=255+0+0 which changes the color in one classObj. So, in the past you have to change parameters one-at-a-time. Now you can pass chunks of mapfiles (with security restrictions) to the CGI interface. The map_object notation is still necessary to identify which object you want to modify but you can change multiple properties at one time. Note that you can use either a '_' or a '.' to seperate identifiers.

Example 1, changing a scalebar object:

...&map.scalebar=UNITS+MILES+COLOR+121+121+121+SIZE+300+2&...

Example 2, changing a presentation style:

...&map.layer[lakes].class[0].style[0]=SYMBOL+crosshatch+COLOR+151+51+151+SIZE+15&...

Example 3, creating a new feature

...&map_layer[3]=FEATURE+POINTS+500000+1000000+END+TEXT+'A+test+point'+END&...

Example 4, set multiple web object parameters

...&map_web=imagepath+/ms4w/tmp/ms_tmp/+imageurl+/ms_tmp/

Example 5, set the map size

...&map_size=800+400

The variable identifies an object uniquely (by name or index in the case of layerObj's and classObj's). The value is a snippet of a mapfile. You cannot create new objects other than inline features at this point.

Using MapServer version < 5

For MapServer version < 5, any value can be expressed using the hierarchy used in a map file. A map contains a layer, which contains a class, which contains a label, which has a color. This hierarchy is expressed as a sequence of MapServer keywords seperated by underscores. For example to change the color of a layer called "lakes" with only one class defined you would use a form variable named "map_lakes_class_color" and could assign it a color like "0 0 255". Layers can be referenced by index (i.e. map_layer_0...) or by name as shown above. Layer classes are referenced by index value (i.e. map_layer_0_class_2). If there is only 1 class for a layer then the index should be ommited. These variables must always begin with the sequence "map_". Values assigned must conform to the syntax of a map file.

It is also possible to define inline features using this mechanism. This is the only case where you can add on to the map file. You can edit/change layer parameters but you cannot create a new layer. With inline features you have to first create a feature and then build upon it, however, the layer the feature belongs to must exist. Here's a snippet from a GET request that adds a feature to a webuser layer:

. . . &map_webuser_feature=new&map_webuser_feature_points=12345.6789+12345.6789&map_webuser_feature_text=My+House!& . . .

The "map_webuser_feature=new" creates a new feature for the webuser layer. All subsequent calls to the feature object for that layer will modify the new feature. You can repeat the process to create additional features. This is really intended for very small (point, rectangle) amounts of data.

ROSA-Applet Controls

note: Active development and maintenance of the ROSA Applet has stopped

The ROSA Applet parameters were added to the CGI MapServer in version 3.6. This Java Applet provides a more intuitive user interface to MapServer. The MapTools site provides detailed information on the ROSA Applet.

The parameters can also be used by other interfaces/tools, if set to the right values. Please note that the two parameters have to be handed over to te CGI application in the order identified below.

INPUT_TYPE (auto_rect | auto_point)
The INPUT_TYPE parameter is needed to identify if the coordinates handed over to the mapserver have to be interpreted as rectangular or point data.
INPUT_COORD [minx,miny;maxx,maxy]
The ROSA-Applet always fills the pair of coordinates. In case of a point (input_type=auto_point) min and max coordinate are equal (Mapserver uses the min value).

3. Using the CGI Interface at the Commandline

The CGI interface can be tested at the commandline by using the "QUERY_STRING" switch, such as:

mapserv "QUERY_STRING=map=/ms4w/apps/gmap/htdocs/gmap75.map&mode=map"

To suppress the HTTP headers, you can use the "-nh" switch, such as:

mapserv -nh "QUERY_STRING=map=/ms4w/apps/gmap/htdocs/gmap75.map&mode=map"

To save the output into an image file, use the pipe command such as:

mapserv -nh "QUERY_STRING=map=/ms4w/apps/gmap/htdocs/gmap75.map&mode=map" > test.png

4. Map Context Support Through CGI

OGC Map context files contain layer information that can be used to request WMS layers. For more information on Map Context files see the <a href="ms_plone/docs/howto/mapcontext">How-To</a>. MapServer CGI allows you to load a map context through the use of a CONTEXT parameter, and you can point this parameter to a locally stored context file or a context file accessible through a URL.

Support for Local Map Context Files

There is a CGI parameter called CONTEXT that is used to specify a local context file. The user can then use MapServer to request a map using the following syntax:

http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT=
                     /path/to/contextfile.xml&LAYERS=layer_name1 layers_name2

Note All layers created from a context file have their status set to ON. To be able to display layers, the user needs to add the LAYERS argument in the URL.

Support for Context Files Accessed Through a URL

The syntax of using a web accessible context file would be similar to accessing a local context file:

http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT=
            http://URL/path/to/contextfile.xml&LAYERS=layers_name1 layer_name2

Due to security concerns loading a file from a URL is disabled by default. To enable this functionality, the user needs to set a CONFIG parameter called CGI_CONTEXT_URL in the default map file that will allow this functionality. Here is an example of a map file with the CONFIG parameter:

# Start of map file
NAME DEMO
STATUS ON
SIZE 400 300
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
IMAGECOLOR 255 255 255
IMAGETYPE png
CONFIG "CGI_CONTEXT_URL" "1"
...

Default Map File

To smoothly run a Mapserver CGI application with a Map Context, the application administrator needs to provide a default map file with at least the basic required parameters that will be used with the Context file. This default map file can contain as little information as the imagepath and imageurl or contain a list of layers. Information coming from the context (e.g.: layers, width, height, …) would either be appended or will replace values found in the map file.

Here is an example of a default map file containing the minimum required parameters:

NAME CGI-CONTEXT-DEMO
STATUS ON
SIZE 400 300
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
IMAGECOLOR 255 255 255
IMAGETYPE png
#
# Start of web interface definition
#
WEB
  MINSCALE 2000000
  MAXSCALE 50000000
#
# On Windows systems, /tmp and /tmp/ms_tmp/ should be created at the root 
# of the drive where the .MAP file resides.
#
  IMAGEPATH "/ms4w/tmp/ms_tmp/" 
  IMAGEURL "/ms_tmp/"
END
END # Map File
Powered by Plone