Autodesk 15606-011408-9330 - MAPGUIDE R6.3 SITE LIC-UPG R6, MapGuide LiteView Developer's Manual

April 2004

Autodesk MapGuide® LiteView

Developer’s Guide

12345678910

Copyright © 2004 Autodesk, Inc.

All Rights Reserved

This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.

AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS, AND MAKES
SUCH MATERIALS AVAILABLE SOLELY ON AN “AS-IS” BASIS.

IN NO EVENT SHALL AUTODESK, INC., BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES IN CONNECTION WITH OR ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVE
LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE OF THE
MATERIALS DESCRIBED HEREIN.

Autodesk, Inc., reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product
at the time of its publication, and may not reflect the product at all times in the future.

AUTODESK TRADEMARKS

The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Props, 3D Studio, 3D Studio
MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADI, AEC Authority (logo), AEC-X, Animator Pro,
Animator Studio, ATC, AUGI, AutoCAD, AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Inventor, Autodesk (logo), Autodesk
MapGuide, Autodesk Streamline, Autodesk University (logo), Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP,
AutoSketch, Biped, bringing information down to earth, CAD Overlay, Character Studio, Cinepak, Cinepak (logo), Codec Central,
Combustion, Design Your World, Design Your World (logo), Discreet, EditDV, Education by Design, gmax, Heidi, HOOPS,
Hyperwire, i-drop, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, NAAUG, ObjectARX, PeopleTracker, Physique, Planix,
Powered with Autodesk Technology (logo), ProjectPoint, RadioRay, Reactor, Revit, Softdesk, Texture Universe, The AEC Authority,
The Auto Architect, VISION*, Visual, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual
Survey, Visual Toolbox, Visual TugBoat, Visual LISP, Volo, WHIP!, and WHIP! (logo).

The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3ds max, AutoCAD Architectural Desktop,
AutoCAD Learning Assistance, AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL
Interface, Autodesk Envision, Autodesk Map, AutoSnap, AutoTrack, Built with ObjectARX (logo), Burn, Buzzsaw, Buzzsaw.com,
Cinestream, Cleaner, Cleaner Central, ClearScale, Colour Warper, Content Explorer, Dancing Baby (image), DesignCenter,
Design Doctor, Designer's Toolkit, DesignProf, DesignServer, Design Web Format, DWF, DWG Linking, DXF, Extending the
Design Team, GDX Driver, gmax (logo), gmax ready (logo),Heads-up Design, IntroDV, jobnet, ObjectDBX, onscreen onair
online, Plans & Specs, Plasma, PolarSnap, Real-time Roto, Render Queue, Visual Bridge, Visual Syllabus, and Where Design
Connects.

Autodesk Canada Inc. Trademarks

The following are registered trademarks of Autodesk Canada Inc. in the USA and/or Canada, and/or other countries: discreet, fire,
flame, flint, flint RT, frost, glass, inferno, MountStone, riot, river, smoke, sparks, stone, stream, vapour, wire.

The following are trademarks of Autodesk Canada Inc., in the USA, Canada, and/or other countries: backburner, backdraft, Multi­Master Editing.

THIRD-PARTY TRADEMARKS

All other brand names, product names, or trademarks belong to their respective holders.

THIRD-PARTY COPYRIGHT NOTICES

Copyright (c) 2000 The Apache Software Foundation. All rights reserved.

Portions of this product are distributed under license from D.C. Micro Development, © Copyright D.C. Micro Development. All
rights reserved.

GOVERNMENT USE

Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer
Software-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable.

iii

Contents

Chapter 1 Introduction . . . . . . . . . . . . . . . . . 1

About This Document . . . . . . . . . . . . . . . . . 2

What You Need to Know . . . . . . . . . . . . . . 2

Conventions . . . . . . . . . . . . . . . . . . 3

Copying Text from This Document . . . . . . . . . . . 3

Overview of Autodesk MapGuide LiteView . . . . . . . . . . 4

Features . . . . . . . . . . . . . . . . . . . . 4

Creating an Autodesk MapGuide LiteView Application. . . . . . . 6

Understanding Application Architecture . . . . . . . . . . . 7

Chapter 2 Understanding Requests . . . . . . . . . . . . . 9

Overview of Requests and Responses . . . . . . . . . . . 10

OpenGIS WMS 1.1.1 Compliance . . . . . . . . . . 10

Non-WMS 1.1.1-Compliant Parameters . . . . . . . . . 10

Creating a map Request . . . . . . . . . . . . . . . 10

Formatting a map Request . . . . . . . . . . . . . 11

Example of a Minimal Map Request . . . . . . . . . . 12

Overview of map Request Parameters . . . . . . . . . 13

Understanding map Request Parameters . . . . . . . . 15

Tips for Creating Map Requests . . . . . . . . . . . 22

Creating a feature_info Request . . . . . . . . . . . . . 22

Example of a feature_info Request . . . . . . . . . . 23

Positioning Feature Information . . . . . . . . . . . 23

Understanding feature_info Request Parameters . . . . . . 24

Interpreting Responses to a feature_info Request. . . . . . . . 26

Sample Response . . . . . . . . . . . . . . . . 27

