HBUMNMapServer ger Capter Referenz

= Referenz =

In jedes Buch gehört natürlich eine tolle Programmierreferenz. Um das Schlagwort zu zitieren: "`Das Buch soll den Schreibtisch nicht wieder verlassen"', und das kann man nur mit einem Nachschlagewerk schaffen.

=Limits=\index{Limits}

Möchte man den MapServer produktiv einsetzen, muß man diverse Limits kennen, über deren Existenz man ansonsten schnell stolpert. Diese Limits möchte ich nun vorstellen.

Man kann diese Limits verändern, indem man vor dem Kompilieren diverse Einträge in den Quelldateien verändert.


 * =MS_MAXIMGSIZE 2048= Die maximale Größe für eine produzierte Karte ist 2048 Pixel im Quadrat (map.h)
 * =MS_MAXCLASSES 250= Die maximale Anzahl von Classes in einem Layer beträgt 250 (map.h)
 * =MS_STYLES 5= Die maximale Zahl von Styles in einer Class beträgt 5.
 * =MS_MAXPROJARGS 20= Eine Projektions-Sektion kann maximal 20 Argumente aufnehmen (map.h)
 * =MS_MAXLAYERS 100= Ein Mapfile kann maximal 100 Layer aufnehmen (map.h)
 * =MS_NAMELEN 20= Der Name einer Sektion kann maximal 20 Zeichen lang sein (map.h)
 * =MS_MAXSYMBOLSIZE 100= und =MS_MINSYMBOLSIZE 1=  Ein Symbol muß mindestens 1 und kann maximal 100 Pixel groß sein (map.h)
 * =MS_MAXFONTSIZE 256= und =MS_MINFONTSIZE 4=  Eine Beschriftung muß mindestens 4 und kann maximal 256 Pixel groß sein (map.h)
 * =MS_MAXSYMBOLS 64= Die maximale Anzahl an Symbolen beträgt 64 (mapsymbol.h)
 * =MS_MAXVECTORPOINTS 100= Ein Vektorsymbol kann über maximal 100 Punkte definiert werden (mapsymbol.h)
 * =MS_URL_LENGTH 1024= Der URL zu Aufruf des MapServer kann maximal 1024 Zeichen lang sein (map.h)
 * =MS_MAXBUFFER_LENGTH 2048= Eine Zeile im Mapfile darf maximal 2048 Zeichen lang sein (map.h)

=Organisation der Daten=

Generell ist es irrelevant, wie Sie die Daten Ihrer Applikation organisieren, solange Sie nur selber den Überblick behalten können. Da keine Norm existiert, an die man sich halten muß (oder halten sollte), können Sie praktisch machen, was Sie wollen. Wir präsentieren Ihnen an dieser Stelle ein durch den Autor häufig eingesetztes Beispiel, das Ihnen eine Idee für einen strukturierten Aufbau einer MapServer-Applikation geben soll.

Die Idee ist, die gesamte Applikation samt aller dazugehörigen Daten in einem eigenen Verzeichnisbaum zu halten. Schauen Sie sich zuerst die folgende Verzeichnishierarchie an.

Das Mapfile und die Templates liegen in einem eigenen Verzeichnis. Darunter gibt es Unterverzeichnisse für Schriften, Symbole und eine eigene Hierarchie für die Daten, die ihrerseits noch einmal in Raster- und Vektordaten unterteilt sind. Alle Pfadangaben im Mapfile werden relativ zum Mapfile gemacht.

Generell kann man aber natürlich auch Teile des Ganzen zentralisieren und Schriften, Symbole und auch die Daten an anderen Stellen im Dateisystem anlegen und dann absolute Angaben im Mapfile verwenden. Das ergibt natürlich nur dann Sinn, wenn mehr als eine Anwendung auf die gleichen Datenbestände zugreifen soll und man nicht große Mengen Dateien für jede Anwendung neu kopieren möchte.

Das obige Beispiel ist durchaus typisch, kann aber problematisch sein, wenn Sie verhindern wollen, dass jemand direkten Zugriff auf Ihre Daten erhalten kann. Lesen Sie den Anhang über MapServer-Sicherheit, um mehr zu diesem Thema zu erfahren.

=Änderungen=

Erst seit der Version~{3.6} des MapServers werden Änderungen systematisch festgehalten.

In diesem Abschnitt sollen die Änderungen für den Leser dieses Handbuchs nachvollziehbar sein, ohne die entsprechende Datei im Quelltextpaket des MapServers lesen zu müssen.

3.5 nach 3.6
%
 * FIXME: Ersten Eintrag in 3.6.0-Beta1 klären
 * Die Schlüsselworte =ANTIALIAS= und =FILLED=  benötigen nun einen Booleschen Parameter: =TRUE=  oder =FALSE=.
 * =MINSCALE= und =MAXSCALE=  funktionieren jetzt auch in Klassen, nicht nur in Layern.
 * In der Referenzkarte kann jetzt ein Marker angezeigt werden, wenn die Box in der Karte zu klein wird. Siehe auch die neuen Schlüsselworte =MARKER=, =MARKERSIZE= , =MAXBOXSIZE= und =MINBOXSIZE=.
 * Gekachelte OGR-Datensätze werden unterstützt
 * PHP MapScript funktioniert mit PHP 4.1.2 und 4.2.0
 * Schlüsselwort =TRANSPARENCY= für Layer hinzugefügt, das einen Wert von 0 bis 100 bekommt.
 * SWIG-Interface für Jave korrigiert
 * HTML-Legenden zusätzlich zu den bisherigen Legenden eingeführt.
 * MapServer als WMS-Server unterstützt Query-Templates zusätzlich zu den reinen plain/text-Antworten
 * Weitere Fortschritte an der Thread-Sicherheit; neuer Parameter -\-with-thread beim Kompilieren.
 * Diverse Änderungen in 'selbstgemachten' SQL-Anfragen an PostGIS
 * Capabilities-XML eines WMS-konformen MapServers liefert gruppierte Mapfile-Layer korrekter zurück
 * Das ROSA-Applet funktioniert jetzt auch mit der CGI-Version des MapServers (ohne PHP)

FIXME: liste von änderungen existiert schon an anderer stelle?

=PHP MapScript=\index{PHP MapScript}

Im Kapitel über MapScript wird ab Seite~\pageref{text:mapscript:php} im wesentlichen auf PHP MapScript eingegangen. Dieser Schwerpunkt soll hier im Anhang komplettiert werden, indem wir eine vollständige Referenz über die in PHP MapScript verwendeten Objekte einfügen.

Die folgenden Abschnitte beschreiben zuerst die Konstanten, die zur Verfügung stehen; sie sind in einer Tabelle aufgelistet.

Danach werden alle Objekte von PHP MapScript der Reihe nach aufgezählt. Sie bilden alle einen eigenen Abschnitt, zusammen mit einer Tabelle ihrer Eigenschaften und einer Beschreibung ihrer Methoden.

Da sich MapScript ständig weiterentwickelt, kann diese Referenz bestenfalls ein Schnappschuß sein. Falls Sie Diskrepanzen zwischen dem hier stehenden und PHP MapScript im tatsächlichen Einsatz feststellen, lassen Sie es uns wissen; die jeweils aktuelle Version der Dokumentation finden Sie in englischer Sprache auf der Website von DM Solutions~http:website:dmsolutions bzw. auf der Dokumentationsseite von MapServer. Wir haben versucht, uns so nah wie möglich an dieser Referenz zu orientieren.

Konstanten
Wir eröffnen die Referenz, wie es auch die englischsprachige Originaldokumentation tut: mit einer Liste von Konstanten, die in MapScript benutzt werden können.

Beachten Sie bitte, dass diese Konstanten Eigendefinitionen von MapScript sind und außerhalb von MapScript-Funktionen keine verläßlichen Werte darstellen. Zum Beispiel der folgende Code:

Vermeiden Sie das. =MS_TRUE= muß nicht zwangsweise das gleiche sein wie das in PHP eingebaute =TRUE=. Kann. Muß aber nicht. Benutzen Sie MapScript-Konstanten immer nur in Verwendung mit MapScript.

Des weiteren sind alle Konstantennamen case sensitive, das heißt, sie sind nur in der Schreibweise komplett in Großbuchstaben vorhanden.

Beachten Sie die in MapServer 4.0 neu hinzugekommenen Error-Codes am Ende der Tabelle. Diese Konstanten sind nicht sonderlich gut dokumentiert, und es existieren auch noch keine ausführlichen Anwendungsbeispiele. Die Erklärungen zu dene Fehlercodes sind daher nur sporadisch und vorerst lediglich aus den Namen der Codes abgeleitet.

