.. index::
   simple: CGI controls

.. _cgi_controls:

*****************************************************************************
 MapServer CGI Controls
*****************************************************************************


Variables
=========

.. index::
   pair: CGI; buffer

BUFFER [distance]
    A distance, in the same coordinate system as the map file, used in
    conjunction with MAPXY to create an new map extent.

.. index::
   pair: CGI; classgroup

CLASSGROUP [name]
    The name of a :ref:`LAYER` CLASSGROUP.  Set the :ref:`LAYER`
    `CLASSGROUP` to `name` for all layers that have at least one
    :ref:`CLASS` that is using the given CLASSGROUP `name`.

.. index::
   pair: CGI; context

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

.. index::
   pair: CGI; icon

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.

.. index::
   pair: CGI; id

ID [id-string]
    By default MapServer generates a uniq session id based on system time
    and process id. This parameter overwrites the default.

.. index::
   pair: CGI; img

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.

.. index::
   pair: CGI; imgbox

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.

.. index::
   pair: CGI; imgext

IMGEXT [minx] [miny] [maxx] [maxy]
    The spatial extent of the existing inline image, that is, the image the
    users can see in their browser.

.. index::
   pair: CGI; imgshape

IMGSHAPE [x1 y1 x2 y2 x3 y3 ...] | [WKT]
    An arbitrary polygon shape (specified using **image coordinates**)
    to be used for query purposes.

    The polygon is specified by listing its coordinates (multiple
    instances simply add parts to the shape so it is possible to
    construct a shape with holes) or by specifying the WKT (Well
    Known Text) representation.

    Used with the NQUERY mode.

.. index::
   pair: CGI; imgsize

IMGSIZE [cols] [rows]
    The size (in pixels) of the exiting inline image.

.. index::
   pair: CGI; imgxy

IMGXY [x] [y]
    Coordinates (in pixels) of a single mouse click. Used most often in
    conjunction with Java based front ends to the MapServer.

.. index::
   pair: CGI; layer

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.

.. index::
   pair: CGI; layers

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.

.. index::
   pair: CGI; map

MAP [filename]
    Path, relative to the CGI directory, of the map file to be used.

.. index::
   pair: CGI; mapext

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.

.. index::
   pair: CGI; mapshape

MAPSHAPE [x1 y1 x2 y2 x3 y3 ...] | [WKT]
    An arbitrary polygon shape (specified using **map coordinates**)
    to be used for query purposes.

    The polygon is specified by listing its coordinates (multiple
    instances simply add parts to the shape so it is possible to
    construct a shape with holes) or by specifying a WKT (Well Known
    Text) representation of the polygon.

    Used with the NQUERY mode.

.. index::
   pair: CGI; mapsize

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.

.. index::
   pair: CGI; mapxy

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.

.. index::
   pair: CGI; minx

.. index::
   pair: CGI; miny

.. index::
   pair: CGI; maxx

.. index::
   pair: CGI; maxy

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.

.. index::
   pair: CGI; mode