feature_info Response DTDs . . . . . . . . . . . . 28

Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests . 35

Overview . . . . . . . . . . . . . . . . . . . . 36

GetCapabilities Requests . . . . . . . . . . . . . . . 36

GetCapabilities Request Parameters . . . . . . . . . . 37

GetCapabilities Metadata Response . . . . . . . . . . 37

GetMap Requests. . . . . . . . . . . . . . . . . . 44

GetMap Request Parameters . . . . . . . . . . . . 45

GetFeatureInfo Requests . . . . . . . . . . . . . . . 47

iv | Contents

GetFeatureInfo Request Parameters . . . . . . . . . . 47

Chapter 4 Configuring and Using the Sample Applications . . . . . . 49

The Sample Applications . . . . . . . . . . . . . . . 50

The WMS Viewer Sample Application . . . . . . . . . . . 50

Starting WMS Viewer . . . . . . . . . . . . . . 50

Extending WMS Viewer . . . . . . . . . . . . . . 51

Configuring WMS Viewer . . . . . . . . . . . . . 55

The ColdFusion Sample Application. . . . . . . . . . . . 55

ColdFusion Sample Application Files . . . . . . . . . 56

ColdFusion Sample Application Requirements . . . . . . 57

ColdFusion Sample Application Client Platforms. . . . . . 57

Configuring the ColdFusion Sample Application . . . . . . 58

Starting the ColdFusion Sample Application . . . . . . . 63

Removing the ColdFusion Sample Application Files . . . . . 64

Using the ColdFusion Sample Application . . . . . . . . 64

Troubleshooting and Other Resources . . . . . . . . . . . 77

Displaying Data by Layer . . . . . . . . . . . . . 77

Designing the Recenter Feature . . . . . . . . . . . 78

Accessing the GML DTD While Offline . . . . . . . . . 80

SRS-to-WKT Mapping . . . . . . . . . . . . . . 81

Where to Get More Information . . . . . . . . . . . 82

Index . . . . . . . . . . . . . . . . . . . . . . . . 87

1

In this chapter

■ About this document

■ Overview of Autodesk

MapGuide LiteView

■ Creating an Autodesk

MapGuide LiteView
application

■ Understanding application

architecture

1

Introduction

Autodesk MapGuide® LiteView is a platform-indepen-

dent viewing solution for Autodesk MapGuide

®

maps.

Deployed as a Java servlet, Autodesk MapGuide LiteView

serves interactive maps to most browsers—map users

don’t have to download or install a viewer. This chapter

includes general information about this guide and its

audience, an overview of Autodesk MapGuide LiteView

and its architecture, and the general steps you that take to

create an Autodesk MapGuide LiteView application.

2 | Chapter 1 Introduction

About This Document

This guide is written for developers of Web sites that provide access to
Autodesk MapGuide maps. It describes Autodesk MapGuide LiteView, the
HTTP requests that are the basis of an Autodesk MapGuide LiteView applica­tion, and the sample applications that you can use as models for creating
your own applications.

For information about installing and configuring Autodesk MapGuide Lite­View, see the Autodesk MapGuide LiteView Servlet Administrator’s Guide. To

open that guide from the Windows desktop, choose Start ➤ Programs ➤
Autodesk MapGuide Release 6.5 ➤ LiteView 6.5 ➤ Servlet Administrator’s

Guide.

In this document, Autodesk MapGuide LiteView is assumed to be installed in
the default folder, C:\Program Files\Autodesk\MapGuideLiteView6.5\, some­times abbreviated to <InstallFolder>.

What You Need to Know

To get the most benefit from this guide, and to develop a robust application,
you must be proficient in one or more of the following technologies or
languages:

■ Active Server Pages (ASP)

■ Java Server Pages (JSP)

■ JavaScript scripting

■ Perl scripting

■ Servlet technology

■ Web-application architecture

■ XML

You don’t need to know the Autodesk MapGuide Viewer API because you do
not call its methods to create an Autodesk MapGuide LiteView application.

If you want to use the ColdFusion sample application that’s included with
Autodesk MapGuide LiteView, you must be familiar with:

■ Macromedia ColdFusion

■ Apache XML projects such as Xerces XML parser and Xalan XSLT

stylesheet processor. For more information about these see
http://www.apache.org.

About This Document | 3

This document assumes that you know how to create maps with Autodesk
MapGuide Author and have read the Autodesk MapGuide User’s Guide and
Autodesk MapGuide Help.

Conventions

The following syntax-diagram conventions are used in the of Web Map
Service (WMS) requests:

Copying Text from This Document

You can copy text from this PDF file and paste it into another application.
You may want to copy code samples for use in your own work, for example.

To copy text from a PDF file

1 Click the Text Select tool on the Acrobat Reader toolbar.

2 Drag to select the text you want to copy.

3 Right-click and choose Copy from the shortcut menu.

The text is copied to the Clipboard.

Notations Used in Request Syntax

Notation Description

[ ] The argument or value is optional.

{a|b|c} A list of possibilities.

( ) A grouping. Typically used before an asterisk (*) or a

plus sign (+) to indicate a full subexpression.