Die bisher vorhandenen Konstanten für Ausgabeformate, =MS_PNG=, =MS_GIF= , =MS_JPEG= und =MS_WBMP=  sind nicht mehr vorhanden.

\begin{mmltab} {p{.28 \textwidth}p{.67 \textwidth}} {Name & Bedeutung} {PHP MapScript Konstanten} {tab:ref:mapscript:const} & Boolsche Konstanten \\ =MS_TRUE= & Ein Boolsches wahr .\\ =MS_FALSE= & Ein Boolsches falsch .\\ =MS_ON= & An. Entspricht =MS_TRUE= .\\ =MS_OFF= & Aus. Entspricht =MS_FALSE= .\\ =MS_YES= & Ja. Entspricht =MS_TRUE= .\\ =MS_NO= & Nein. Entspricht =MS_FALSE= .\\ & Maßeinheiten \\ =MS_INCHES= & Inches, im deutschen auch Zoll genannt. Entspricht grob $$2.5$$ Zentimetern\\ =MS_FEET= & Feet, im deutschen auch Fuß genannt. Entspricht grob $$30$$ Zentimetern\\ =MS_MILES= & Miles, im deutschen auch Meilen genannt. Entspricht etwa $$1.4$$ Kilometern\\ =MS_METERS= & Meter. Beachten Sie, dass es keine Konstante (und auch keine Entsprechung im Mapfile) für Zentimeter gibt.\\ =MS_KILOMETERS= & Kilometer.\\ =MS_DD= & Decimal degree, also dezimale Gradangaben.\\ =MS_PIXELS= & Pixelangaben.\\ & Layertypen \\ =MS_LAYER_POINT= & Ein Punkt-Layer\\ =MS_LAYER_LINE= & Ein Linien-Layer\\ =MS_LAYER_POLYGON= & Ein Polygon-Layer\\ =MS_LAYER_RASTER= & Ein Raster-Layer\\ =MS_LAYER_ANNOTATION= & Ein Beschriftungs-Layer\\ =MS_LAYER_QUERY= & Ein Query-Layer; solche Layer werden nicht angezeigt, sondern lediglich für Queries benutzt\\

=MS_LAYER_GRATICULE= & Ein Graticule-Layer, der ein Gitternetz anzeigt\\ & Status von Karten, Layer, Scalebars, Legenden, Klasse \\ =MS_ON= & An\\ =MS_OFF= & Nicht an, mithin: aus.\\ =MS_DEFAULT= & Voreingestellt (nur Layer)\\ =MS_EMBED= & In die Karte eingebettet (nur Legenden und Maßstäbe)\\ & Schrifttypen \\ =MS_BITMAP= & Konstante für Bitmap-Schriften\\ =MS_TRUETYPE= & Konstante für TrueType-Schriften\\ & Labelpositionen \\ =MS_UL= & Das Label befindet sich links über dem Bezugspunkt\\ =MS_CL= & Das Label befindet sich links vom Bezugspunkt\\ =MS_LL= & Das Label befindet sich links unter dem Bezugspunkt\\ =MS_UC= & Das Label befindet sich über dem Bezugspunkt\\ =MS_CC= & Das Label befindet sich direkt auf dem Bezugspunkt\\ =MS_LC= & Das Label befindet sich unter dem Bezugspunkt\\ =MS_UR= & Das Label befindet sich rechts über dem Bezugspunkt\\ =MS_CR= & Das Label befindet sich rechts vom Bezugspunkt\\ =MS_LR= & Das Label befindet sich rechts unter dem Bezugspunkt\\ =MS_AUTO= & Das Label wird automatisch gesetzt\\

& Schriftgrößen für Bitmap-Schriten \\ =MS_TINY= & Winzige eingebaute Bitmap-Schrift\\ =MS_SMALL= & Kleine eingebaute Bitmap-Schrift\\ =MS_MEDIUM= & Mittelgroße eingebaute Bitmap-Schrift\\ =MS_LARGE= & Große eingebaute Bitmap-Schrift\\ =MS_HUGE= & Riesige eingebaute Bitmap-Schrift\\ & Shapetypen \\ =MS_SHAPE_POINT= & Ein Punkt-Shape\\ =MS_SHAPE_LINE= & Ein Linien-Shape\\ =MS_SHAPE_POLYGON= & Ein Polygon-Shape\\ =MS_SHAPE_NULL= & Ein leeres Shape\\ & Shapefiletypen \\ =MS_SHP_POINT= & Ein Punkt-Shapefile\\ =MS_SHP_ARC= & Ein Arc-Shapefile\\ =MS_SHP_POLYGON= & Ein Polygon-Shapefile\\ =MS_SHP_MULTIPOINT= & Ein Multipunkt-Shapefile\\ & Query-Ergebnisse und Joins \\ =MS_SINGLE= & Query, die nur einzelne Ergebnisse zuläßt\\ =MS_MULTIPLE= & Query, die mehrere Ergebniss zuläßt\\ & Querymap-Typen \\ =MS_HILITE= & Querymap, in der die gewählten Elemente in einer eigenen Farbe dargestellt werden\\ =MS_NORMAL= & Querymap, die den Inhalt normal darstellt\\ =MS_SELECTED= & Querymap, in der die gewählten Elemente und sonst nichts im jeweiligen Layer dargestellt werden\\ & Connections -- Anbindungen an Datenquellen \\ =MS_INLINE= & Ein Inline-Feature\\ =MS_SHAPEFILE= & Anbindung an ein Shapfile\\ =MS_TILED_SHAPEFILE= & Anbindung an ein gekacheltes Shapefile\\ =MS_SDE= & Anbindung an eine ESRI ArcSDE-Datenbank\\ =MS_OGR= & Anbindung an ein von OGR unterstütztes Datenformat\\ =MS_TILED_OGR= & Anbindung an ein gekacheltes, von OGR unterstütztes Datenformat\\ =MS_WMS= & Anbindung an einen OGC-konformen Mapserver\\ =MS_POSTGIS= & Anbindung an eine PostGIS-Datenbank\\ =MS_ORACLESPATIAL= & Anbindung an eine Oracle Spatial Datenbank\\ & Ausgabeformate \\ =MS_PNG= & Ein Bild im .png -Format\\ =MS_GIF= & Ein Bild im .gif -Format\\ =MS_JPEG= & Ein Bild im .jpg -Format\\ =MS_WBMP= & Ein Bild im .bmp -Format\\ & Fehlercodes \\ =MS_NOERR= & Kein Fehler ist aufgetreten.\\ =MS_IOERR= & Ein Fehler bei der Ein- oder Ausgabe ist aufgetreten.\\ =MS_MEMERR= & Ein Speicherfehler ist aufgetreten.\\ =MS_TYPEERR= & Es gab einen Fehler bei der Definition eines Typs.\\ =MS_SYMERR= & Ein Symbolfehler ist aufgetreten.\\ =MS_REGEXERR= & Es gab einen Fehler in einem regulären Ausdruck.\\ =MS_TTFERR= & Es gab einen Fehler im Zusammenhang mit TrueType-Schriften.\\ =MS_DBFERR= & Es gab einen Fehler im Zusammenhang mit einer DBF-Datei.\\ =MS_GDERR= & Es gab einen Fehler im Zusammenhang mit der Grafikbibliothek GD.\\

=MS_EOFERR= & Ein Fehler ist aufgetreten, weil eine Datei (z.B. das Mapfile) eher zuende war als erwartet. Tritt gerne dann auf, wenn man das abschließende =END= vergißt.\\ =MS_PROJERR= & Es gab einen Fehler im Zusammenhang mit der Projektionsbibliothek.\\ =MS_MISCERR= & Es gab einen nicht näher definierten Fehler.\\ =MS_CGIERR= & Es ist ein CGI-Fehler aufgetreten.\\ =MS_WEBERR= & Es ist ein Web-Fehler aufgetreten.\\ =MS_IMGERR= & Ein Fehler ist bei der Verarbeitung eines Bildes aufgetreten.\\

