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

1. MapScript API Reference

Document Actions
Up one level

Mapscript API Reference, MapServer version 4.10

Author: Sean Gillies
Contact: sgillies@frii.com
Revision: 1.119
Date: 2006-09-05

1   Introduction

This is language agnostic documentation for the mapscript interface to MapServer generated by SWIG. This document is intended for developers and to serve as a reference for writers of more extensive, language specific documentation in DocBook format for the MDP.

1.1   Appendices

Language-specific extensions are described in the following appendices

Python Appendix [Text, HTML]

1.2   Documentation Elements

Classes will be documented in alphabetical order in the manner outlined below. Attributes and methods will be formatted as definition lists with the attribute or method as item, the type or return type as classifier, and a concise description. To make the document as agnostic as possible, we refer to the following types: int, float, and string. There are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments.

We will use the SWIG term immutable to indicate that an attribute's value is read-only.

1.3   fooObj

A paragraph or two about class fooObj.

1.3.1   fooObj Attributes
attribute : type [access]
Concise description of the attribute.

Attribute name are completely lower case. Multiple words are packed together like outlinecolor.

Note that because of the way that mapscript is generated many confusing, meaningless, and even dangerous attributes are creeping into objects. See outputFormatObj.refcount for example. Until we get a grip on the structure members we are exposing to SWIG this problem will continue to grow.

1.3.2   fooObj Methods
method(type mandatory_parameter [, type optional_parameter=default]) : type
Description of the method including elaboration on the method arguments, the method's actions, and returned values. Optional parameters and their default values are enclosed in brackets.

Class method names are camel case with a leading lower case character like getExpressionString.

1.4   Additional Documentation

There's no point in duplicating the MapServer Mapfile Reference, which remains the primary reference for mapscript class attributes.

2   Mapscript Variables

2.1   Version

Name Type Value
MS_VERSION character 4.8

2.2   Logical Control - Boolean Values

Name Type Value
MS_TRUE integer 1
MS_ON integer 1
MS_YES integer 1
MS_FALSE integer 0
MS_OFF integer 0
MS_NO integer 0

2.3   Logical Control - Status Values

Name Type Value
MS_DEFAULT integer 2
MS_EMBED integer 3
MS_DELETE integer 4

2.4   Map Units

Name Type Value
MS_DD integer  
MS_FEET integer  
MS_INCHES integer  
MS_METERS integer  
MS_MILES integer  
MS_PIXELS integer  

2.5   Layer Types

Name Type Value
MS_LAYER_POINT integer  
MS_LAYER_LINE integer  
MS_LAYER_POLYGON integer  
MS_LAYER_RASTER integer  
MS_LAYER_ANNOTATION integer  
MS_LAYER_QUERY integer  
MS_LAYER_CIRCLE integer  
MS_LAYER_TILEINDEX integer  

2.6   Font Types

Name Type Value
MS_TRUETYPE integer  
MS_BITMAP integer  

2.7   Label Positions

Name Type Value
MS_UL integer  
MS_LL integer  
MS_UR integer  
MS_LR integer  
MS_CL integer  
MS_CR integer  
MS_UC integer  
MS_LC integer  
MS_CC integer  
MS_AUTO integer  

2.8   Label Size (Bitmap only)

Name Type Value
MS_TINY integer  
MS_SMALL integer  
MS_MEDIUM integer  
MS_LARGE integer  
MS_GIANT integer  

2.9   Shape Types

Name Type Value
MS_SHAPE_POINT integer  
MS_SHAPE_LINE integer  
MS_SHAPE_POLYGON integer  
MS_SHAPE_NULL integer  

2.10   Measured Shape Types

Name Type Value
MS_SHP_POINTM integer 21
MS_SHP_ARCM integer 23
MS_SHP_POLYGONM integer 25
MS_SHP_MULTIPOINTM integer 28

2.11   Shapefile Types

Name Type Value
MS_SHAPEFILE_POINT integer 1
MS_SHAPEFILE_ARC integer 3
MS_SHAPEFILE_POLYGON integer 5
MS_SHAPEFILE_MULTIPOINT integer 8

2.12   Query Types

Name Type Value
MS_SINGLE integer 0
MS_MULTIPLE integer 1

2.13   File Types

Name Type Value
MS_FILE_MAP integer  
MS_FILE_SYMBOL integer  

2.14   Querymap Styles

Name Type Value
MS_NORMAL integer  
MS_HILITE integer  
MS_SELECTED integer  

2.15   Connection Types

Name Type Value
MS_INLINE integer  
MS_SHAPEFILE integer  
MS_TILED_SHAPEFILE integer  
MS_SDE integer  
MS_OGR integer  
MS_POSTGIS integer  
MS_WMS integer  
MS_ORACLESPATIAL integer  
MS_WFS integer  
MS_GRATICULE integer  
MS_MYGIS integer  
MS_RASTER integer  

2.16   DB Connection Types

Name Type Value
MS_DB_XBASE integer  
MS_DB_CSV integer  
MS_DB_MYSQL integer  
MS_DB_ORACLE integer  
MS_DB_POSTGRES integer  

2.17   Join Types

Name Type Value
MS_JOIN_ONE_TO_ONE integer  
MS_JOIN_ONE_TO_MANY integer  

2.18   Line Join Types (for rendering)

Name Type Value
MS_CJC_NONE integer  
MS_CJC_BEVEL integer  
MS_CJC_BUTT integer  
MS_CJC_MITER integer  
MS_CJC_ROUND integer  
MS_CJC_SQUARE integer  
MS_CJC_TRIANGLE integer  