* Zero or more occurrences of the previous

subexpression.

+ One or more occurrences of the previous

subexpression.

< > A variable argument or value.

Other notation A literal.

4 | Chapter 1 Introduction

Overview of Autodesk MapGuide LiteView

Autodesk MapGuide LiteView extends the capabilities of Autodesk
MapGuide to display maps quickly in a browser without the need for a
special plug-in viewer. Autodesk MapGuide LiteView is a servlet—that is, a
Java program that runs on a server—that provides lightweight (fast, efficient,
and installation-free) viewing.

Autodesk MapGuide LiteView converts MWF files to PNG or JPEG files for
display in Microsoft

Internet Explorer, Netscape Navigator, or any browser
that supports the PNG or JPEG format. A Web application that sends a
request to the Autodesk MapGuide LiteView servlet to convert an MWF file
to a PNG or JPEG file receives the converted image in the response.

Autodesk MapGuide LiteView understands all the enhancements to the
Autodesk MapGuide Release 6.5 MWF file format, and supports all coordi­nate systems in which an MWF file can be authored. Autodesk MapGuide
LiteView supports GetCapabilities, GetMap, and GetFeatureInfo requests to
comply with the OpenGIS Web Map Service (WMS) 1.1.1 implementation
specification. You must register maps by using Autodesk MapGuide Lite­View’s WMS Administrator before making WMS 1.1.1 requests.

Features

As a developer, the Autodesk MapGuide LiteView features of special interest
to you are:

■ User-map interactivity—You can use the following URL parameters in

map requests to give users more opportunities to interact with a map:

❏ SRS (Spatial Reference System) parameter—Overrides the Map Coor-

dinate System (MCS).

❏ SELECT parameter—Supports selection of layer groups as well as the

selection of map features on layers.

❏ HLS (Highlighting Line Styles) parameter—Supports up to four user-

defined highlighting styles that are used to select map features.

❏ SYMBOLS parameter—Identifies one or more map locations by using

a user-defined symbol.

■ Simplified installation and configuration—The Autodesk MapGuide

LiteView installation program prompts you for the most important
Autodesk MapGuide LiteView configuration parameters, configures
Apache Tomcat, and sets up Autodesk MapGuide LiteView so it is ready to
use. The ColdFusion and WMS Viewer sample application files are copied

Overview of Autodesk MapGuide LiteView | 5

to the SampleApp and WmsViewer subfolders in the Autodesk MapGuide
LiteView installation folder on your hard drive.

■ Fast map viewing—For first-time users or occasional users, it’s faster to

use a Autodesk MapGuide LiteView application to download and display
a raster image than it is to download and install a specialized viewer for
image display.

■ Cross-platform deployment—Autodesk MapGuide LiteView responds to

HTTP requests for MWF files by returning images in PNG or JPEG format.
Most Web browsers on most platforms support these formats natively.

■ Locked-down deployment—Many organizations prevent users from

downloading and installing viewers, such as ActiveX controls and Java
plug-ins, on their desktops. Applications written for Autodesk MapGuide
LiteView require no viewers.

6 | Chapter 1 Introduction

Creating an Autodesk MapGuide LiteView
Application

You can use the sample applications provided with Autodesk MapGuide Lite­View as starting points for creating your own Autodesk MapGuide LiteView
applications. This section describes the general steps to create an Autodesk
MapGuide LiteView application.

To create a Autodesk MapGuide LiteView application

1 Refer to the Autodesk MapGuide LiteView Servlet Administrator’s Guide to

install and configure Autodesk MapGuide LiteView and the sample appli­cations, and then run a sample application to see how it works.

2 Learn the HTTP requests that the Autodesk MapGuide LiteView servlet

accepts. For information about requests, see Chapter 2, “Understanding
Requests,” on page 9, and Chapter 3, “Making GetCapabilities, GetMap,
and GetFeatureInfo Requests,” on page 35.

3 Open a sample-application source file and inspect its code. See Chapter 4,

“Configuring and Using the Sample Applications,” on page 49.

4 Read the sample-application source-code comments that explain how to

send get and post HTTP requests.

5 Think of how you might adapt the application to suit your needs.

Understanding Application Architecture | 7

Understanding Application Architecture

The following diagram shows how the Autodesk MapGuide LiteView servlet
accepts HTTP requests for raster images through the Java Servlet API interface
of a Web server:

The Autodesk MapGuide LiteView servlet requires a Web application server that functions as a Java
servlet container.

To fulfill a request for a raster image. Autodesk MapGuide LiteView:

■ Accepts an HTTP request for a raster image of a portion of an MWF file

■ Loads the requested MWF file

■ Zooms to the correct location and scale, generating HTTP requests for

map-layer data to the Autodesk MapGuide Server

■ Returns a raster image in PNG or JPEG format as the HTTP response

Web Server

Autodesk MapGuide Server

Browser

Internet

Extranet

Intranet

Data Sources

MWF

Web

LiteView Servlet

Java Servlet
API

Application

Servlet

Container

8 | Chapter 1 Introduction

9

In this chapter

■ Overview of requests and

responses

■ Creating a map request

■ Creating a feature_info

request

■ Interpreting responses to a