=MS_JOINERR= & Es ist ein Fehler in einem Join aufgetreten.\\ =MS_NOTFOUND= & Es gab einen Fehler, weil ein Objekt nicht gefunden werden konnte.\\ =MS_SHPERR= & Ein Shape-Fehler ist aufgetreten.\\ =MS_PARSEERR= & Beim Parsen ist ein Fehler aufgetreten\\ =MS_SDEERR= & Es ist ein Fehler im Zusammenhang mit der Verbindung mit einer ArcSDE-Datenbank aufgetreten.\\ =MS_OGRERR= & Bei der Vererbeitung einer OGR-Verbindung ist ein Fehler aufgetreten.\\ =MS_QUERYERR= & Bei einer Query ist ein Fehler aufgetreten.\\ =MS_WMSERR= & Es gab einen Fehler im Zusammenhang mit WMS.\\ =MS_WMSCONNERR= & Es gab einen Fehler im Zusammenhang mit einer WMS-Verbindung.\\ =MS_ORACLESPATIALERR= & Es ist ein Fehler im Zusammenhang mit der Verbindung mit einer Oracle Spatial-Datenbank aufgetreten.\\ =MS_WFSERR= & Es gab einen Fehler im Zusammenhang mit WFS.\\ =MS_WFSCONNERR= & Es gab einen Fehler im Zusammenhang mit einer WFS-Verbindung.\\ =MS_MAPCONTEXTERR= & Es ist ein Fehler bei der Verarbeitung eines Map Context aufgetreten.\\ =MS_HTTPERR= & Ein Fehler bei einer HTTP-Verbindung ist aufgetreten. \end{mmltab}

Allgemeine Funktionen
Es gibt es nur zwei allgemeine Funktion, die nicht mit einem Objekt in PHP MapScript assoziiert sind.

Diese Funktion liefert die Version des benutzten MapServers (oder vielmehr: von MapScript) als Zeichenkette zurück. In diesem String enthalten sind auch alle Eigenschaften aufgelistet, die die jeweilige Installation von MapScript auszeichnen; auf diese Weise kann man die Installation auf vorhandene Features prüfen.

Der fertige String hat das gleiche Aussehen wie die Zeichenkette, die durch den Befehl =mapserv -v= auf der Kommandozeile ausgegeben wird.

Die zweite Funktion lautet:

Diese Funktion öffnet das übergebene Mapfile und läßt es duch den Parser bearbeiten, der in MapScript die Mapfiles verarbeitet.

Im Grunde ist das ein interner Schritt, der für die Bearbeitung eines Mapfile notwendig ist, und nach draußen nicht wirklich einen unmittelbaren Sinn ergibt. Die Rückgabe ist ein Array, das alle Token des Mapfiles enthält. Token ist ein Begriff aus dem Compiler- bzw. Parserbau und bezeichnet die kleinsten Einzelelemente einer Sprache.

mapObj
(1)\index{mapObj}

Dieses Objekt geht mit Mapfiles um. Dementsprechend wird es in den meisten MapScript-Applikationen benutzt.

\subsubsection*{Konstruktor}

Eine neues mapObj entsteht, wenn ein Mapfile geladen wird. Das sieht folgendermaßen aus:

Dieser Konstruktor gibt ein neues Objekt zurück, dessen Eigenschaften denen des angegebenen Mapfiles entspricht.

Der zweite Parameter ist optional. Normalerweise können alle Pfade im Mapfile wie =SHAPEPATH=, =FONTSET= und so weiter relativ zum Mapfile angegeben werden. Wenn der zweite Parameter im Konstruktor ein gültiger Pfad im System ist, werden ab diesem Zeitpunkt alle relativen Angaben als relativ zu diesem Pfad angesehen.

\subsubsection*{Eigenschaften}

Jedes mapObj verfügt über die folgenden Eigenschaften. Alle können zumindest ausgelesen werden; wenn Sie nicht von außen gesetzt werden können, so ist das bei den betreffenden Eigenschaften explizit vermerkt.

\begin{mmltab} {p{.20 \textwidth}p{.20 \textwidth}p{.55 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von mapObj} {tab:ref:mapobj:prop} int & numlayers & Anzahl der Layer im Mapfile. Kann nur gelesen werden\\ string & name & Name der Karte\\ int & status & Status der Karte; für mögliche Werte siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const}\\ int & width & Breite der Karte in Pixeln\\ int & height & Höhe der Karte in Pixeln\\ int & transparent & Soll der Hintergrund der Karte transparent sein?\\ int & interlace & Soll die Karte interlaced sein?\\ int & imagetype & Welches Bildformat soll die Karte haben? Siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const}\\ int & imagequality & Bildqualität für Bilder im Format =MS_JPEG=, sollte zwischen 0 und 95 liegen\\ int & resolution & Auflösung der Karte in Pixeln pro Inch; Voreinstellung ist 72\\ rectObj & extent & Extents der Karte\\

int & units & Einheiten für die Karte; Siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const}\\ double & scale & Der aktuelle =SCALE= der Karte; kann nur gelesen werden\\ string & shapepath & Der =SHAPEPATH= der Karte\\ int & keysizex & Breite eines Legendensymbols in Pixeln\\ int & keysizey & Höhe eines Legendensaymbols in Pixeln\\ int & keyspacingx & Horizontaler Abstand zweier Legendensymbole\\ int & keyspacingy & Vertikaler Abstand zweier Legendensymbole\\ webObj & web & Die Web-Sektion im Mapfile als Objekt\\ referenceMapObj & reference & Die Referenzkarten-Sektion im Mapfile als Objekt\\ colorObj & imagecolor & Die Hintergrundfarbe der fertigen Karte\\ scalebarObj & scalebar & Das Maßstabs-Objekt des Mapfiles\\ legendObj & legend & Das Legenden-Objekt des Mapfiles\\ \end{mmltab}

\subsubsection*{Methoden}

Die folgenden Methoden sind jedem mapObj zueigen:

Setzt den Wert für eine Eigenschaft im Objekt neu.

Fügt der Farbpalette der Karte eine neue Farbe hinzu. Gibt den Index der Farbe in der Farbpalette zurück.

Gibt für das Symbol mit dem gegebenen Namen den Index des Symbols im Mapfile zurück.

Berechnet den Scale der Karte neu, und weist ihn der Eigenschaft =scale= des Objektes zu.

Gibt eine Referenz auf ein leeres imageObj zurück.

Rendert die Karte in einem Puffer vom Typ imageObj und liefert eben dieses Objekt zurück.

Rendert die QueryMap in einem Puffer vom Typ imageObj und liefert eben dieses Objekt zurück.

Rendert die Legende in einem Puffer vom Type imageObj und liefert eben dieses Objekt zurück.

Rendert die Referenzkarte in einem Puffer vom Typ imageObj und liefert eben dieses Objekt zurück.

Rendert den Maßstab in einem Puffer vom Typ imageObj und liefert eben dieses Objekt zurück.

Bettet die Legende in die Karte ein.

Intern wird die Legende dem Labelcache hinzugefügt, also nach allen Features als Label gezeichnet. Daher sollte =drawlabelcache= aufgerufen werden, damit die Legende tatsächlich gezeichnet wird.

Bettet den Maßstab in die Karte ein.

Alle zusätzlichen Kommentare zu =embedLegend= gelten auch hier.

Rendert den LabelCache für eine Karte. Falls ein Fehler auftritt, liefert diese Funktion =-1= zurück.

Liefert den Layer mit dem betreffenden Index innerhalb des Mapfiles zurück. Der erste Layer hat die Nummer =0=.

Liefert den Layer mit dem angegebenen Namen zurück.

Liefert ein colorObj zurück, das den =i= -ten Eintrag in der Farbpalette repräsentiert.

Setzt die Extents der Karte neu. Kann zum Hineinzoomem 'von Hand' verwendet werden.

Zoomt um den Zoomfaktor in die Karte hinein. Ein Zoomfaktor von =1= verschiebt die Karte lediglich, negative Werte zoomen heraus. Das Punktobjekt repräsentiert die Koordinaten des Klicks in der Karte in Pixelkoordinaten; die anderen Angaben sind die Breite und die Höhe des Kartenbildes in Pixeln und die Extents in den Einheiten des Mapfiles.

Zoomt auf einen rechteckigen Ausschnitt innerhalb der aktuellen Extents. Das =recht\-eck= ist ein Objekt, dessen Werte in Pixeln anzugeben sind. Dazu kommen die Breite und die Höhe der Karte in Pixeln, sowie deren Extents.

Zoomt auf den angeklickten Punkt, sodass die Karte in einem bestimmten =SCALE= dargestellt wird. Alle darauf folgenden Parameter sind analog zu den anderen Zoomfunktionen.

Als letzter Paramter kann dieser Funktion auch noch ein rectObj übergeben werden, das maximale Extents definiert, aus denen nicht herausgezoomt werden darf. Eintragen von =MAXSCALE= im Mapfile leistet jedoch das Gleiche.

Stellt eine Anfrage an alle dafür eingerichteten Layer in der Karte (d.h. in allen Classes bzw. Layern, in denen ein =TEMPLATE= -Eintrag vorhanden ist) am angegebenen Punkt. Dieser Punkt ist in Kartenkoordinaten anzugeben, nicht in Pixeln -- höchstwahrscheinlich müssen Sie hier nach einem Mausklick in die Karte von Hand eine Umrechnung vornehmen.