2.19   Image Types

Name Type Value
GD/GIF integer  
GD/PNG integer  
GD/PNG24 integer  
GD/JPEG integer  
GD/WBMP integer  
swf integer  
imagemap integer  
pdf integer  
GDAL/GTiff integer  

2.20   Image Modes

Name Type Value
MS_IMAGEMODE_PC256 integer  
MS_IMAGEMODE_RGB integer  
MS_IMAGEMODE_RGBA integer  
MS_IMAGEMODE_INT16 integer  
MS_IMAGEMODE_FLOAT32 integer  
MS_IMAGEMODE_BYTE integer  
MS_IMAGEMODE_NULL integer  
MS_NOOVERRIDE integer  
MS_GD_ALPHA integer 1000

2.21   Symbol Types

Name Type Value
MS_SYMBOL_SIMPLE integer  
MS_SYMBOL_VECTOR integer  
MS_SYMBOL_ELLIPSE integer  
MS_SYMBOL_PIXMAP integer  
MS_SYMBOL_TRUETYPE integer  
MS_SYMBOL_CARTOLINE integer  

2.22   Return Codes

Name Type Value
MS_SUCCESS integer 0
MS_FAILURE integer 1
MS_DONE integer 2

2.23   Limiters

Name Type Value
MS_MAXSYMBOLS long  
MS_MAXVECTORPOINTS long  
MS_MAXSTYLELENGTH long  
MS_IMAGECACHESIZE long  

2.24   Error Return Codes

Name Type Value
MS_NOERR long 0
MS_IOERR long 1
MS_MEMERR long 2
MS_TYPEERR long 3
MS_SYMERR long 4
MS_REGEXERR long 5
MS_TTFERR long 6
MS_DBFERR long 7
MS_GDERR long 8
MS_IDENTERR long 9
MS_EOFERR long 10
MS_PROJERR long 11
MS_MISCERR long 12
MS_CGIERR long 13
MS_WEBERR long 14
MS_IMGERR long 15
MS_HASHERR long 16
MS_JOINERR long 17
MS_NOTFOUND long 18
MS_SHPERR long 19
MS_PARSEERR long 20
MS_SDEERR long 21
MS_OGRERR long 22
MS_QUERYERR long 23
MS_WMSERR long 24
MS_WMSCONNERR long 25
MS_ORACLESPATIALERR long 26
MS_WFSERR long 27
MS_WFSCONNERR long 28
MS_MAPCONTEXTERR long 29
MS_HTTPERR long 30
MS_CHILDERR long 31
MS_WCSERR long 32
MS_NUMERRORCODES long 33
MESSAGELENGTH long 33
ROUTINELENGTH long 33

3   Mapscript Functions

msCleanup() : void
msCleanup() attempts to recover all dynamically allocated resources allocated by MapServer code and dependent libraries. It it used primarily for final cleanup in scripts that need to do memory leak testing to get rid of "noise" one-time allocations. It should not normally be used by production code.
msGetVersion() : string
Returns a string containing MapServer version information, and details on what optional components are built in. The same report as produced by "mapserv -v".
msIO_installStdoutToBuffer() : void
Installs a mapserver IO handler directing future stdout output to a memory buffer.
msIO_installStdinFromBuffer() : void
Installs a mapserver IO handler directing future stdin reading (ie. post request capture) to come from a buffer.
msIO_resetHandlers() : void
Resets the default stdin and stdout handlers in place of "buffer" based handlers.
msIO_getStdoutBufferString() : string
Fetch the current stdout buffer contents as a string. This method does not clear the buffer.
msIO_getStdoutBufferBytes() : binary data
Fetch the current stdout buffer contents as a binary buffer. The exact form of this buffer will vary by mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled in perl)
msIO_stripStdoutBufferContentType() : string
Strip the Content-type header off the stdout buffer if it has one, and if a content type is found it is return (otherwise NULL/None/etc).

4   Mapscript Classes

4.1   classObj

An instance of classObj is associated with with one instance of layerObj.

+-------+ 0..*     1 +-------+
| Class | <--------> | Layer |
+-------+            +-------+

The other important associations for classObj are with styleObj, labelObj, and hashTableObj.

+-------+ 1     0..* +-------+
| Class | ---------> | Style |
+-------+            +-------+

+-------+ 1     0..1 +-------+
| Class | ---------> | Label |
+-------+            +-------+

+-------+ 1        1 +-----------+
| Class | ---------> | HashTable |
+-------+            |    --     |
                     | metadata  |
                     +-----------+

Multiple class styles are now supported in 4.1. See the styleObj section for details on use of multiple class styles.

4.1.1   classObj Attributes
debug : int
MS_TRUE or MS_FALSE
keyimage : string
TODO Not sure what this attribute is for
label : labelObj immutable
Definition of class labeling
layer : layerObj immutable
Reference to the parent layer
maxscale : float
The maximum scale at which class is drawn
metadata : hashTableObj immutable
class metadata hash table.
minscale : float
The minimum scale at which class is drawn
name : string
Unique within a layer
numstyles : int
Number of styles for class. In the future, probably the 4.4 release, this attribute will be made immutable.
status : int
MS_ON or MS_OFF. Draw features of this class or do not.
template : string
Template for queries
title : string
Text used for legend labeling
type : int
The layer type of its parent layer
4.1.2   classObj Methods
new classObj( [ layerObj parent_layer=NULL ] ) : classObj
Create a new child classObj instance at the tail (highest index) of the class array of the parent_layer. A class can be created outside the context of a parent layer by omitting the single constructor argument.
clone( ) : classObj
Return an independent copy of the class without a parent layer.
createLegendIcon( mapObj map, layerObj layer, int width, int height ) : imageObj
Draw and return a new legend icon.
drawLegendIcon( mapObj map, layerObj layer, int width, int height, imageObj image, int dstx, int dsty ) : int
Draw the legend icon onto image at dstx, dsty. Returns MS_SUCCESS or MS_FAILURE.
getExpressionString() : string
Return a string representation of the expression enclosed in the quote characters appropriate to the expression type.
getFirstMetaDataKey() : string
Returns the first key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys.
getMetaData( string key ) : string
Return the value of the classObj metadata at key.
getNextMetaDataKey( string lastkey ) : string
Returns the next key in the metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.