feature_info request

2

Understanding Requests

This chapter gives an overview of requests and responses

using Autodesk

MapGuide® LiteView, and describes how

to create requests for a map image and its feature informa-

tion, and describes how to interpret a response that con-

tains feature information.

10 | Chapter 2 Understanding Requests

Overview of Requests and Responses

This chapter describes how to construct the following HTTP requests in an
Autodesk MapGuide LiteView application and how to work with the
responses:

■ map request—Returns the map image to the application

■ feature_info request—Returns information about a map feature, located

at a specified point, to the application

The format of the responses to the map and feature_info requests are:

■ Response to a map request—A PNG or JPEG image

■ Response to a feature_info request—An XML document that describes

the selected feature

OpenGIS WMS 1.1.1 Compliance

Autodesk MapGuide LiteView’s map-request and map-interface features
comply with the OpenGIS Web Map Service (WMS) 1.1.1 implementation
specification, available at http://www.opengis.org/techno/specs/01­068r3.pdf. As an active and Principal Member of the Open GIS Consortium
(OGC) Autodesk works with OGC staff and members to create industry-stan­dard mapping specifications for the Web. The OGC Web site is at
www.opengis.org.

This chapter describes how to make requests that comply with the draft WMS
specification (that is, map and feature_info requests). To make requests that
comply with WMS 1.1.1 by using GetCapabilities, GetMap, and GetFeature­Info operations, see Chapter 3, “Making GetCapabilities, GetMap, and
GetFeatureInfo Requests,” on page 35.

Non-WMS 1.1.1-Compliant Parameters

In addition to the map-request parameters defined by WMS 1.1.1, Autodesk
MapGuide LiteView also supports the Autodesk-specific parameters HLS,
SYMBOLS, SELECT, and PPIY.

Creating a map Request

You use a map request in the HTTP get or post request of your application; see
“Using Get and Post Requests,” on page 68. The map request parameters

Creating a map Request | 11

define the map’s extents, content, and image size. Autodesk MapGuide Lite­View returns a PNG or JPEG image of the map in response.

Formatting a map Request

A map request consists of a URL, required parameters, variable and constant
parameter values, and delimiters—ampersand (&), equal sign (=), and
comma (,). You can use the comma delimiter with the SELECT and SYMBOLS
parameters to imply values, so you don’t have to list them repeatedly in a
single request. A map request also can include optional parameters.

The syntax of a map request is described by using the following conventional
notation:

■ Parameter values—Enclosed in angle brackets, using the data type of the

variable, such as <float>, or a short description of the variable in angle
brackets, such as <filename.mwf>.

■ Optional elements of the map request—Enclosed in square brackets ([ ]).

■ Repeated parameters—Indicated with an ellipsis (...).

■ Prefix—Represents the URL of the Autodesk MapGuide LiteView servlet:

http://<webserver_name>/<context_path>/servlet/MapGuideLiteView?

<webserver_name> is the name of the Web server under which Autodesk

MapGuide LiteView is running, followed by a colon (:) and a port number.
<context_path> may or may not appear, depending on your application­server configuration. The question mark (?) at the end of the prefix sepa­rates the servlet address from the request parameters. For the default
Autodesk MapGuide LiteView installation, which requests the
MapGuideLiteView servlet from Apache Tomcat, the URL (for a local host)
is:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView

This URL is used in many examples in this document. When making your
own requests, change <webserver_name> and <context_path> to match your
configuration.

Note If you’re using the JRun application server, omit <context_path>.

■ Other elements—Are literals.

Syntax of a Minimal map Request

The syntax of the following map request includes only required parameters:

<prefix>?

REQUEST=map
&BBOX=<minX>,<minY>,<maxX>,<maxY>

12 | Chapter 2 Understanding Requests

&WIDTH=<integer>
&HEIGHT=<integer>
&LAYERS=<filename.mwf>
&FORMAT=<PNG|JPEG|JPG>

Syntax of Optional Parameters

The map request can include the following optional parameters, each having
its own syntax:

■ SELECT parameter syntax:

&SELECT=<MWFName>/[MWFLayerName|MWFLayerGroupName], featureID
(,<MWFName>/[MWFLayerName|MWFlayerGroupName], [featureID])*

■ SRS parameter syntax:

&SRS=ADSK:LL84

■ HLS parameter syntax

&HLS=<n>

■ SYMBOLS Parameter Syntax

&SYMBOLS=<SymbolName>,<X>,<Y>,<Width>,<Height>,

[(rotationDegrees)],[<labelString>]
(,[<SymbolName>],<X>,<Y>,[<Width>],[<Height>],
[<rotationDegrees>],[<labelString>])*

Example of a Minimal Map Request

The following example shows a map request that uses only required param­eters for the map named Sample_World.mwf:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=map
&BBOX=26.117831,30.373481,49.340653,68.102723
&WIDTH=600
&HEIGHT=300
&LAYERS=Sample_World.mwf
&FORMAT=PNG

The request specifies a bounding box with a lower-left coordinate of
(26.117831, 30.373481) and an upper-right coordinate of (49.340653,

68.102723). This box is the area of the map to be displayed in the browser as
a PNG image with dimensions of 600 x 300 pixels.

