Introduction to ArcXML

ArcXML is the protocol for communicating with the ArcIMS Spatial Server. An ArcIMS Spatial Server is the backbone of ArcIMS and provides the functional capabilities for accessing and bundling maps and data into the appropriate format before sending the data back to a client. In order to understand ArcXML, it is first necessary to understand how configuration files, ArcIMS services, requests, and responses relate to each other and how they interact with the ArcIMS Spatial Server.

The figure below is a diagram showing the interaction between the ArcIMS Spatial Server and configuration files, services, requests, and responses. The numbers in the diagram reflect the different steps involved in communicating with the ArcIMS Spatial Server:

In Step 1, you create a configuration file.
In Step 2, you use ArcIMS Administrator to start an ArcIMS Service on the ArcIMS Spatial Server. The configuration file from Step 1 is the input to the service.
In Step 3, the ArcIMS Spatial Server receives a request in ArcXML.
In Step 4, the ArcIMS Spatial Server generates a response in ArcXML.

Step 1: Creating a Configuration File

In Step 1, a configuration file is generated. You create a map configuration file for Image and Feature Services using ArcIMS Author or by using a text or XML editor. For Metadata Services, you create a metadata configuration file using a text or XML editor. For ArcMap Image Services, you use ArcMap to generate an ArcMap document, which is treated the same as a map configuration file by ArcIMS. These files are in binary format and cannot be edited outside of ArcMap.

The next figure shows a map in ArcIMS Author with two layers: STATES and CITIES.

When this file is saved in ArcIMS Author, the result is a map configuration file, written in ArcXML, containing layer information on STATES and CITIES. The file has an *.axl extension. In this example, assume the file is named usa.axl.

Usa.axl map configuration file using ArcXML

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>
      <LOCALE country="US" language="en" variant="" />
      <UIFONT color="0,0,0" name="Arial" size="12" style="regular" />
    </ENVIRONMENT>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-125" miny="25" maxx="-67" maxy="50" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
        <FEATURECOORSYS id="4326" />
        <FILTERCOORSYS id="4326" />
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-0" directory="C:\ESRIDATA\USA" />
      </WORKSPACES>
      <LAYER type="featureclass" name="States" visible="true" id="States">
        <DATASET name="STATES" type="polygon" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL fillcolor="0,0,255" filltype="solid" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Cities" visible="true" id="Cities">
        <DATASET name="CITIES" type="point" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEMARKERSYMBOL color="255,0,0" width="6" />
        </SIMPLERENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The element that distinguishes a map configuration file from a request or response is CONFIG. Elements within the CONFIG element, such as PROPERTIES, WORKSPACES, and LAYER, help define the characteristics of the map.

Step 2: Starting an ArcIMS Service

An ArcIMS service is a process that runs on the ArcIMS Spatial Server. You can think of a service as a portal to the Spatial Server. Spatial Server functionality is accessible only through services running on the server.

In Step 2, a map configuration file, such as usa.axl or an ArcMap document (*.mxd or *.pmf), is the input to an ArcIMS service. When starting a service, you must assign the service to a Feature Server, Image Server, or ArcMap Server. The naming of an ArcIMS service is independent of the name of the input map configuration file. For example, usa.axl can be the input file to an Image Service named usa_image.

A map configuration file provides drawing instructions for each layer in the service. For example, the usa_image service is instructed, by default, to draw the STATES layer with a blue polygon fill and the CITIES layer with a red marker.

Step 3: Sending a Request

In Step 3, once an ArcIMS service such as usa_image is running on the ArcIMS Spatial Server, requests can be sent to the service. Requests are generated by a client such as the ArcIMS HTML Viewer, Java Viewers, or any viewers using the ColdFusion Connector, ActiveX Connector, Java Connector, or .NET Link. The requests are:

The element that distinguishes a request from other types of ArcXML files is REQUEST. For example, to request a map, a GET_IMAGE request can be made:

A sample request

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_IMAGE>
      <PROPERTIES>
        <ENVELOPE minx="-125" miny="25" maxx="-67" maxy="50" />
      </PROPERTIES>
    </GET_IMAGE>
  </REQUEST>
</ARCXML>

When the above request is sent to the usa_image service, the result is a map that looks like the original map defined in ArcIMS Author. The layer symbol definitions from the service are used: blue for the states and red for the cities.

A request can also override some of the information in a service by asking for a new map at a different scale, turning layers on and off, requesting a subset of the attribute data, changing the projection, or adding acetate layers, among other things. With an Image Service, a request can also be used to change the rendering of a layer or add new data in dynamic layers. In the next example, a request is sent to the usa_image service asking for information at a new zoom scale and changing the color of the States layer from blue to yellow.

Request to change the zoom area and layer color of an ArcIMS service

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_IMAGE>
      <PROPERTIES>
        <ENVELOPE minx="-88" miny="30" maxx="-67" maxy="50.0" />
        <IMAGESIZE width="500" height="350" />
        <LAYERLIST>
          <LAYERDEF id="States" visible="true" >
            <SIMPLERENDERER>
              <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,255,0" />
            </SIMPLERENDERER>
          </LAYERDEF>
        </LAYERLIST>
      </PROPERTIES>
    </GET_IMAGE>
  </REQUEST>
</ARCXML>

The new map, when drawn, has new rendering for the States layer and is zoomed in to a new scale.

Note that because of architectural differences with the ArcMap Server, layer rendering and symbology cannot be changed through a request to an ArcIMS Image Service. Using the same request above, the same extent would show, but the rendering for the States layer would not change from what is in the ArcMap document.

Step 4: Receiving a Response

In Step 4, when the ArcIMS Spatial Server processes a request, the results are returned in a response. The element that distinguishes a response from other types of ArcXML files is RESPONSE. For example, an IMAGE response contains the name and location of the map generated during a GET_IMAGE request. The following example shows a possible IMAGE response from the usa_image service.

A sample response

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <RESPONSE>
    <IMAGE>
      <ENVELOPE minx="-87.5" miny="30.0" maxx="-59.5" maxy="50.0" />
      <OUTPUT url="http://mycomputer.domain.com/output/usa_image_MYCOMPUTER2953026.jpg" />
    </IMAGE>
  </RESPONSE>
</ARCXML>

There are nine request and response pairs in ArcIMS:

Request	Response	More Information
GET_IMAGE	IMAGE	Using GET_IMAGE and IMAGE with Image Services Using GET_IMAGE and IMAGE with ArcMap Image Services
GET_FEATURES	FEATURES	Using GET_FEATURES and FEATURES
GET_GEOCODE	GEOCODE	Summary of Geocoding Elements
GET_EXTRACT	EXTRACT	Using GET_EXTRACT and EXTRACT
GET_SERVICE_INFO	SERVICEINFO	Using GET_SERVICE_INFO and SERVICEINFO with Image and Feature Services Using GET_SERVICE_INFO and SERVICEINFO with ArcMap Image Services
GET_LAYOUT	LAYOUT	Using GET_LAYOUT and LAYOUT with ArcMap Image Services
GET_RASTER_INFO	RASTER_INFO
GET_METADATA	METADATA
PUBLISH_METADATA	Refer to child elements of PUBLISH_METADATA