Note

getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.

getStyle( int index ) : styleObj

Return a reference to the styleObj at index in the styles array.

See the styleObj section for more details on multiple class styles.

getTextString() : string
Return a string representation of the text enclosed in the quote characters appropriate to the text expression type (logical or simple string).
insertStyle( styleObj style [, int index=-1 ] ) : int
Insert a copy of style into the styles array at index index. Default is -1, or the end of the array. Returns the index at which the style was inserted.
moveStyleDown( int index ) : int
Swap the styleObj at index with the styleObj index + 1.
moveStyleUp( int index ) : int
Swap the styleObj at index with the styleObj index - 1.
removeStyle( int index ) : styleObj
Remove the styleObj at index from the styles array and return a copy.
setExpression( string expression ) : int
Set expression string where expression is a MapServer regular, logical or string expression. Returns MS_SUCCESS or MS_FAILUIRE.
setMetaData( string key, string value ) : int
Insert value into the classObj metadata at key. Returns MS_SUCCESS or MS_FAILURE.

Note

setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.

setText( string text ) : int
Set text string where text is a MapServer text expression. Returns MS_SUCCESS or MS_FAILUIRE.

Note

Older versions of MapScript (pre-4.8) featured the an undocumented setText() method that required a layerObj be passed as the first argument. That argument was completely bogus and has been removed.

4.2   colorObj

Since the 4.0 release, MapServer colors are instances of colorObj. A colorObj may be a lone object or an attribute of other objects and have no other associations.

4.2.1   colorObj Attributes
blue : int
Blue component of color in range [0-255]
green : int
Green component of color in range [0-255]
red : int
Red component of color in range [0-255]
pen : int
Don't mess with this unless you know what you are doing!

Note

Because of the issue with pen, setting colors by individual components is unreliable. Best practice is to use setRGB(), setHex(), or assign to a new instance of colorObj().

4.2.2   colorObj Methods
new colorObj( [ int red=0, int green=0, int blue=0, int pens=-4 ] ) : colorObj
Create a new instance. The color arguments are optional.
setRGB( int red, int green, int blue ) : int
Set all three RGB components. Returns MS_SUCCESS or MS_FAILURE.
setHex( string hexcolor ) : int
Set the color to values specified in case-independent hexadecimal notation. Calling setHex('#ffffff') assigns values of 255 to each color component. Returns MS_SUCCESS or MS_FAILURE.
toHex() : string
Complement to setHex, returning a hexadecimal representation of the color components.

4.3   errorObj

This class allows inspection of the MapServer error stack. Only needed for the Perl module as the other language modules expose the error stack through exceptions.

4.3.1   errorObj Attributes
code : int
MapServer error code such as MS_IMGERR (1).
message : string
Context-dependent error message.
routine : string
MapServer function in which the error was set.
4.3.2   errorObj Methods
next : errorObj
Returns the next error in the stack or NULL if the end has been reached.

4.4   fontSetObj

A fontSetObj is always a 'fontset' attribute of a mapObj.

4.4.1   fontSetObj Attributes
filename : string immutable
Path to the fontset file on disk.
fonts : hashTableObj immutable
Mapping of fonts.
numfonts : int immutable
Number of fonts in set.

4.5   hashTableObj

A hashTableObj is a very simple mapping of case-insensitive string keys to single string values. Map, Layer, and Class metadata have always been hash hables and now these are exposed directly. This is a limited hash that can contain no more than 41 values.

4.5.1   hashTableObj Attributes
numitems : int immutable
Number of hash items.
4.5.2   hashTableObj Methods
clear( ) : void
Empties the table of all items.
get( string key [, string default=NULL ] ) : string
Returns the value of the item by its key, or default if the key does not exist.
nextKey( [string key=NULL] ) : string
Returns the name of the next key or NULL if there is no valid next key. If the input key is NULL, returns the first key.
remove( string key ) : int
Removes the hash item by its key. Returns MS_SUCCESS or MS_FAILURE.
set( string key, string value ) : int
Sets a hash item. Returns MS_SUCCESS or MS_FAILURE.

4.6   imageObj

An image object is a wrapper for GD and GDAL images.

4.6.1   imageObj Attributes
format : outputFormatObj immutable
Image format.
height : int immutable
Image height in pixels.
imagepath : string immutable
If image is drawn by mapObj.draw(), this is the mapObj's web.imagepath.
imageurl : string immutable
If image is drawn by mapObj.draw(), this is the mapObj's web.imageurl.
renderer : int
MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA, MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP. Don't mess with this!
size : int
I don't see where this is used. Anyone? --SG
width : int immutable
Image width in pixels.
4.6.2   imageObj Methods
new imageObj( int width, int height [, outputFormatObj format=NULL [, string filename=NULL ] ] ) : imageObj
Create new instance of imageObj. If filename is specified, an imageObj is created from the file and any specified width, height, and format parameters will be overridden by values of the image in filename. Otherwise, if format is specified an imageObj is created using that format. See the format attribute above for details. If filename is not specified, then width and height should be specified.
getBytes() : binary data
Returns the image contents as a binary buffer. The exact form of this buffer will vary by mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled in perl)
save( string filename [, mapObj parent_map=NULL ] ) : int
Save image to filename. The optional parent_map parameter must be specified if saving GeoTIFF images.
write( [ FILE file=NULL ] ) : int
Write image data to an open file descriptor or, by default, to stdout. Returns MS_SUCCESS or MS_FAILURE.