MODE [value]
    Mode of operation. The following options are supported:

    .. index::
       triple: CGI; mode; browse

    BROWSE
        Fully interactive interface where maps (and interactive pages) are
        created. This is the default mode.

    .. index::
       triple: CGI; mode; featurenquery

    FEATURENQUERY
        A spatial search that uses multiple features from SLAYER to query
        other layers.

    .. index::
       triple: CGI; mode; featurequery

    FEATUREQUERY
        A spatial search that uses one feature from SLAYER to query other
        layers.

    .. index::
       triple: CGI; mode; indexquery

    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.

    .. index::
       triple: CGI; mode; itemfeaturenquery

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

    .. index::
       triple: CGI; mode; itemfeaturequery

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

    .. index::
       triple: CGI; mode; itemnquery

    ITEMNQUERY
        A text search of attribute data is triggered using a QSTRING.
        Returns all matches.

    .. index::
       triple: CGI; mode; itemquery

    ITEMQUERY
        A text search of attribute data is triggered using a layer QSTRING.
        Returns 1st match.

    .. index::
       triple: CGI; mode; legend

    LEGEND
        The created legend is returned. Used within an <img ... > tag.

    .. index::
       triple: CGI; mode; legendicon

    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=/mapfiles/gmap75.map&MODE=legendicon&ICON=popplace,0

    .. index::
       triple: CGI; mode; map

    MAP
        The created map is returned. Used within an <img ... > tag.

    .. index::
       triple: CGI; mode; nquery

    NQUERY
        A spatial search (finds all) is triggered by a click in a map or by
        user-define selection box.

    .. index::
       triple: CGI; mode; query

    QUERY
        A spatial search (finds closest) is triggered by a click in a map.

    .. index::
       triple: CGI; mode; reference

    REFERENCE
        The created reference map is returned. Used within an <img ... > tag.

    .. index::
       triple: CGI; mode; scalebar

    SCALEBAR
        The created scalebar is returned. Used within an <img ... > tag.

    .. index::
       triple: CGI; mode; zoomin

    ZOOMIN
        Switch to mode BROWSE with ZOOMDIR=1

    .. index::
       triple: CGI; mode; zoomout

    ZOOMOUT
        Switch to mode BROWSE with ZOOMDIR=-1

    .. index::
       triple: CGI; mode; coordinate

    COORDINATE
        To be clarified.

    .. note::
       The previously available map-only query modes, e.g.
       ITEMQUERYMAP, are no longer supported.  The `QFORMAT` parameter
       is now used instead.

.. index::
   pair: CGI; qformat

QFORMAT [outputformat | mime/type] (optional)
    The `OUTPUTFORMAT` name or mime/type to be used to process a set
    of query results (corresponds to the :ref:`WEB` object's
    QUERYFORMAT parameter).
    The parameter is optional and used in conjunction with query
    `MODE`\s.  The default is text/html.

    Example (map output):

    ::

       ...&mode=nquery&qformat=png24&...

.. index::
   pair: CGI; qitem

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.

.. index::
   pair: CGI; qlayer

QLAYER [name]
    Query layer. The name of the layer to be queried as it appears in the map
    file.

.. index::
   pair: CGI; qstring

QSTRING [expression]
    Attribute queries: Query string passed to the query function.
    Since 5.0, qstring will have to be specified in the `VALIDATION`
    parameter of the `LAYER` for qstring queries to work
    (*qstring_validation_pattern* `LAYER`-level `METADATA` for
    Mapserver versions prior to 5.4).

.. index::
   pair: CGI; queryfile

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.

.. index::
   pair: CGI; ref

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.

.. index::
   pair: CGI; refxy

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.

.. index::
   pair: CGI; savequery

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.

.. index::
   pair: CGI; scaledenom

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.

.. index::
   pair: CGI; searchmap

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.

.. index::
   pair: CGI; shapeindex

SHAPEINDEX [index]
    Used for index queries (in conjunction with INDEXQUERY).

.. index::
   pair: CGI; slayer

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.

.. index::
   pair: CGI; tileindex

TILEINDEX [index]
    Used for index queries (in conjunction with INDEXQUERY), used with tiled
    shapefile layers.

.. index::
   pair: CGI; zoom

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.

.. index::
   pair: CGI; zoomdir

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

.. index::
   pair: CGI; zoomsize

ZOOMSIZE [number]
    Absolute magnitude of a zoom. Used with ZOOMDIR.

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


.. index::
   single: Change map file parameters

.. _cgi_mapfile_change_parameters:

Changing map file parameters via a form or a URL
================================================

Beginning 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
straightforward, 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.  `VALIDATION` can be used to control run-time substition
(see :ref:`RUNSUB`).  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 had 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.

.. index::
   single: Apache variables

Specifying the location of mapfiles using an Apache variable
============================================================

Apache variables can be used to specify the location of map files
(instead of exposing full mapfile paths to the outside world).

1. Set the variable (in this example `MY_MAPFILE`) in Apache's
   httpd.conf:

   ::

          SetEnv MY_MAPFILE "/opt/mapserver/map1/mymapfile.map"

2. Refer to the variable in the mapserver CGI URL:

   ::

          http://localhost/cgi-bin/mapserv?map=MY_MAPFILE&mode=...



.. index::
   single: ROSA-Applet controls

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