Der Modus ist entweder =MS_SINGLE= oder =MS_MULTIPLE=. Der =puffer= beachtet die Werte im Mapfile, wenn der kleiner als Null ist, es kann jedoch ein Puffer (in den Einheiten der Karte) übergeben werden, der als Radius um den Punkt dient; auf diese Weise kann man Kreisförmige Abfragen realisieren.

Wenn es Suchergebnisse gab, liefert diese Funktion =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=

Führt eine Query durch, analog zur eben genannten Funktion. Das Rechteck muß in den Koordinaten der Karte vorliegen.

Führt eine Query anhand eines beliebigen Shapes durch, das als shapeObj vorliegen muß. Restliches Vorgehen wie bei den beiden vorherigen Funktionen.

Führt eine Query durch anhand bereits vorhandener Query-Resultate des Layers =slayer=. Im Moment müssen diese Resultate leider noch gezwungenermaßen in einem Polygonlayer liegen. Das restliche Vorgehen entspricht den vorherigen Query-Funktionen.

Speichert den aktuellen Stand des Mapfiles in einer Datei mit dem gegebenen Dateinamen ab. Falls ein Fehler dabei auftritt, gibt diese Funktion =-1= zurück.

Liefert die Projektion der Karte in einem String zurück, der den Optionen für die Projektionsbibliothek proj.4 entspricht. Gibt bei einem Fehler =MS_FALSE= zurück.

Setzt die Projektion für die Karte. Die Parameter werden als Liste von Parameter für die Projektionsbibliothek proj.4 übergeben, die durch Kommata voneinander getrennt sind.

Der zweite Parameter kann entweder =MS_TRUE= oder =MS_FALSE=  sein und bestimmt, ob nach dem Setzen der Projektion die Extents und Einheiten der Karte neu gesetzt werden sollen. Das ist normalerweise eine gute Idee.

Liest die Daten aus einem =METADATA= -Bereich in der Web-Sektion des Mapfiles aus. Sucht nach einem Eintrag =name= und gibt den entsprechenden String zurück, beziehungsweise einen leeren String, wenn es den Wert nicht gibt.

Setzt einen Metadaten-Eintrag in der Web-Sektion des Mapfiles. Gibt bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

Gibt ein Array aller Layernamen zurück, die sich in der =GROUP= mit dem Namen =gruppenname=  befinden.

Gibt ein Array mit den Namen aller =GROUP= s zurück, die sich im Mapfile befinden.

Liefert ein Array zurück, das die Namen aller Layer im Mapfile enthält.

Die Layer, die zuerst in Mapfile stehen, werden zuerst gezeichnet, sind in der fertigen Karte also die untersten Layer. Mit dieser Funktion kann man einen Layer, dessen Index im Mapfile man kennen muß, in dieser Hierarchie einen Schritt nach oben schieben. Liefert =MS_TRUE= zurück, wenn das Verschieben gelungen ist.

Das gleiche wie =moveLayerUp=, aber in die andere Richtung.

Gibt ein Array zurück, indem sich die Layer-Indizes in der Reihenfolge befinden, in der sie gezeichnet werden.

Setzt ein neues Array, wie bei =getLayersDrawingOrder= beschrieben. Gibt bei Erfolg =MS_TRUE= zurück.

Mit dieser Funktion wird das Template, das in der Web-Sektion des Mapfiles definiert ist, abgearbeitet (wie man es vom MapServer CGI her kennt), und das Ergebnis wird in einem Puffer zurückgeliefert. Wenn der letzte Parameter in der Funktion auf =MS_TRUE= gesetzt wird, werden auch die Bilder generiert und Bilder-Tags wie =[img]=  und so weiter mit korrekten URLs ausgetauscht.

Das Array =params= ist ein assoziatives Array; mit den Schlüssel/Werte-Paaren können eigene Tags im Template mit Inhalten gefüllt werden.

Arbeitet die Querytemplates ab und gibt das Ergebnis in einem Puffer zurück.

Siehe =processTemplate=.

Arbeitet die Templates für HTML-Legenden ab und gibt das Ergebnis in einem Puffer zurück.

Siehe =processTemplate=.

Setzt für das Mapfile ein neues =SYMBOLSET=.

Gibt die Anzahl der Symbole zurück, die für ein Mapfile definiert sind.

layerObj
(2)\index{layerObj}

Dieses Objekt entspricht einer Layer-Sektion aus dem Mapfile. Layer werden entweder aus dem Mapfile heraus referenziert, oder mit einem Konstruktor von Hand generiert

\subsubsection*{Konstruktor}

Mapfile-Layer werden (wenn sie nicht aus einem bestehenden mapObj heraus referenizert werden) immer im Kontext eines bereits existenten mapObj erstellt:

Der neue Layer wird an das untere Ende der Hierarchie eingefügt; er wird in der fertigen Karte also zuoberst gezeichnet.

\subsubsection*{Eigenschaften}

Jedes layerObj verfügt über die folgenden Eigenschaften. Alle können zumindest ausgelesen werden; wenn Sie nicht von außen gesetzt werden können, so ist das bei den betreffenden Eigenschaften explizit vermerkt.

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von layerObj} {tab:ref:layerobj:prop} int & numclasses & Anzahl der Classes in einem Layer; kann nur gelesen werden\\ int & index & Die Nummer des Layers innerhalb der Layer-Hierarchie des Mapfiles. Kann nur gelesen werden\\ int & status & Der Status des Layers. Siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const} für mögliche Werte\\ string & classitem & Das =CLASSITEM= für den Layer\\ string & name & Der Name des Layers\\ string & group & Die =GROUP=, in der sich der Layer befindet\\ string & data & Die Datenquelle für den Layer\\ int & type & Der Datentyp des Layers. Siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const} für mögliche Werte\\ double & tolerance & Der Toleranzwert für Punkt-Queries\\ int & toleranceunits & Die Einheit, in der =tolerance= angegeben ist\\ double & symbolscale & Der =SCALE=, bei dem Symbole in 100\ double & minscale & Der =MINSCALE= des Layers\\ double & maxscale & Der =MAXSCALE= des Layers\\ double & labelminscale & Der minimale =SCALE=, ab dem Labels im Layer angezeigt werden sollen\\ double & labelmaxscale & Der maximale =SCALE=, bis zu dem Labels im Layer angezeigt werden sollen\\ int & maxfeatures & Maximale Anzahl von Features, die in einem Layer dargestellt werden soll\\ int & offsite & Für Rasterlayer. Die Nummer der Farbe in der Farbpalette der Bilder, die transparent geschaltet werden soll\\ int & annotate & Soll der Layer beschriftet werden?\\ int & transform & Wenn =MS_TRUE= (Voreinstellung), werden die Daten in das Koordinatensystem des Layers transformiert\\ int & labelcache & Gibt an, ob Labels gecached werden ujnd später mit allen Labels gemalt werden sollen, oder sie zusammen mit den Features gezeichnet werden sollen. Ist =MS_ON= oder =MS_OFF= \\ int & postlabelcache & Wenn =MS_TRUE=, wird dieser Layer nach allen Labeln gezeichnet\\ string & labelitem & Die Spalte in der .dbf -Datei, die für Beschriftungen verwendet werden soll\\ string & labelsizeitem & Die Spalte in der .dbf -Datei, die für die Größe der Beschriftungen zurate gezogen werden soll\\ string & labelangleitem & Die Spalte in der .dbf -Datei, die für die Rotation von Beschriftungen zurate gezogen werden soll\\ string & tileindex & Index-Datei für gekachelte Daten\\ string & tileitem & Name der Spalte in der .dbf -Datei des Index, in dem sich die Dateinamen der einzelnen Kacheln finden\\ string & header & Dateiname des =HEADER= -Templates\\ string & footer & Dateiname des =FOOTER= -Templates\\ int & connectiontype & Die Art der =CONNECTION= (Datenquelle)\\ string & connection & Die genauen Parameter der =CONNECTION= (Datenquelle)\\ string & filteritem & Das Item, anhand dessen gefiltert werden soll\\ string & template & Das =TEMPLATE= für diesen Layer \end{mmltab}

\subsubsection*{Methoden}

Jedem layerObj sind die folgenden Methoden zueigen.

Setzt den Wert für eine Eigenschaft im Objekt neu.

Rendert den Layer in das Bildobjekt =bild= und fügt eventuelle Labels in den Labelcache ein. Liefert =-1= bei Fehlern zurück.

Rendert den Layer in der QueryMap in das Bild-Objekt =bild=. Liefert =-1= bei Fehlern zurück.

Gibt ein Objekt zurück, dass der Class in diesem Layer entspricht; dabei ist =0= die erste Class, =1=  die zweite und so weiter.

Stellt eine Anfrage an alle dafür eingerichteten Classes in dem Layer.