Note

This method is current enabled for Python and C# only. C# supports writing onto a Stream object. User-contributed typemaps are needed for Perl, Ruby, and Java.

Note

The free() method of imageObj has been deprecated. In MapServer revisions 4+ all instances of imageObj will be properly disposed of by the interpreter's garabage collector. If the application can't wait for garabage collection, then the instance can simply be deleted or undef'd.

4.7   intarray

An intarray is a utility class generated by SWIG useful for manipulating map layer drawing order. See mapObj::getLayersDrawingOrder for discussion of mapscript use and see http://www.swig.org/Doc1.3/Library.html#Library_nn5 for a complete reference.

4.7.2   intarray Methods
new intarray( int numitems ) : intarray
Returns a new instance of the specified length.

4.8   labelCacheMemberObj

An individual feature label. The labelCacheMemberObj class is associated with labelCacheObj.

+------------------+ 0..*     1 +------------+
| LabelCacheMember | <--------- | LabelCache |
+------------------+            +------------+
4.8.1   labelCacheMemberObj Attributes
classindex : int immutable
Index of the class of the labeled feature.
featuresize : float immutable
TODO
label : labelObj immutable
Copied from the class of the labeled feature.
layerindex : int immutable
The index of the layer of the labeled feature.
numstyles : int immutable
Number of styles as for the class of the labeled feature.
point : pointObj immutable
Label point.
poly : shapeObj immutable
Label bounding box.
shapeindex : int immutable
Index within shapefile of the labeled feature.
status : int immutable
Has the label been drawn or not?
styles : styleObj immutable
TODO this should be protected from SWIG.
text : string immutable
Label text.
tileindex : int immutable
Tileindex of the layer of the labeled feature.
4.8.2   labelCacheMemberObj Methods

None.

Note

No real scripting control over labeling currently, but there may be some interesting new possibilities if users have control over labeling text, position, and status.

4.9   labelCacheObj

Set of a map's cached labels. Has no other existence other than as a 'labelcache' attribute of a mapObj. Associated with labelCacheMemberObj and markerCacheMemberObj.

+------------+ 1     0..* +-------------------+
| LabelCache | ---------> | LabelCacheMember  |
+------------+            + ----------------- +
                          | MarkerCacheMember |
                          +-------------------+
4.9.1   labelCacheObj Attributes
cachesize : int immutable
TODO
markercachesize : int immutable
TODO
numlabels : int immutable
Number of label members.
nummarkers : int immutable
Number of marker members.
4.9.2   labelCacheObj Methods
freeCache( ) : void
Free the labelcache.

4.10   labelObj

A labelObj is associated with a classObj, a scalebarObj, or a legendObj.

+-------+ 0..1     1 +----------+
| Label | <--------- | Class    |
+-------+            | -------- |
                     | Scalebar |
                     | -------- |
                     | Legend   |
                     +----------+
4.10.1   labelObj Attributes
angle : float
TODO
antialias : int
MS_TRUE or MS_FALSE
autoangle : int
MS_TRUE or MS_FALSE
autofollow : int
MS_TRUE or MS_FALSE. Tells mapserver to compute a curved label for appropriate linear features (see RFC 11 for specifics).
autominfeaturesize: int
MS_TRUE or MS_FALSE
backgroundcolor : colorObj
Color of background rectangle or billboard.
backgroundshadowcolor : colorObj
Color of background rectangle or billboard shadow.
backgroundshadowsizex : int
Horizontal offset of drop shadow in pixels.
backgroundshadowsizey : int
Vertical offset of drop shadow in pixels.
buffer : int
Maybe this should've been named 'padding' since that's what it is: padding in pixels around a label.
color : colorObj
Foreground color.
encoding : string
Supported encoding format to be used for labels. If the format is not supported, the label will not be drawn. Requires the iconv library (present on most systems). The library is always detected if present on the system, but if not the label will not be drawn. Required for displaying international characters in MapServer. More information can be found at: http://www.foss4g.org/FOSS4G/MAPSERVER/mpsnf-i18n-en.html.
font : string
Name of TrueType font.
force : int
MS_TRUE or MS_FALSE.
maxsize : int
Maximum height in pixels for scaled labels. See symbolscale attribute of layerObj.
mindistance : int
Minimum distance in pixels between duplicate labels.
minfeaturesize : int
Features of this size of greater will be labeled.
minsize : int
Minimum height in pixels.
offsetx : int
Horizontal offset of label.
offsety : int
Vertical offset of label.
outlinecolor : colorObj
Color of one point outline.
partials : int
MS_TRUE (default) or MS_FALSE. Whether or not labels can flow past the map edges.
position : int
MS_UL, MS_UC, MS_UR, MS_CL, MS_CC, MS_CR, MS_LL, MS_LC, MS_LR, or MS_AUTO.
shadowcolor : colorObj
Color of drop shadow.
shadowsizex : int
Horizontal offset of drop shadow in pixels.
shadowsizey : int
Vertical offset of drop shadow in pixels.
size : int
Annotation height in pixels.
type : int
MS_BITMAP or MS_TRUETYPE.
wrap : string
Character on which legend text will be broken to make multi-line legends.