Creating a map Request | 13

Examples of Optional Parameters

The following example shows how to use the optional SELECT parameter to
display US, CA, and UK features on the Countries layer of Sample_World.mwf:

Null values between comma delimiters imply the repeated use of
Sample_World.mwf/Countries as the MWF and the layer that has CA and
UK features.

The following example shows how to set the SYMBOLS parameter to specify
insertion of a single symbol, TestSymbol, at point (32.5,45.2) that is 0.001 by

0.001 meters, not rotated, and displayed with the label test:

&SYMBOL=TestSymbol,32.5,45.2,0.001,0.001,,test

The following examples show how to set the SRS and HLS parameters:

&SRS=ADSK:LL84
&HLS=3

Overview of map Request Parameters

The following table briefly describes the map-request parameters that were
introduced in “Formatting a map Request,” on page 11. For detailed informa­tion about these parameters, see “Understanding map Request Parameters,”
on page 15.

Note You must include all the following parameters in a map request except
SELECT, SRS, HLS, SYMBOLS, and PPIY.

Parameters for map Requests

Parameter Description Content

REQUEST Required. The type of request. “map”

BBOX Required. The bounding box of the

requested map image, specified by the
MCS, unless overridden by the SRS parame­ter. The image’s bounding box should fall
within the maximum extents of the
authored map. The first pair of floats speci­fies the lower-left X-Y coordinate and the
second pair specifies the upper-right X-Y
coordinate.

minX,minY,maxX,maxY
Floating-point num­bers.

&SELECT=Sample_World.mwf/Countries,US,,CA,,UK

Repeated delimiters

14 | Chapter 2 Understanding Requests

WIDTH Required. The width of the requested

image, expressed in pixels.

An integer between
16 and 2048, inclu­sive.

HEIGHT Required. The height of the requested

image, expressed in pixels.

An integer between
16 and 2048, inclu­sive.

LAYERS Required. The name of a registered MWF file

found in the search path specified by the
MWFSearchPath parameter in config.ini (see
Chapter 3, “Configuring Autodesk
MapGuide LiteView,” in the Autodesk

MapGuide LiteView Servlet Administrator’s
Guide). All layers of the map, visible at the

current scale and not password-protected,
are included in the returned raster image.
Locked layers cause map and feature_info
requests to fail. For more information, see
“LAYERS Parameter,” on page 15.

filename.mwf

A file name without
drive, folder, or
relative path.

FORMAT Required. The format of the requested

image.

“PNG”, “JPEG”, or
“JPG”

SELECT Optional. A list of name-value pairs. The

name portion of the pair is a map layer or
map group name. The value portion is the
feature ID of the map feature that should be
drawn in the selected state. The map-layer
name is the MWF file name followed by a
forward slash and the name of an Autodesk
MapGuide layer within the MWF file. For
more information, see “SELECT Parameter,”
on page 17.

A list of comma-sepa­rated items to select
or highlight.

SRS Optional. Specifies the type of coordi-

nates— latitude/longitude instead of MCS.
Used by the BBOX and SYMBOL parame­ters. For more information, see “SRS Param­eter,” on page 19.

“ADSK:LL84”

Parameters for map Requests (continued)

Parameter Description Content

Creating a map Request | 15

Understanding map Request Parameters

The following sections cover some of the map-request parameters in more
detail than the table on page 13.

LAYERS Parameter

To locate an MWF file, Autodesk MapGuide LiteView concatenates the MWF
name specified in the map request and the value of that MWFSearchPath
parameter specified in config.ini. MWFSearchPath can contain multiple path
names, each of which Autodesk MapGuide LiteView prefixes onto the
LAYERS value and uses to search for the MWF file. Locked layers cause map
and feature_info requests to fail. To specify the value of the LAYERS param­eter in a request, use either the file name or the relative path and file names
of an MWF. You can omit the .mwf extension.

HLS Optional. Specifies one of the highlighting

styles (line thickness, line style, and so on)
that are defined by the config.ini file’s own
HLS parameter(s). Autodesk MapGuide Lite­View assigns a default style if this parameter
is omitted. For more information about con-
fig.ini’s HLS parameter, see Chapter 3, “Con­figuring Autodesk MapGuide LiteView,” in
the Autodesk MapGuide LiteView Servlet
Administrator’s Guide.

An integer between 1
and 4, inclusive.

SYMBOLS Optional. User-defined symbols that identify

map locations. If SYMBOLS is omitted from
the request, map symbols aren’t displayed.
For more information, see “SYMBOLS
Parameter,” on page 20.

A list of comma-sepa­rated items that desig­nate map locations.

PPIY Optional. An integer that represents the cli-

ent browser’s vertical display resolution,
expressed in pixels per inch. If PPIY is omit­ted from the request, Autodesk MapGuide
LiteView uses the default value 72 (the stan­dard resolution for onscreen Web images).
For more information, see “PPIY Parameter,”
on page 19.

An integer between 1
and 2147483647,
inclusive.

Parameters for map Requests (continued)

Parameter Description Content

16 | Chapter 2 Understanding Requests