Entspricht =queryByPoint= im mapObj.

Führt eine Query durch, analog zur eben genannten Funktion. Das Rechteck muß in den Koordinaten der Karte vorliegen.

Führt eine Query anhand eines beliebigen Shapes durch, das als shapeObj vorliegen muß. Restliches Vorgehen wie bei den beiden vorherigen Funktionen.

Führt eine Query durch anhand bereits vorhandener Query-Resultate des Layers =slayer=. Im Moment müssen diese Resultate leider noch gezwungenermaßen in einem Polygonlayer liegen. Das restliche Vorgehen entspricht den vorherigen Query-Funktionen.

Stellt eine Anfrage nach allen Shapes, die sich in den momentanen Extents der Karte befinden. Ansonsten analog zu den vorhergehenden Query-Funktionen.

Setzt einen =FILTER= -Ausdruck für den Layer; kommt beispielsweise bei PostGIS-Layern zum Einsatz.

Liefert die Projektion des Layers in einem String zurück, der den Optionen für die Projektionsbibliothek proj.4 entspricht. Gibt bei einem Fehler =MS_FALSE= zurück.

Setzt die Projektion für den Layer. Die Parameter werden als Liste von Parameter für die Projektionsbibliothek proj.4 übergeben, die durch Kommata voneinander getrennt sind.

Liefert die Anzahl der Resultate der letzten Query für den Layer zurück.

Gibt ein Resultat-Objekt aus dem Layer zurück. Ergibt erst nach einer Query Sinn. Die Anzahl vorhandener Resultate kann mit =getNumResult= abgefragt werden. Die Funktion liefert =0= zurück, falls der Index ungültig ist.

'Öffnet' den Layer; dient als Vorbereitung, um später =getShape= benutzen zu können. Gibt bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

Schließt einen Layer, den man vorher mit =open= geöffnet hat.

Liefert das shapeObj an den angegebenen Indizes zurück. =tileindex= wird nur für tiled shapefiles benutzt; handelt es sich nicht um ein tiled shapefile, übergibt man an dieser Stelle =-1=.

Fügt dem Layer das Feature =shape= hinzu. Gibt bei einem Fehler =-1= zurück.

Liest die Daten aus einem =METADATA= -Bereich des Layers aus. Sucht nach einem Eintrag =name= und gibt den entsprechenden String zurück, beziehungsweise einen leeren String, wenn es den Wert nicht gibt.

Setzt einen Metadaten-Eintrag im Layer. Gibt bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

classObj
\index{classObj}

Dieses Objekt repräsentiert eine Class aus einem Layer in einem Mapfile. Neue Objekte vom Typ classObj können entweder aus existierenden Objekten vom Typ layerObj herausgefischt werden, oder aber im Kontext eines solchen Layers neu angelegt werden.

Beachten Sie bitte, dass die darstellenden Eigenschaften einer Class in ein eigenes Objekt gewandert sind, das Style-Objekt. Details zu Styles im Mapfile finden Sie in Abschnitt~\ref{text:mapfile:styles}, das styleObj in MapScript wird weiter unten behandelt.

\subsubsection*{Konstruktor}

Neue classObj-Objekte können neu angelegt werden mit:

Es muß also offensichtlich ein layerObj vorhanden sein, in dem man seine neue Class anlegen kann. Die neue Class wird an das Ende der Liste der Classes eingefügt, wird also als letztes darauf geprüft, ob sie zur Darstellung eines Features geeignet ist.

Ist die letzte Class in einem Layer eine Catch-All-Class, ergibt das Einfügen einer neuen Class nicht viel Sinn. In diesem Fall muß man überprüfen, ob man nicht zuerst an den Expressions der bisher vorhandenen Classes noch etwas ändern bzw. ob man nicht schon vorhandene Classes löschen muß.

\subsubsection*{Eigenschaften}

Jedes classObj verfügt über die folgenden Eigenschaften. Alle können zumindest ausgelesen werden; wenn Sie nicht von außen gesetzt werden können, so ist das bei den betreffenden Eigenschaften explizit vermerkt.