4.11   layerObj

A layerObj is associated with mapObj. In the most recent revision, an intance of layerObj can exist outside of a mapObj.

+-------+ 0..*  0..1 +-----+
| Layer | <--------> | Map |
+-------+            +-----+

The other important association for layerObj is with classObj

+-------+ 1     0..* +-------+
| Layer | <--------> | Class |
+-------+            +-------+

and hashTableObj

+-------+ 1        1 +-----------+
| Layer | ---------> | HashTable |
+-------+            |    --     |
                     | metadata  |
                     +-----------+
4.11.1   layerObj Attributes
bandsitem : string
The attribute from the index file used to select the source raster band(s) to be used. Normally NULL for default bands processing.
classitem : string
The attribute used to classify layer data.
connection : string
Layer connection or DSN.
connectiontype : int
See MS_CONNECTION_TYPE in map.h for possible values.
data : string
Layer data definition, values depend upon connectiontype.
debug : int
Enable debugging of layer. MS_ON or MS_OFF (default).
dump : int
Switch to allow mapserver to return data in GML format. MS_TRUE or MS_FALSE. Default is MS_FALSE.
extent : rectObj
optional limiting extent for layer features.
filteritem : string
Attribute defining filter.
footer : string
TODO
group : string
Name of a group of layers.
header : string
TODO
index : int immutable
Index of layer within parent map's layers array.
labelangleitem : string
Attribute defining label angle.
labelcache : int
MS_ON or MS_OFF. Default is MS_ON.
labelitem : string
Attribute defining feature label text.
labelmaxscale : float
Maximum scale at which layer will be labeled.
labelminscale : float
Minimum scale at which layer will be labeled.
labelrequires : string
Logical expression.
labelsizeitem : string
Attribute defining label size.
map : mapObj immutable
Reference to parent map.
maxfeatures : int
Maximum number of layer features that will be drawn. For shapefile data this means the first N features where N = maxfeatures.
maxscale : float
Maximum scale at which layer will be drawn.
metadata : hashTableObj immutable
Layer metadata.
minscale : float
Minimum scale at which layer will be drawn.
name : string
Unique identifier for layer.
numclasses : int immutable
Number of layer classes.
numitems : int immutable
Number of layer feature attributes (items).
numjoins : int immutable
Number of layer joins.
numprocessing : int immutable
Number of raster processing directives.
offsite : colorObj
transparent pixel value for raster layers.
postlabelcache : int
MS_TRUE or MS_FALSE. Default is MS_FALSE.
requires : string
Logical expression.
sizeunits : int
Units of class size values. MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD or MS_PIXELS
status : int
MS_ON, MS_OFF, or MS_DEFAULT.
styleitem : string
Attribute defining styles.
symbolscale : float
Scale at which symbols are default size.
template : string
Template file. Note that for historical reasons, the query attribute must be non-NULL for a layer to be queryable.
tileindex : string
Layer index file for tiling support.
tileitem : string
Attribute defining tile paths.
tolerance : float
Search buffer for point and line queries.
toleranceunits : int
MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD or MS_PIXELS
transform : int
Whether or not layer data is to be transformed to image units. MS_TRUE or MS_FALSE. Default is MS_TRUE. Case of MS_FALSE is for data that are in image coordinates such as annotation points.
transparency : int
Layer opacity percentage in range [0, 100]. The special value of MS_GD_ALPHA (1000) indicates that the alpha transparency of pixmap symbols should be honored, and should be used only for layers that use RGBA pixmap symbols.
type : int
See MS_LAYER_TYPE in map.h.
units : int
Units of the layer. See MS_UNITS in map.h.
4.11.2   layerObj Methods
new layerObj( [ mapObj parent_map=NULL ] ) : layerObj
Create a new layerObj in parent_map. The layer index of the new layerObj will be equal to the parent_map numlayers - 1. The parent_map arg is now optional and Layers can exist outside of a Map.
addFeature( shapeObj shape ) : int
Add a new inline feature on a layer. Returns -1 on error. TODO: Is this similar to inline features in a mapfile? Does it work for any kind of layer or connection type?
addProcessing( string directive ) : void
Adds a new processing directive line to a layer, similar to the PROCESSING directive in a map file. Processing directives supported are specific to the layer type and underlying renderer.
applySLD( string sld, string stylelayer ) : int
Apply the SLD document to the layer object. The matching between the sld document and the layer will be done using the layer's name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HOWTO for more information on the SLD support.
applySLDURL( string sld, string stylelayer ) : int
Apply the SLD document pointed by the URL to the layer object. The matching between the sld document and the layer will be done using the layer's name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HOWTO for more information on the SLD support.
clearProcessing() : int
Clears the layer's raster processing directives. Returns the subsequent number of directives, which will equal MS_SUCCESS if the directives have been cleared.
clone() : layerObj
Return an independent copy of the layer with no parent map.
close() : void
Close the underlying layer.

Note

demote() is removed in MapServer 4.4