The following restrictions apply if you use a relative path to specify the
LAYERS parameter value:

■ Absolute paths are not allowed

■ Use only paths relative to the directories specified by the MWFSearchPath

parameter in the config.ini file, with the following exceptions:

❏ Relative paths that move upward in the file structure (paths with ..\,

for example) are not allowed

❏ Relative path names starting with .\ or ./ are not allowed

Autodesk MapGuide Autodesk MapGuide LiteView assumes that MWF
names are relative to the MWFSearchPath pathnames. Below are some exam­ples of valid MWF names, assuming that MyMap.mwf exists in the appro­priate folder:

■ MyMap.mwf

■ MyMap

■ reldir1/reldir2/MyMap

In Windows, you can’t use the following characters in file names:

\/:*?"<>|

Note You can use the backslash (\) as a path separator whether or not you
enclose the MWF name in quotation marks. Names that contain restricted char­acters (covered next) must be enclosed in quotes.

Restricted Characters in the LAYERS Parameter

You can’t use the following characters in a LAYERS parameter value:

■ control characters

■ space

■ forward slash (/)

■ comma (,)

■ ampersand (&)

■ pound (#)

■ percent (%)

■ certain alphanumeric symbols

For more information about restricted characters, visit http://www.w3.org/
Addressing/rfc1738.txt

To use restricted characters in the LAYERS parameter, you must encode them
in hexadecimal, and preface them with a percent symbol. After encoding
restricted characters, enclose the coded file name in quotation marks.

Creating a map Request | 17

If the MWF file name that you want to use in a LAYERS parameter value is
map5&6.mwf, for example, you would encode the ampersand (&) as hexadec­imal %26, and specify the file name as LAYERS=”map5%266.mwf”.

SELECT Parameter

This section describes how to use the SELECT parameter to:

■ Select a feature from a layer

■ Select a feature from a group layer

■ Select multiple features

■ Set the SELECT parameter to a value that contains restricted characters

■ Highlight a selected map feature

You set the SELECT parameter to a list of layer-name, ID pairs. The layer-name
portion of the pair is a map-layer or map-group name. The ID portion of the
pair is the feature ID of a map feature to be drawn in the selected state.

You use the MWF file name followed by a forward slash (/) and the name of
an Autodesk MapGuide layer or group within the MWF, followed by a
comma and the feature ID, as follows:

■ <MwfName>/<LayerNameInMWF>, <feature ID>

■ <MwfName>/<LayerGroupNameInMWF>, <feature ID>

If all the features are on the same layer or in the same layer group, you don’t
have to repeat the second and subsequent names—use a repeated comma
delimiter instead of the names. The following example specifies a map with
two features selected from the roads layer:

SELECT=USA.MWF/Roads,0002,,0005

Selecting Features from a Group Layer

The following SELECT example returns a map with two features selected
from the roads group layer:

SELECT=USA.MWF/RoadsGroupLayer,0002,,0005

Keep the following rules in mind when selecting features from a group layer:

■ The layer name and layer group name must be unique.

■ The feature IDs within a layer group must be unique among layers; other-

wise, only one of the features is selected at random.

■ If the layer name and layer group name are the same, the layer group has

priority over the layer name, and the feature is selected from the layer
group.

18 | Chapter 2 Understanding Requests

Selecting Multiple Features

To select multiple features from a layer or a layer group, use the following
syntax:

SELECT=<MWFName>/[MWFLayerName|MWFLayerGroupName], featureID

(,<MWFName>/[MWFLayerName|MWFlayerGroupName], [featureID])*

Restricted Characters in the SELECT Parameter

You must enclose the layer-name portion of the SELECT parameter
(MWFName/MWFLayerName) in quotation marks if the name contains a space,
a forward slash, or a comma. The operating system doesn’t allow these char­acters in either the MWF name or a relative path. If the layer name already
contains a quotation mark, add another quotation mark in front of it, as
shown in the second and third examples in the following table:

The following example shows how you can enclose the layer name alone in
quotation marks:

hudson_river.mwf/"Rye,NY",0044

If the MWF file name starts with a relative path, you must enclose the entire
path and MWF name in quotation marks. The next example shows an MWF
file name that includes a relative path. In this example, both the MWF file
name and the layer name separately are in quotation marks:

"NYrivers\hudson_river.mwf"/"Rye,NY",0044

The SELECT parameter value in the following map request uses layer names
(X Layer and Z Layer) that require quotation marks because they include
spaces:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=map
&BBOX=26.117831,30.373481,49.340653,68.102723
&WIDTH=600
&HEIGHT=300
&LAYERS=Sample_World.mwf
&FORMAT=PNG

Layer Name Formatted Layer Name

roads, local "roads, local"

roads, "local" "roads, ""local"""

roads,"local "roads,""local"

Creating a map Request | 19

&SELECT="Sample_World.mwf"/"X Layer",0032,

"Sample_World.mwf"/"Z Layer",0004

Highlighting a Selected Map Feature

Use the following procedure to highlight a selected map feature.

To highlight a selected map feature

1 Get the feature ID of the object at the user-selected point.

The source code in the ColdFusion sample application file featureInfo.cfm
shows you how to get the feature ID.

2 Retrieve the feature ID from the XML stream.

To see an example of how to retrieve the feature ID from the XML stream
see the featureInfo.cfm page of the ColdFusion sample application. This
application parses the featureInfo.cfm page in the feature_info frame, sends
a feature_info request to Autodesk MapGuide LiteView, and captures the
XML.

3 Create a map request by using the ID with the SELECT parameter to high-

light the feature, and then send the request. To see an example of how to
create a map request, see the ColdFusion sample application’s map.cfm
page.

For more information about using the SELECT parameter, see “Under­standing the Select And Identify Implementation,” on page 75.

SRS Parameter

If the SRS parameter appears in the map request, Autodesk MapGuide Lite­View interprets coordinates as latitude/longitude. If SRS is absent, Autodesk
MapGuide LiteView interprets the BBOX and SYMBOLS parameters as coor­dinates of the Map Coordinate System (MCS). If SRS is specified, set it to
ADSK:LL84 (the only SRS value supported in this release).

PPIY Parameter

Either the map request or the config.ini file specifies the PPIY value, which
dynamically changes the display resolution of the client browser when
Autodesk MapGuide LiteView responds to a map request. To determine the

20 | Chapter 2 Understanding Requests

resolution of the map, Autodesk MapGuide LiteView takes the following
steps:

■ Autodesk MapGuide LiteView determines whether the application has

specified a client resolution through the PPIY parameter in the map
request.

■ If PPIY is omitted from the request, Autodesk MapGuide LiteView uses the

PPIY parameter defined in config.ini. For information about the config.ini
file, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the
Autodesk MapGuide LiteView Servlet Administrator’s Guide.

You can use PPIY used to increase the vertical pixel resolution of the returned
PNG or JPEG image. When you want to print a Autodesk MapGuide LiteView
map in large scale, increase PPIY to prevent degradation of printed-image
quality.

SYMBOLS Parameter

Your application can use the SYMBOLS parameter to designate one or more
map locations by using user-defined symbols. These locations can mark
places of interest or a route’s start or destination points, for example.
Symbols, which can differ by location, have the following characteristics:

■ Symbol size is independent of map scale, so a symbol’s size is constant at

any zoom level.

■ The symbol can be rotated counterclockwise at an angle expressed in

degrees.

■ An application can label each symbol with a user-defined text string.

Autodesk MapGuide LiteView displays the label below (south of) the sym­bol; if that position would overwrite a feature label, Autodesk MapGuide
LiteView displays the label beside the symbol.

To add symbols to a map, use the SYMBOLS parameter in the map request.

Setting the SYMBOLS Parameter

To add symbols to a map, use the following syntax:

SYMBOLS=<Name>,<X>,<Y>,<Width>,<Height>,[(Rotation)],

[<Label>](,[<Name>],<X>,<Y>,[<Width>],[<Height>],
[<Rotation>],[<Label>])*

Creating a map Request | 21

The following table specifies the SYMBOLS parameter:

Examples of the SYMBOLS Parameter

The following example shows how to use SYMBOLS to insert a single symbol,
TestSymbol, at point (2000, 2000) that is 0.001 x 0.001 meters, rotated 30
degrees, and displayed with the label test:

SYMBOLS=TestSymbol,2000,2000,0.001,0.001,30,test

The next example shows how to insert two instances of TestSymb ol at points
(2000, 2000) and (2500, 2500), rotated 30 degrees, and labeled test1 and test2,
respectively:

SYMBOL=

TestSymbol,2000,2000,0.001,0.001,30,test1,,2500,2500,,,,test2

Default Symbol Layer Styles

You can set the default symbol layer styles in the config.ini file by setting the
SymbolXxx parameters; see Chapter 3, “Configuring Autodesk MapGuide
LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

Specification Description

Name The name of an Autodesk MapGuide API symbol. If a symbol

with the specified name is not found, the default symbol (a
black square) is displayed.

X, Y The insertion point, usually the center, defined by the symbol.

By default, the insertion point is specified in the coordinate sys­tem used by the map MCS, unless it is overridden by the SRS
parameter. If the X, Y elements fall outside the map range then
the symbol is drawn outside the range. The symbol is clipped if
it falls on the edge of the map.

Width, Height The size of the symbol, expressed in meters.

Rotation The angle of rotation for the symbol, expressed in degrees. The

default value is zero degrees. The angle of rotation is measured
counterclockwise from East and is between -360 to +360,
inclusive.

Label A string of up to 254 characters that labels the symbol’s loca-

tion. You must encode the label if it contains special characters
such as $, & and ?; see “Restricted Characters in the LAYERS
Parameter,” on page 16.

22 | Chapter 2 Understanding Requests

Tips for Creating Map Requests

Some important things to remember when creating a map request are:

■ Maps must reside on the same local area network (LAN) as the Autodesk

MapGuide LiteView servlet.

■ You must set the MWFSearchPath parameter in the config.ini file to list the

location of the MWF files. For information about setting this parameter,
see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the
Autodesk MapGuide LiteView Servlet Administrator’s Guide.

■ If you use SELECT to specify multiple layers, designate layers from a single

map.

■ The BBOX parameter must specify an area of the map that falls within the

maximum extents of the authored map; otherwise, Autodesk MapGuide
LiteView displays only the background color of the map.

■ Coordinates in the request must be in map coordinate system (MCS)

units, unless the SRS is set to ADSL:LL84, in which case the coordinates
must be latitude/longitude.

■ All map-request parameter values are case-sensitive except the value of the

REQUEST parameter.

Creating a feature_info Request

You u se a feature_info request in the HTTP get or post request of your appli­cation to obtain feature information about the feature located at a specified
point. The feature_info request has the following format:

<prefix>?

REQUEST=feature_info
&BBOX=<minX>,<minY>,<maxX>,<maxY>
&WIDTH=<integer>
&HEIGHT=<integer>
&LAYERS=<filename.mwf>
&X=<integer>
&Y=<integer>
&PPIY=<integer>

<prefix> is the URL of the Autodesk MapGuide LiteView servlet:
http://<webserver_name>/<context_path>/servlet/MapGuideLiteView

The prefix for the default Autodesk MapGuide LiteView installation is:
http://localhost:8080/liteview6.5/servlet/MapGuideLiteView

For general information about request syntax, see “Formatting a map
Request” on page 11.

Creating a feature_info Request | 23

Example of a feature_info Request

The following example requests feature information from the
Sample_World.mwf file. The request specifies a bounding box with a lower-left
coordinate of (26.117831, 30.373481) and upper-right coordinate of
(49.340653, 68.102723), which identifies the area of interest on the map. The
request also specifies the area’s width and height, expressed in pixels, and the
feature’s XY location, expressed in pixels:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?
REQUEST=feature_info
&BBOX=26.117831,30.373481,49.340653,68.102723
&WIDTH=600
&HEIGHT=400
&LAYERS=Sample_World.mwf
&X=300
&Y=200

Positioning Feature Information

The XY pixel position of the feature information must correspond to the
displayed map, so that your application displays feature information in an
appropriate location. You match the LAYER, BBOX, WIDTH, and HEIGHT
values of the map request and feature_info request to display feature infor­mation correctly. In the ColdFusion sample application map.cfm, for
example, these values are set for Sample_World.mwf as follows:

<cfset mapName = "Sample_World.mwf">
<cfset defaultbbox = "-150.0,0.0,-54.0,92.0">
<cfset width = "500">
<cfset height = "480">

The following excerpt from feature_info.cfm shows that when the ColdFusion
sample application builds the feature_info request, it uses form variables
passed from map.cfm to set LAYER, BBOX, WIDTH, and HEIGHT values to
match those of the map request:

<cfset urlRequest =

"http://" & Form.server & "/servlet/MapGuideLiteView?
REQUEST=feature_info
&HEIGHT=" & Form.height
& "&WIDTH=" & Form.width
& "&LAYERS=" & Form.mapName
& "&BBOX=" & Form.bbox
& "&X=" & Form.MAP.X
& "&Y=" & Form.MAP.Y>

Note The Form.server variable must include the web-server name and context
path. For a default Autodesk MapGuide LiteView installation, Form.server is

24 | Chapter 2 Understanding Requests

“localhost:8080/liteview6.5”. For more information, see “Formatting a map
Request” on page 11.

Understanding feature_info Request Parameters

The following table describes feature_info-request parameters.

Note You must include all the following parameters, except PPIY, in a
feature_info request:

Feature_info Request Parameters

Parameter Description Content

REQUEST Required. Type of request. ”feature_info”

BBOX Required. The bounding box of the

requested map image, specified by the
MCS, unless overridden by the SRS
parameter. The image’s bounding box
should fall within the maximum extents of
the authored map. The first pair of floats
specifies the lower-left X-Y coordinate and
the second pair specifies the upper-right
X-Y coordinate.

minX,minY,maxX,maxY
Floating-point numbers.

WIDTH Required. The width of the requested

image, expressed in pixels.

integer

HEIGHT Required. The height of the requested

image, expressed in pixels.

integer

LAYERS Required. The name of a registered MWF

found in the search path specified by the
MWFSearchPath parameter in config.ini
(see Chapter 3, “Configuring Autodesk
MapGuide LiteView,” in the Autodesk

MapGuide LiteView Servlet Administrator’s
Guide). All layers of the map, visible at the

current scale and not password-protected,
are included in the returned raster image.
Locked layers cause map and feature_info
requests to fail.

Sample_World.mwf

A file name without any
leading drive, folder, or
relative path informa­tion.

Creating a feature_info Request | 25

X Required. The pixel offset in the X direc-

tion that identifies the feature of interest.
The upper-left corner of map image is at
0,0. Increase the value of X to move the
right.

integer

Y Required. The pixel offset in the Y direc-

tion that identifies the feature of interest.
The upper-left corner of map is at 0,0.
Increase the value of Y to move down.

integer

PPIY Not used. The screen’s vertical resolution,

expressed in pixels per inch. This parame­ter is not used from the map request, but
is taken from config.ini (or set to 72 by
default).

An integer between 1
and 2147483647, inclu­sive.

Feature_info Request Parameters (continued)

Parameter Description Content