\begin{mmltab} {p{.10 \textwidth}p{.30 \textwidth}p{.55 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von classObj} {tab:ref:classobj:prop} string & name & Name der Class\\

int & status & Der Status der Class\\ int & minscale & Minimaler Scale, ab dem die Class Verwendung finden soll.\\ int & maxscale & Maximaler Scale, bis zu dem die Class Verwendung finden soll.\\ string & template & Das Query-Template für diese Class \\ labelObj & label & Das Label für diese Class\\ int & numstyles & Die Anzahl der Styles in dieser Class \end{mmltab}

\subsubsection*{Methoden}

Die folgenden Methoden sind jedem classObj zueigen.

Setzt den Wert für eine Eigenschaft im Objekt neu.

Setzt die =EXPRESSION= für die Class neu.

Setzt den =TEXT= für die Class neu. Auf diese Weise können Sie alle Features, die mit den Angaben in dieser Class dargestellt werden, mit einem fixen Text bechriften.

Malt das Legendensymbol für die Class in der gewählten Größe in das imageObj =bild= an die Stelle, die durch die Koordinaten angegeben ist. Liefert bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

Zeichnet das Legendsymbol für diese Class in ein eigenes neues imageObj.

Liefert das Styleobjekt Nummer =index= zurück.

styleObj
\index{styleObj}(3)

Dieses mit MapServer 4.0 neu eingeführte Objekt übernimmt alle darstellenden Eigenschaften, die in vorherigen Version Bestandteil einer Class waren. Style-Objekte befinden sich immer innerhalb von Classes. Styles können mit einem Konstruktor neu erzeugt und einer Class hinzugefügt werden. Eine Class kann mehr als einen Style haben. Mehr Informationen über das Style-Objekt finden Sie ab Seite~\pageref{text:mapfile:styles}.

\subsubsection*{Konstruktor}

Neue styleObj-Objekte können neu angelegt werden mit:

Es muß also offensichtlich ein classObj vorhanden sein, in dem man seinen neuen Style anlegen kann. Der neu erzeugte Style wird an das Ende der Liste der Styles in der Class eingefügt und wird somit auf alle anderen Style in der Class gezeichnet.

\subsubsection*{Eigenschaften}

Jedes styleObj verfügt über die folgenden Eigenschaften. Alle können zumindest ausgelesen werden; wenn Sie nicht von außen gesetzt werden können, so ist das bei den betreffenden Eigenschaften explizit vermerkt.

Die meisten dieser Eigenschaften waren bisher Bestandteil der classObj-Objekte. Da die Style-Objekte alle bisherigen Overlay-Funktionalitäten obsolet macht, sind diese Eigenschaften hier nicht mehr zu finden.

\begin{mmltab} {p{.10 \textwidth}p{.30 \textwidth}p{.55 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von classObj} {tab:ref:styleobj:prop} string & name & Name der Class\\

colorObj & color & Farbe, in der Features gezeichnet werden sollen\\ colorObj & backgroundcolor & Hintergrundfarbe für nicht-transparente Symbole\\ colorObj & outlinecolor & Umrißfarbe für Polygone\\ int & symbol & Nummer des verwendeten Symbols\\ string & symbolname & Name des verwendeten Symbols\\ int & size & Größe des Symbols\\ int & minsize & Mindestgröße des Symbols\\ int & maxsize & Maximalgröße ds Symbols \\ int & offsetx & Offset des Symbols in Pixeln in X-Richtung \\ int & offsety & Offset des Symbols in Pixeln in Y-Richtung \end{mmltab}

\subsubsection*{Methoden}

Die folgenden Methoden sind jedem styleObj zueigen.

Setzt den Wert für eine Eigenschaft im Objekt neu. Im Fehlerfall ist die Rückgabe der Funktion =-1=.

imageObj
(4)\index{imageObj}

Bei imageObj handelt es sich um einen Puffer mit Bilddaten. Solche Bilder werden ausschließlich von mapObj-Methoden kreiert.

Diese Datenpuffer werden erst dann mit Dateinamen assoziiert, wenn entsprechende Methoden der Klasse aufgerufen werden, um die Daten als Bilddatei abzuspeichern. Dieses Abspeichern hat sich übrigens mit Version 4.0 des MapServers in der Notation geändert, da es jetzt die =OUTPUTFORMAT= -Sektion gibt, mit der die Eigenschaften des zu produzierenden Bildes detailliert bestimmt werden können. Mehr dazu finden Sie weiter unten.

\subsubsection*{Konstruktor}

Diese Klasse kennt keinen von außen zugänglichen Konstruktor.

\subsubsection*{Eigenschaften}

Die Klasse imageObj kennt die folgenden Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von imageObj} {tab:ref:imageobj:prop} int & width & Breite des Bildes in Pixeln. Diese Eigenschaft kann nur gelesen werden.\\ int & height & Höhe des Bildes in Pixeln. Diese Eigenschaft kann nur gelesen werden.\\ string & imagepath & =IMAGEPATH= aus der Web-Sektion des Mapfiles.\\ string & imageurl & =IMAGEURL= aus der Web-Sektion des Mapfiles. \end{mmltab}

\subsubsection*{Methoden}

Die Objekte der Klasse imageObj kennen die folgenden Methoden:

Schreibt das Bild-Objekt in eine Datei mit dem Namen =dateiname=. Wenn dieser Name leer ist, wird der Inhalt nach =stdout= geschrieben; in diesem Fall sollte man die PHP-Funktion =header=  benutzen, um den content-type  für die Daten korrekt zu setzen.

Vor MapScript 4.0 folgten weitere Parameter, die die Eigenschaften des Bildes bestimmten. Diese Angaben werden nun aus dem aktuellen =OUTPUTFORMAT= der Karte gelesen.

Entspricht der vorherigen Funktion, mit dem Unterschied, dass das Bild jetzt in das Verzeichnis =IMAGEPATH= der Web-Sektion geschrieben wird. Die Funktion liefert einen URL zurück, auf den man sich in einem HTML-Link beziehen kann. Dieser URL entspricht dem =[img]= -Tag aus dem HTML-Template des CGI-MapServers.

Auch hier gilt, dass die ganzen Funktionsparameter von MapServer 3.6 und älter wegfallen und die Einstellungen aus dem aktuellen =OUTPUTFORMAT= übernommen werden.

Fügt das Bild =quelle= in das imageObj ein. Mit =transparent= wählt man den Index der Farbe in der Palette des Bildes, die transparent sein soll; falls keine Farbe transparent sein soll, übergibt man hier =-1=.

Die letzten beiden Parameter sind optional. Werden sie nicht angegeben, wird das Quellbild an der linken oberen Ecke des imageObj orientiert. Werden die beiden Werte jedoch benutzt, geben sie die Koordinaten im Bild an, an die das Bild stattdessen positioniert werden soll.

Zerstört das imageObj und gibt alle mit ihm zusammenhängenden Resourcen frei.

labelObj
(5)\index{labelObj}

Objekte dieser Klasse sind immer in andere Klassen eingebettet und können über diese referenziert werden.

\subsubsection*{Konstruktor}

labelObj verfügt nicht über einen von außen zugänglichen Konstruktor.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften sind Teil jedes Objektes vom Typ imageObj:

\begin{mmltab} {p{.10 \textwidth}p{.30 \textwidth}p{.55 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von labelObj} {tab:ref:labelobj:prop} string & font & Font-Alias für die Schriftart des Labels\\ int & type & Typ der Schrift (Bitmap oder TrueType)\\ int & color & Farbe des Labels\\ int & outlinecolor & Umrißfarbe des Labels\\ int & shadowcolor & Farbe für einen Schattenwurf des Labels\\ int & shadowsizex & Verschiebung des Schattens in horizontaler Richtung\\ int & shadowsizey & Verschiebung des Schattens in vertikaler Richtung\\ int & backgroundcolor & Hintergrundfarbe für das Label\\ int & backgroundshadowcolor & Farbe für einen Schattenwurf des Hintergrunds\\ int & backgroundshadowsizex & Verschiebung des Schattens in horizontaler Richtung\\ int & backgroundshadowsizey & Verschiebung des Schattens in vertikaler Richtung\\ int & size & Größe der Beschriftung\\ int & minsize & Minimale Größe der Beschriftung\\ int & maxsize & Maximale Größe der Beschriftung\\ int & position & Position der Beschriftung. Siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const} für mögliche Werte\\ int & offsetx & Horizontaler Offset zu dieser Position\\ int & offsety & Vertikaler Offset zu dieser Position\\ double & angle & Winkel für die Rotation des Labels\\ int & autoangle & Soll das Label am Feature ausgerichtet werden?\\ int & buffer & Abstand in Pixeln um das Label herum\\ int & antialias & Soll das Label Antialiased sein?\\

int & minfeaturesize & Mindestgröße, die ein Feature haben muß, um beschriftet zu werden\\

int & mindistance & Minimaler Abstand zwischen zwei Labels gleichen Inhalts\\ int & partials & Sollen Labels auch dann sichtbar sein, wenn sie nur teilweise Beschriftungen sind?\\ int & force & Soll die Anzeige des Labels trotz eventueller Kollisionen erzwungen werden? \end{mmltab}

\subsubsection*{Methoden}

Diese Klasse kennt lediglich die =set= -Methode:

Setzt den Wert für eine Eigenschaft im Objekt neu.

webObj
(6)\index{webObj}

Diese Klasse entspricht der Web-Sektion im Mapfile, die das interne Verhalten und seine Kommunikation mit der Außenwelt steuern. Objekte dieser Klasse sind immer Bestandteil von mapObj und können nicht von Hand erstellt werden.

\subsubsection*{Konstruktor}

webObj verfügt nicht über einen von außen zugänglichen Konstruktor.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften sind Teil jedes Objektes vom Typ webObj:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von webObj} {tab:ref:webobj:prop} string & log & Name des Logdatei für dieses Mapfile\\ string & imagepath & Der =IMAGEPATH= der Karte\\ string & imageurl & Der =IMAGEURL= der Karte\\ string & template & Das =TEMPLATE= für die Karte\\ string & header & Der =HEADER= für die Karte\\ string & footer & Der =FOOTER= für die Karte\\ string & empty & URL oder Dateiname für eine Seite, die aufgerufen wird, wenn es keine Suchergebnisse bei einer Query gab. Kann nur gelesen werden\\ string & error & URL oder Dateiname für eine Seite, die aufgerufen wird, wenn es einen Fehler gab. Kann nur gelesen werden\\ string & mintemplate & Anderes =TEMPLATE= für den Fall, dass =MINSCALE=  unterschritten wird\\ string & maxtemplate & Anderes =TEMPLATE= für den Fall, dass =MAXSCALE=  überschritten wird\\ double & minscale & Minimaler =SCALE= für die Karte\\ double & maxscale & Maximaler =SCALE= für die Karte\\

\end{mmltab}

\subsubsection*{Methoden}

Diese Klasse kennt lediglich die =set= -Methode:

Setzt den Wert für eine Eigenschaft im Objekt neu.

referenceMapObj
(7)\index{referenceObj}

Diese Klasse entspricht der Sektion =REFERENCEMAP= im Mapfile, die das interne Verhalten und seine Kommunikation mit der Außenwelt steuern. Objekte dieser Klasse sind immer Bestandteil von mapObj und können nicht von Hand erstellt werden.

\subsubsection*{Konstruktor}

referenceMapObj verfügt nicht über einen von außen zugänglichen Konstruktor.

\subsubsection*{Eigenschaften}

referenceMapObj verfügt über die folgenden Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von referencemapObj} {tab:ref:referencemapobj:prop} string & image & Dateiname des Bildes, das der Referenzkarte zugrunde liegt\\ int & width & Breite des Bildes in Pixeln\\ int & height & Höhe des Bildes in Pixeln\\ int & status & Status der Referenzkarte\\ rectObj & extent & Extents der Referenzkarte, können nur gelesen werden\\ ColorObj & color & Farbe der Markierungsfläche in der Referenzkarte; kann nur gelesen werden\\ ColorObj & outlinecolor & Umrißfarbe der Markierung in der Referenzkarte; kann nur gelesen werden \end{mmltab}

\subsubsection*{Methoden}

Diese Klasse kennt lediglich die =set= -Methode:

Setzt den Wert für eine Eigenschaft im Objekt neu.

colorObj
\index{colorObj}

Diese Klasse entspricht einer Farbangabe im Mapfile. Objekte dieser Klasse sind immer Bestandteil von anderen Klassen und können nicht von Hand erstellt werden.

Die Farben im MapServer -- und demnach auch in MapScript -- werden nach dem RGB-Schema notiert.

\subsubsection*{Konstruktor}

colorObj verfügt nicht über einen von außen zugänglichen Konstruktor.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften sind Teil jedes Objektes der Klasse colorObj.

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von colorObj} {tab:ref:colorobj:prop} int & red & Rot-Anteil der Farbe\\ int & green & Grün-Anteil der Farbe\\ int & blue & Blau-Anteil der Farbe \end{mmltab}

\subsubsection*{Methoden}

Diese Klasse kennt leidglich eine einzige Methode:

Mit dieser Methode wird der Rot-, Grün- und Blau-Anteil der Farbe (jeweils zwischen =0= und =255=  gesetzt.

pointObj
(8)\index{pointObj}

Diese Klasse stellt einen einzelnen Punkt dar. Punkte können entweder aus anderen geometrischen Objekten gewonnen werden (beispielsweise Linien), sie können aber auch über einen Konstruktor neu erschaffen werden.

\subsubsection*{Konstruktor}

Der folgende simple Konstruktor erstellt einen neuen, leeren Punkt:

\subsubsection*{Eigenschaften}

pointObj kennt die folgenden Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von pointObj} {tab:ref:pointobj:prop} double & x & x-Koordinate des Punktes\\ double & y & y-Koordinate des Punktes\\ double & m & Weitere Koordinate des Punktes, die nur fü sogenannte measured Shapefiles benutzt wird. \end{mmltab}

\subsubsection*{Methoden}

pointObj kennt die folgenden Methoden:

Setzt die Koordinaten des Punktes neu. Der dritte Parameter wird für measured shapes benutzt, die vom MapServer bisher jedoch noch nicht dargestellt werden können.

Malt den Punkt in den entsprechenden Layer des Mapfiles und annotiert ihn auf Wunsch mit =text=.

Diese Funktion berechnet die Entfernung des Punkt-Objektes zu einem anderen Punkt-Objekt.

Diese Funktion berechnet die minimale Entfernung des Punkt-Objektes zu einer Linie, die durch die beiden übergebenen Punkte definiert wird.

Diese Funktion berechnet die minimale Entfernung des Punkt-Objektes zu einem Shape.

Projiziert den Punkt von der Projektion =von= in die Projektion =nach=.

Zerstört den Punkt und gibt alle mit ihm zusammenhängenden Resourcen frei.

lineObj
(9)\index{lineObj}

Dieses Objekt bezeichnet eine Linie, die aus einem oder mehreren Punkten besteht. Objekte dieses Typs lassen sich entweder aus anderen geometrischen Objekten extrahieren (beispielsweise aus Shapes) oder auch per Hand erstellen.

\subsection*{Konstruktor}

Der Konstruktor von lineObj erstellt ein leeres Objekt und hat folgendes Aussehen:

\subsection*{Eigenschaften}

lineObj kennt die folgenden Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von lineObj} {tab:ref:lineobj:prop} int & numpoints & Die Anzahl der Punkte in der Linie; kann nur gelesen werden. \end{mmltab}

\subsection*{Methoden}

lineObj kennt die folgenden Methoden:

Fügt einer Linie einen weiteren Punkt am Ende der Linie hinzu.

Fügt der Linie einen Punkt am Ende hinzu. Der Parameter =m= ist optional und wird für sogenannte measured shapefiles benutzt.

Gibt das Objekt zurück, das dem =i= -ten Punkt in der Linie entspricht. Diese Referenz geht verloren, wenn das betreffende =lineObj= vernichtet wird.

Projiziert die Punkte der Linie von der Projektion =von= in die Projektion =nach=.

Gibt die Resourcen für das Objekt frei und zerstört es.

rectObj
\index{rectObj}

Dieses Objekt beschreibt anhand von zwei Punkten ein Rechteck. Häufig wird es zum Beschreiben von Extents von Kartenausschnitten benutzt. Objekte dieses Typs können aus anderen Objekten herausgefischt, aber auch von Hand konstruiert werden.

\subsubsection*{Konstruktor}

Der Konstruktor dieser Klasse erstellt ein leeres rectObj und sieht wie folgt aus:

\subsubsection*{Eigenschaften}

rectObj kennt die folgenden Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von rectObj} {tab:ref:rectobj:prop} double & minx & x-Koordinate des ersten Punktes\\ double & miny & y-Koordinate des ersten Punktes\\ double & maxx & x-Koordinate des zweiten Punktes\\ double & maxy & y-Koordinate des zweiten Punktes \end{mmltab}

\subsubsection*{Methoden}

rectObj kennt die folgenden Methoden:

Setzt den Wert für eine Eigenschaft im Objekt neu.

Setzt die Extents des Objekts neu.

Malt das Rechteck in eine Karte =map= in den Layer {layer}. Es wird anhand der angegebenen =CLASS= klassifiziert und mit =text=  annotiert, falls dieser Wert mit übergeben wird.

Gibt bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

Die Extents des Rechtecks werden auf die angegebene Breite und Höhe zurechtgestutzt.

Projiziert die Punkte des Rechtecks von der Projektion =von= in die Projektion =nach=.

Zerstört das imageObj und gibt alle mit ihm zusammenhängenden Resourcen frei.

shapeObj
\index{shapeObj}

Dieses Objekt repräsentiert ein einzelnes Shape. Ein solches Shape kann man aus einem shapefileObj herausholen, oder aber von Hand konstruieren.

\subsubsection*{Konstruktor}

Der Konstruktor erstellt ein neues, leeres shapeObj von angegebenen Typ:

Die möglichen Werte für =typ= sind aus der Tabelle auf Seite~\pageref{tab:ref:mapscript:const} ersichtlich.

\subsubsection*{Eigenschaften}

shapeObj kennt die folgenden Eigenschaften:\\

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von shapeObj} {tab:ref:shapeobj:prop}

int & classindex & Nur relevant, wenn das Shape mit =draw= gezeichnet werden soll\\ int & type & Type des Shapes. Kann nur gelesen werden\\ int & numlines & Anzahl der Linien im Shape. Kann nur gelesen werden\\ int & index & Nummer des Shapes innerhalb des Shapefiles. Kann nur gelesen werden\\ int & tileindex & Kachel, in der sich das Shape befindet. Gilt nur für gekachelte Shapefiles. Kann nur gelesen werden\\ rectObj & bounds & Extents des Shapes. Kann nur gelesen werden\\ array & values & Assoziatives Array mit Werten aus der .dbf -Datei zum Shapefile. Existiert nur für shapeObjs, die aus einem layerObj extrahiert wurden. Kann nur gelesen werden\\ int & numvalues & Anzahl der Einträge in diesem Array. Kann nur gelesen werden \end{mmltab}

\subsubsection*{Methoden}

In shapeObj stehen die folgenden Methoden zur Verfügung:

\enlargethispage{1.5em}

Setzt den Wert für eine Eigenschaft im Objekt neu.

Fügt dem Shape eine neue Linie hinzu.

Gibt die Linie mit dem Index =i= aus dem Shape zurück. Diese Referenz existiert nur solange, wie es das shapeObj gibt; wird es zerstört, geht auch diese Referenz verloren.

Malt das Shape in den angegebenen Layer der Karte =map=. Es wird anhand der angegebenen =CLASS= klassifiziert und mit =text=  annotiert, falls dieser Wert mit übergeben wird.

Gibt bei Erfolg =MS_SUCCESS= zurück, ansonsten =MS_FAILURE=.

Gibt =MS_TRUE= zurück, falls sich =punkt=  innerhalb des Shapes befindet, ansonsten =MS_FALSE=.

Gibt =MS_TRUE= zurück, falls =shape=  das Shape überschneidet, ansonsten =MS_FALSE=.

Projiziert die Punkte des Shapes von der Projektion =von= in die Projektion =nach=.

Zerstört das shapeObj und gibt alle mit ihm zusammenhängenden Resourcen frei.

projectionObj
\index{projectionObj}

Diese Klasse repräsentiert eine Projektions-Sektion im Mapfile. Ein solches Objekt kann ebenso aus einem mapObj wie auch aus einem layerObj stammen, und kann ebenso von Hand kreiert werden.

Ein projectionObj hat keine von außen zugänglichen Eigenschaften oder Methoden. Es kann lediglich über einen Konstruktor erschaffen werden, der folgendermaßen aussieht:

Der zu übergebende String ist eine Zeichenkette, die einer Kette von kommaseparierten Parametern für die Prjektionsbibliothek proj.4 entspricht.

shapefileObj
(10)\index{shapefileObj}

Dieses Objekt repräsentiert ein Shapefile. Es hat nicht gezwungenermaßen etwas mit Mapfiles oder anderen, kartenbezogenen Objekten zu tun; man kann dieses Objekt auch einfach zur Manipulation von Shapefiles verwenden.

Natürlich lassen sich auch neue Shapefiles erzeugen und speichern.

\subsubsection*{Konstruktor}

Eine neues Shapefile wird mit dem Konstruktor der Klasse erzeugt:

Öffnet ein Shapefile. Der Dateiname benötigt die Erweiterung .shp nicht. Die Indexdatei .shx muß bei bereits existierende Shapefiles vorhanden sein; ebenso die .dbf -Datei, diese kann aber leer sein.