draw( mapObj map, imageObj image ) : int
Renders this layer into the target image, adding labels to the cache if required. Returns MS_SUCCESS or MS_FAILURE. TODO: Does the map need to be the map on which the layer is defined? I suspect so.
drawQuery( mapObj map, imageObj image ) :
Draw query map for a single layer into the target image. Returns MS_SUCCESS or MS_FAILURE.
executeWFSGetFeature( layer ) : string
Executes a GetFeature request on a WFS layer and returns the name of the temporary GML file created. Returns an empty string on error.
generateSLD() : void
Returns an SLD XML string based on all the classes found in the layers.
getClass( int i ) : classObj
Fetch the requested class object. Returns NULL if the class index is out of the legal range. The numclasses field contains the number of classes available, and the first class is index 0.
getExtent() : rectObj
Fetches the extents of the data in the layer. This normally requires a full read pass through the features of the layer and does not work for raster layers.
getFeature( int shapeindex [, int tileindex=-1 ] ) : shapeObj
Return the layer feature at shapeindex and tileindex.
getFilterString() : string
Returns the current filter expression.
getFirstMetaDataKey() : string
Returns the first key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys.
getItem( int i ) : string
Returns the requested item. Items are attribute fields, and this method returns the item name (field name). The numitems field contains the number of items available, and the first item is index zero.
getMetaData( string key ) : string
Return the value at key from the metadata hash table.
getNextMetaDataKey( string lastkey ) : string
Returns the next key in the metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.

Note

getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.

getNumFeatures() : int
Returns the number of inline features in a layer. TODO: is this really only online features or will it return the number of non-inline features on a regular layer?
getNumResults() : int
Returns the number of entries in the query result cache for this layer.
getProcessing( int index) : string
Return the raster processing directive at index.
getProjection( ) : string
Returns the PROJ.4 definition of the layer's projection.
getResult( int i ) : resultCacheMemberObj
Fetches the requested query result cache entry, or NULL if the index is outside the range of available results. This method would normally only be used after issuing a query operation.

Note

getNumResults() and getResult() are deprecated in MapServer 4.4. Users should instead use the new querying API described in querying-HOWTO.txt. layerObj::getResults() is the entry point for the new API.

getResults() : resultCacheObj
Returns a reference to layer's result cache. Should be NULL prior to any query, or after a failed query or query with no results.
getShape( shapeObj shape, int tileindex, int shapeindex ) : int
Get a shape from layer data.

Note

getShape() is deprecated. Users should adopt getFeature() for new applications.

getWMSFeatureInfoURL( mapObj map, int click_x, int click_y, int feature_count, string info_format ) : string
Return a WMS GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return. infoFormat is the format the format in which the result should be requested. Depends on remote server's capabilities. MapServer WMS servers support only "MIME" (and should support "GML.1" soon). Returns "" and outputs a warning if layer is not a WMS layer or if it is not queriable.
insertClass( classObj class [, int index=-1 ] ) : int
Insert a copy of the class into the layer at the requested index. Default index of -1 means insertion at the end of the array of classes. Returns the index at which the class was inserted.
isVisible( ) : int
Returns MS_TRUE or MS_FALSE after considering the layer status, minscale, and maxscale within the context of the parent map.
moveClassDown( int class ) : int
The class specified by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex. moveClassDown(1) will have the effect of moving class 1 down to postion 2, and the class at position 2 will be moved to position 1.
moveClassUp( int class ) : int
The class specified by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex. moveClassUp(1) will have the effect of moving class 1 up to postion 0, and the class at position 0 will be moved to position 1.
nextShape( ) : shapeObj

Called after msWhichShapes has been called to actually retrieve shapes within a given area returns a shape object or MS_FALSE

example of usage :

mapObj map = new mapObj("d:/msapps/gmap-ms40/htdocs/gmap75.map");
layerObj layer = map.getLayerByName('road');
int status = layer.open();
status = layer.whichShapes(map.extent);
shapeObj shape;
while ((shape = layer.nextShape()) != null) 
{
  ...
}
layer.close();
open() : void
Opens the underlying layer. This is required before operations like getFeature() will work, but is not required before a draw or query call.

Note

promote() is eliminated in MapServer 4.4.

queryByAttributes( mapObj map, string qitem, string qstring, int mode ) : int

Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value.

Note that the layer's FILTER/FILTERITEM are ignored by this function. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened.

queryByFeatures( mapObj map, int slayer ) : int
Perform a query set based on a previous set of results from another layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened
queryByIndex( mapObj map, int shapeindex, int tileindex [, int bAddToQuery=MS_FALSE ]) : int
Pop a query result member into the layer's result cache. By default clobbers existing cache. Returns MS_SUCCESS or MS_FAILURE.
queryByPoint( mapObj map, pointObj point, int mode, float buffer ) : int
Query layer at point location specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer <=0 defaults to tolerances set in the map file (in pixels) but you can use a constant buffer (specified in ground units) instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened.
queryByRect( mapObj map, rectObj rect ) : int
Query layer using a rectangle specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened.
queryByShape( mapObj map, shapeObj shape ) : int
Query layer based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened
removeClass( int index ) : classObj
Removes the class indicated and returns a copy, or NULL in the case of a failure. Note that subsequent classes will be renumbered by this operation. The numclasses field contains the number of classes available.
removeMetaData( string key ) : int
Delete the metadata hash at key. Returns MS_SUCCESS or MS_FAILURE.

Note

removeMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.

setExtent( float minx, float miny, float maxx, float maxy ) : int
Sets the extent of a layer. Returns MS_SUCCESS or MS_FAILURE.
setFilter( string filter ) : int
Sets a filter expression similarly to the FILTER expression in a map file. Returns MS_SUCCESS on success or MS_FAILURE if the expression fails to parse.
setMetaData( string key, string value ) : int
Assign value to the metadata hash at key. Return MS_SUCCESS or MS_FAILURE.

Note

setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.