Um ein neues Shapefile zu erstellen oder ein altes zu überschreiben, muß =typ= auf einen entsprechenden Wert gesetzt werden, wie man ihn in der Tabelle auf Seite~\pageref{tab:ref:mapscript:const} finden kann. Soll ein Shapefile nur zum Lesen geöffnet werden, muß =typ= auf =-1=  gesetzt sein, für ein anhängendes Schreiben auf =-2=.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften gelten für jedes shapefileObj:\\

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von shapefileObj} {tab:ref:shapefileobj:prop} int & numshapes & Die Anzahl der Shapes im Shapefile. Kann nur gelesen werden\\ int & type & Typ des Shapefiles. Kann nur gelesen werden\\ string & source & Datei, die dem shapefileObj zugrunde liegt. Kann nur gelesen werden\\ rectObj & bounds & Die Extents des Shapefiles. Kann nur gelesen werden \end{mmltab}

\subsubsection*{Methoden}

shapefileObj stellt die folgenden Methoden zur Verfügung:

Holt als shapeObj das Shape Nummer =i= aus dem shapefileObj.

Holt das =i= -te Shape aus dem Shapefile, nachdem es anhand der Vorgaben im mapObj =map= transformiert worden ist.

Gibt die Bounding Box für das =i= -te Shape im Shapefile zurück.

Fügt dem Shapefile ein neues Shape hinzu.

Hängt an das Shapefile einen neuen Punkt an.

Zerstört das shapefileObj und gibt alle mit ihm zusammenhängenden Resourcen frei.

resultcachememberObj
\index{resultcachememberObj}

Objekte dieser Art werden nur bei Queries erzeugt und liegen dann in layerObjs, wo sie mit der Methode =getResult= hervorgeholt werden können. Sie besitzen keinen öffentlichen Konstruktor, sondern lediglich drei Eigenschaften:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von resultcachememberObj} {tab:ref:resultcachememberobj:prop} int & shapeindex & Die Nummer des Shapefiles für das Resultat. Kann nur gelesen werden\\ int & tileindex & Die Nummer der Kachel für das Resultat. Gilt nur für gekachelte Daten. Kann nur gelesen werden\\ int & classindex & Die Nummer der Class für das Resultat. Kann nur gelesen werden \end{mmltab}

Anhand dieser Eigenschaften lassen sich dann die Daten für die Suchergebnisse ermitteln.

scalebarObj
\index{scalebarObj}

Diese Klasse repräsentiert die =SCALEBAR= -Sektion aus dem Mapfile.

\subsubsection*{Konstruktor}

Auch dieses Objekt besitzt keinen von außen zugänglichen Konstruktor; Objekte dieser Klasse sind immer Bestandteil eines mapObj.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften kennt jedes legendObj:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von legendObj} {tab:ref:scalebarobj:prop} int & width & Breite der Legende in Pixeln\\ int & height & Höhe der Legende in Pixeln\\ int & style & Stil des Maßstabs\\ int & color & Hintergrundfarbe des Maßstabbildes\\ int & backgroundcolor & Hintergrundfarbe des Maßstabs\\ int & outlinecolor & Umrißfarbe des Maßstabs\\ int & units & Maßeinheit für den Maßstab; siehe die Tabelle ab Seite~\pageref{tab:ref:mapscript:const} für mögliche Werte\\ int & status & Status des Maßstabs; =MS_ON= =MS_OFF=  oder =MS_EMBED= \\ int & position & Position für in die Karte eingebettete Maßstäbe; für mögliche Werte siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const}\\ int & transparent & Soll der Hintergrund transparent sein?\\ int & interlace & Soll der fertige Maßstab interlaced sein? (nicht für HTML-Legenden)\\ int & postlabelcache & Sollen Labels vor oder nach den Features gezeichnet werden? Ist =MS_TRUE= oder =MS_FALSE= \\ labelObj & label & Beschriftung des Maßstabs\\ colorObj & imagecolor & Farbe des Maßstabsbildes \end{mmltab}

\subsubsection*{Methoden}

Setzt den Wert für eine Eigenschaft im Objekt neu.

legendObj
\index{legendObj}

Diese Klasse repräsentiert die =LEGEND= -Sektion aus dem Mapfile.

\subsubsection*{Konstruktor}

Auch dieses Objekt besitzt keinen von außen zugänglichen Konstruktor; Objekte dieser Klasse sind immer Bestandteil eines mapObj.

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften kennt jedes legendObj:

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von legendObj} {tab:ref:legendobj:prop} int & width & Breite der Legende in Pixeln\\ int & height & Höhe der Legende in Pixeln\\ int & keysizex & Breite eines Legendensymbols in Pixeln\\ int & keysizey & Höhe eines Legendensaymbols in Pixeln\\ int & keyspacingx & Horizontaler Abstand zweier Legendensymbole\\ int & keyspacingy & Vertikaler Abstand zweier Legendensymbole\\ int & outlinecolor & Umrißfarbe der Legende; ist =-1=, falls es keinen Umriß gibt\\ int & status & Status der Legende; =MS_ON= =MS_OFF=  oder =MS_EMBED= \\ int & position & Position für in die Karte eingebettete Legenden; für mögliche Werte siehe die Tabelle auf Seite~\pageref{tab:ref:mapscript:const}\\ int & transparent & Soll der Hintergrund transparent sein?\\ int & interlace & Soll die fertige Legende interlaced sein? (nicht für HTML-Legenden)\\ int & postlabelcache & Sollen Labels vor oder nach den Features gezeichnet werden? Ist =MS_TRUE= oder =MS_FALSE= \\ labelObj & label & Beschriftung der Legende\\ colorObj & imagecolor & Farbe der Legende\\ string & template & Name der Template-Datei für eine HTML-Legende \end{mmltab}

\subsubsection*{Methoden}

Setzt den Wert für eine Eigenschaft im Objekt neu.

outputformatObj
(11)\index{outputformatObj}

gridObj
(12)\index{gridObj}

Dieses Objekt ist erstmals in MapServer 4.0 zu finden. Es ist immer in einen Layer eingebettet und bezeichnet ein Gitternetz. Mit Hilfe dieses Objekts ist man nicht darauf angewiesen, ein eigenes Shapefile für ein Gitternetz zu haben; Grids werden mit entsprechenden Einstellungen automatisch erzeugt. Zur Verwendung von Grids siehe Abschnitt~\ref{text:mapfile:graticule}.

\subsubsection*{Konstruktor}

Ein Layer wird zu einem Grid-Objekt, indem man die folgende Methode mit dem entsprechenden Layer als Parameter aufruft:

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften gelten für jedes gridObj:\\

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von gridObj} {tab:ref:gridobj:prop} double & minsubdivide & Minimale Anzahl von Segmenten in einer Kurve des Gitters.\\ double & maxsubdivide & Maximale Anzahl von Segmenten in einer Kurve des Gitters.\\ double & minarcs & Minimale Anzahl von Kurven pro Achse.\\ double & maxarcs & Maximale Anzahl von Kurven pro Achse.\\ double & mininterval & Minimales Interval zwischen Kurven des Gitters, im Koordinatensystem der Karte.\\ double & maxinterval & Maximales Interval zwischen Kurven des Gitters, im Koordinatensystem der Karte.\\ string & labelformat & Das Beschriftungsformat für den Grid. \end{mmltab}

\subsubsection*{Methoden}

Setzt den Wert für eine Eigenschaft im Objekt neu.

errorObj
(13)\index{errorObj}

Diese Klasse wird für die Fehlerbehandlung in MapScript eingesetzt. Sie existiert erst seit Version 4.0.

\subsubsection*{Konstruktor}

Es gibt keinen Konstruktor für Fehlerobjekte in MapScript. Diese Objekte werden ausschließlich von MapScript selber erzeugt. Allerdings sollte die Liste von Fehlern zu Beginn eines Skriptes und immer dann, wenn man die Fehler in der Liste nicht mehr braucht, zurückgesetzt werden:

Der Anfang der Liste von Fehlern ist das eigentliche =errorObj= ; man erhält einen Verweis auf diese Liste mit der folgenden Funktion:

\subsubsection*{Eigenschaften}

Die folgenden Eigenschaften gelten für jedes errorObj:\\

\begin{mmltab} {p{.10 \textwidth}p{.20 \textwidth}p{.65 \textwidth}} {Type & Name & Bedeutung} {Eigenschaften von shapefileObj} {tab:ref:errorobj:prop} int & code & Der Fehlercode für den aktuellen Fehler\\ string & routine & Der Name der Funktion, innerhalb der der Fehler aufgetreten ist.\\ string & message & Die von MapScript erzeugte Fehlernachricht. \end{mmltab}

\subsubsection*{Methoden}

Dieses Objekt kennt lediglich eine einzige Methode:

Diese Methode gibt einen Verweis auf das nächste Fehlerobjekt in der globalen Liste von Fehlerobjekten zurück.