setProcessingKey( string key, string value ) : void
Adds or replaces a processing directive of the form "key=value". Unlike the addProcessing() call, this will replace an existing processing directive for the given key value. Processing directives supported are specific to the layer type and underlying renderer.
setProjection( string proj4 ) : int
Set the layer projection using a PROJ.4 format projection definition (ie. "+proj=utm +zone=11 +datum=WGS84" or "init=EPSG:26911"). Returns MS_SUCCESS or MS_FAILURE.
setWKTProjection( string wkt ) : int
Set the layer projection using OpenGIS Well Known Text format. Returns MS_SUCCESS or MS_FAILURE.
int whichShapes( rectObj rect ) : int
Performs a spatial, and optionally an attribute based feature search. The function basically prepares things so that candidate features can be accessed by query or drawing functions (eg using nextShape function). Returns MS_SUCCESS or MS_FAILURE.

4.12   legendObj

legendObj is associated with mapObj

+--------+ 0..1     1 +-----+
| Legend | <--------> | Map |
+--------+            +-----+

and with labelObj.

+--------+ 1        1 +-------+
| Legend | ---------> | Label |
+--------+            +-------+
4.12.1   legendObj Attributes
height : int
Legend height.
imagecolor : colorObj
Legend background color.
keysizex : int
Width in pixels of legend keys.
keysizey : int
Pixels.
keyspacingx : int
Horizontal padding around keys in pixels.
keyspacingy : int
Vertical padding.
label : labelObj immutable
legend label.
map : mapObj immutable
Reference to parent mapObj.
outlinecolor : colorObj
key outline color.
position : int
MS_UL, MS_UC, MS_UR, MS_LL, MS_LC, or MS_LR.
postlabelcache : int
MS_TRUE or MS_FALSE.
status : int
MS_ON, MS_OFF, or MS_EMBED.
template : string
Path to template file.
width : int
Label width.

4.13   lineObj

A lineObj is composed of one or more pointObj instances.

+------+ 0..1  1..* +-------+
| Line | ---------> | Point |
+------+            +-------+
4.13.1   lineObj Attributes
numpoints : int immutable
Number of points in the line.
4.13.2   lineObj Methods
add(pointObj point) : int
Add point to the line. Returns MS_SUCCESS or MS_FAILURE.
get(int index) : pointObj
Return reference to point at index.
project(projectionObj proj_in, projectionObj proj_out) : int
Transform line in place from proj_in to proj_out. Returns MS_SUCCESS or MS_FAILURE.
set(int index, pointObj point) : int
Set the point at index to point. Returns MS_SUCCESS or MS_FAILURE.

4.14   mapObj

A mapObj is primarily associated with instances of layerObj.

+-----+ 0..1  0..* +-------+
| Map | <--------> | Layer |
+-----+            +-------+

Secondary associations are with legendObj, scalebarObj, referenceMapObj,

+-----+ 1     0..1 +--------------+
| Map | ---------> | Legend       |
+-----+            | ------------ |
                   | Scalebar     |
                   | ------------ |
                   | ReferenceMap |
                   +--------------+

outputFormatObj.

+-----+ 1     1..* +--------------+
| Map | ---------> | OutputFormat |
+-----+            +------------- +
4.14.1   mapObj Attributes
cellsize : float
Pixel size in map units.
configoptions : hashObj immutable
A hash table of configuration options from CONFIG keywords in the .map. Direct access to config options is discouraged. Use the setConfigOption() and getConfigOption() methods instead.
datapattern : string
TODO not sure this is meaningful for mapscript.
debug : int
MS_TRUE or MS_FALSE.
extent : rectObj
Map's spatial extent.
fontset : fontSetObj immutable
The map's defined fonts.
height : int
Map's output image height in pixels.

Note

direct setting of height is deprecated in MapServer version 4.4. Users should set width and height simultaneously using setSize().

imagecolor : colorObj
Initial map background color.
imagequality : int
JPEG image quality.

Note

map imagequality is deprecated in MapServer 4.4 and should instead be managed through map outputformats.

imagetype : string immutable
Name of the current output format.
interlace : int
Output image interlacing.

Note

map interlace is deprecated in MapServer 4.4 and should instead be managed through map outputformats.

lablecache : labelCacheObj immutable
Map's labelcache.
legend : legendObj immutable
Reference to map's legend.
mappath : string
Filesystem path of the map's mapfile.
maxsize : int
TODO ?
name : string
Unique identifier.
numlayers : int immutable
Number of map layers.
numoutputformats : int
Number of output formats.
outputformat : outputFormatObj
The currently selected output format.

Note

Map outputformat should not be modified directly. Use the selectOutputFormat() method to select named formats.

outputformatlist : outputFormatObj[]
Array of the available output formats.

Note

Currently only available for C#. A proper typemaps should be implemented for the other languages.

querymap : queryMapObj immutable
TODO should this be exposed to mapscript?
reference : referenceMapObj immutable
Reference to reference map.
resolution : float
Nominal DPI resolution. Default is 72.
scale : float
The nominal map scale. A value of 25000 means 1:25000 scale.
scalebar : scalebarObj immutable
Reference to the scale bar.
shapepath : string
Base filesystem path to layer data.
status : int
MS_OFF, MS_ON, or MS_DEFAULT.
symbolset : symbolSetObj immutable
The map's set of symbols.
templatepattern : string
TODO not sure this is meaningful for mapscript.
transparent : int
MS_TRUE or MS_FALSE.

Note

map transparent is deprecated in MapServer 4.4 and should instead be managed through map outputformats.

units : int
MS_DD, MS_METERS, etc.
web : webObj immutable
Reference to map's web definitions.
width : int
Map's output image width in pixels.

Note

direct setting of width is deprecated in MapServer version 4.4. Users should set width and height simultaneously using setSize().

4.14.2   mapObj Methods
new mapObj( [ string filename='' ] ) : mapObj
Create a new instance of mapObj. Note that the filename is now optional.
appendOutputFormat( outputFormatObj format ) : int
Attach format to the map's output format list. Returns the updated number of output formats.
applyConfigOptions( ) : void
Apply the defined configuration options set by setConfigOption().
applySLD( string sldxml ) : int
Parse the SLD XML string sldxml and apply to map layers. Returns MS_SUCCESS or MS_FAILURE.
applySLDURL( string sldurl ) : int
Fetch SLD XML from the URL sldurl and apply to map layers. Returns MS_SUCCESS or MS_FAILURE.
clone( ) : mapObj

Returns a independent copy of the map, less any caches.

Note

In the Java module this method is named 'cloneMap'.

draw( ) : imageObj
Draw the map, processing layers according to their defined order and status. Return an imageObj.
drawLabelCache( imageObj image ) : int
Draw map's label cache on image. Returns MS_SUCCESS or MS_FAILURE.
drawLegend( ) : imageObj
Draw map legend, returning an imageObj.
drawQuery( ) : imageObj
Draw query map, returning an imageObj.
drawReferenceMap( ) : imageObj
Draw reference map, returning an imageObj.
drawScalebar( ) : imageObj
Draw scale bar, returning an imageObj.
embedLegend( imageObj image ) : int
Embed map's legend in image. Returns MS_SUCCESS or MS_FAILURE.
embedScalebar( imageObj image ) : int
Embed map's scalebar in image. Returns MS_SUCCESS or MS_FAILURE.
freeQuery( [ int qlayer=-1 ] ) : void
Clear layer query result caches. Default is -1, or all layers.
generateSLD( ) : string
Return SLD XML as a string for map layers.
getConfigOption( string key ) : string
Fetches the value of the requested configuration key if set. Returns NULL if the key is not set.
getFirstMetaDataKey( ) : string
Returns the first key in the web.metadata hash table. With getNextMetaDataKey( ), provides an opaque iterator over keys.
getLayer( int index ) : layerObj
Returns a reference to the layer at index.
getLayerByName( string name ) : layerObj
Returns a reference to the named layer.
getLayersDrawingOrder( ) : int*
Returns an array of layer indexes in drawing order.

Note

Unless the proper typemap is implemented for the module's language a user is more likely to get back an unuseable SWIG pointer to the integer array.

getMetaData( string key ) : string
Return the value at key from the web.metadata hash table.
getNextMetaDataKey( string lastkey ) : string
Returns the next key in the web.metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.
getNumSymbols( ) : int
Return the number of symbols in map.
getOutputFormatByName( string imagetype ) : outputFormatObj
Return the output format corresponding to driver name imagetype or to format name imagetype. This works exactly the same as the IMAGETYPE directive in a mapfile, is case insensitive and allows an output format to be found either by driver (like 'GD/PNG') or name (like 'PNG24').
getProjection( ) : string
Returns the PROJ.4 definition of the map's projection.
getSymbolByName( string name ) : int
Return the index of the named symbol in the map's symbolset.

Note

This method is poorly named and too indirect. It is preferrable to use the getSymbolByName method of symbolSetObj, which really does return a symbolObj reference, or use the index method of symbolSetObj to get a symbol's index number.

insertLayer( layerObj layer [, int nIndex=-1 ] ) : int
Insert a copy of layer into the Map at index nIndex. The default value of nIndex is -1, which means the last possible index. Returns the index of the new Layer, or -1 in the case of a failure.
loadMapContext( string filename [, int useUniqueNames=MS_FALSE ] ) : int
Load an OGC map context file to define extents and layers of a map.
loadOWSParameters( OWSRequest request [, string version='1.1.1' ] ) : int
Load OWS request parameters (BBOX, LAYERS, &c.) into map. Returns MS_SUCCESS or MS_FAILURE.
loadQuery( string filename ) : int
Load a saved query. Returns MS_SUCCESS or MS_FAILURE.
moveLayerDown( int layerindex ) : int
Move the layer at layerindex down in the drawing order array, meaning that it is drawn later. Returns MS_SUCCESS or MS_FAILURE.
moveLayerUp( int layerindex ) : int
Move the layer at layerindex up in the drawing order array, meaning that it is drawn earlier. Returns MS_SUCCESS or MS_FAILURE.
nextLabel( ) : labelCacheMemberObj
Return the next label from the map's labelcache, allowing iteration over labels.
OWSDispatch( OWSRequest req ) : int
Processes and executes the passed OpenGIS Web Services request on the map. Returns MS_DONE (2) if there is no valid OWS request in the req object, MS_SUCCESS (0) if an OWS request was successfully processed and MS_FAILURE (1) if an OWS request was not successfully processed. OWS requests include WMS, WFS, WCS and SOS requests supported by MapServer. Results of a dispatched request are written to stdout and can be captured using the msIO services (ie. msIO_installStdoutToBuffer() and msIO_getStdoutBufferString())
prepareImage( ) : imageObj
Returns an imageObj initialized to map extents and outputformat.
prepareQuery( ) : void
TODO this function only calculates the scale or am I missing something?
processLegendTemplate( string names[], string values[], int numitems ) : string
Process MapServer legend template and return HTML.
processQueryTemplate( string names[], string values[], int numitems )