Using Configuration Files

Using Configuration Files

Introduction
Map Configuration Files
Viewer Configuration Files
Default.axl: A Special Viewer Configuration File
- Framework of default.axl
- Relationship between Feature MapServices and default.axl
Comparing Different CONFIG Files

Introduction

Configuration files are used to define a map. There are three types of configuration files:

A map configuration file. This file is created using ArcIMS Author or an XML editor and is used as input to a MapService.
A viewer configuration file. This file is generated when a map in ArcExplorer 3 or an ArcIMS Java Viewer is saved.
Default.axl. This file is a special type of viewer configuration file that is generated during the ArcIMS Designer process and is used as input to the ArcIMS Java Viewers.

The following sections cover configuration files in detail. The first section discusses map configuration files. The second section covers viewer configuration files. The third section reviews default.axl. A final section provides a summary review of the similarities and differences among the three configuration file types.

Map Configuration Files

Map configuration files are used as input to MapServices. All information in a map configuration file provides a default set of instructions for map properties and rendering. Requests can override information in the MapService properties, but if the request does not include the element, then the default MapService properties prevail. The diagram below shows the flow for creating a MapService using a map configuration file as input.

In Step 1, data sources are referenced and rendered. This process takes place using ArcIMS Author or by using a text or XML editor. If non-English characters are used for layer names or font names, either ArcIMS Author or an XML editor must be used. Text editors do not display non-English characters correctly.
In Step 2, when a session is saved in ArcIMS Author or an XML editor, the output is a map configuration file. Note that data sources are not included in the file, only references to the data. The information in a map configuration file provides a default set of instructions for map properties and rendering.
In Step 3, the map configuration file is used as input in ArcIMS Administrator to start a MapService.
In Step 4, once the MapService has been started, it runs as a process on the ArcIMS Spatial Server and is ready to receive requests.

Framework of a map configuration file

A map configuration file can be divided into several sections. The following example shows the basic framework.

Framework of a map configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>...</PROPERTIES>
      <WORKSPACES>...</WORKSPACES>
      <LAYER>...</LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

A map configuration file includes:

A prolog which is used to define the XML version and encoding.
An ARCXML element, which is used in all ArcXML statements.
A CONFIG element, which is used in all configuration files.
An ENVIRONMENT element, which is used to define the locale.
A MAP element, which is used to define the map.

ARCXML and the prolog

The first line of an ArcXML statement is the prolog. All ArcXML 1.1 statements are required to use a standard prolog that includes the XML version and encoding. The XML version is 1.0. Encoding in ArcXML 1.1 is UTF8. UTF-8 and UTF8 can be used interchangeably in map configuration files, but ArcIMS Author writes configuration files using UTF-8.

After the prolog, all ArcXML statements begin and end with ARCXML. This element is required, and the version number is 1.1.

Prolog and ARCXML:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML>
...
</ARCXML>

CONFIG, ENVIRONMENT, and MAP

A map configuration file distinguishes itself from a REQUEST or RESPONSE by the CONFIG element. For more information on the relationship between map configuration files, requests, and responses, see Introduction to ArcXML.

The only child elements to CONFIG in a map configuration file are ENVIRONMENT and MAP.

CONFIG, ENVIRONMENT, and MAP:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>...</MAP>
  </CONFIG>
</ARCXML>

ENVIRONMENT is used to set up information about the environment used in the MapService. Once the environment is established, clients in one locale can access a MapService created in another locale. Child elements of ENVIRONMENT include the following:

LOCALE. (Required) LOCALE is used to set the country and language for the locale of the ArcIMS site. This information is based on settings in the operating system. For example, in the United States, the country is "US" and the language is "en". Some characteristics of the United States locale include using English alphabetic characters and a decimal point (.) to represent number fractions such as 123.456.

In Germany, the country is "DE" and the language is "de". Some characteristics of the German locale include using non-English characters and a comma (,) to represent number fractions such as 123,456.
UIFONT. (Required) UIFONT is used to set a default font for the dialogs in ArcExplorer 3 and the ArcIMS Java Viewers.
SEPARATORS. (Optional) SEPARATORS is used to denote characters to separate x- and y-coordinates and coordinate pairs. By default, x- and y-coordinates are separated by a space and coordinate pairs are separated by a semicolon (;). These separators can be changed using SEPARATORS. The attribute cs is the coordinate separator and is used to separate an x-coordinate from a y-coordinate. The attribute ts is the tuple separator and is used to separate x- and y-coordinate pairs.
SCREEN. (Optional) SCREEN is used to set the resolution of the screen for the computer generating the map configuration file. This value is important for computing scale dependencies. By default, the dots per inch (dpi) is assumed to be 96 dpi. This is the value for most machines with a display size set to 1024 x 768 pixels.

ENVIRONMENT and its child elements:

The element MAP contains all the instructions for generating a map. This includes the map

PROPERTIES. The PROPERTIES section includes the initial map extent, map units, and current projection, as well as additional instructions used for Image MapServices.
WORKSPACES. The WORKSPACES section includes the location of all the data used to create map layers.
LAYER. One LAYER element is used for each layer in a map. LAYER contains the information about how the data should be symbolized.

MAP and its child elements:

The PROPERTIES, WORKSPACES, and LAYER elements are discussed in detail in the next sections.

MAP: PROPERTIES

PROPERTIES provides the framework for defining properties about a MapService. The child element ENVELOPE is required but all other child elements are optional. The child elements shown in the following example are used in both Image and Feature MapServices.

PROPERTIES and its child elements for both Feature and Image MapServices:

ENVELOPE. In a map configuration file, ENVELOPE defines the initial extent for display. The initial extent is made up of a rectangle bounded by minimum and maximum x- and y-coordinates. In the next example, the initial extent uses decimal degree coordinates.

Using ENVELOPE:

Note the attribute reaspect was included in the above example. This attribute indicates whether the ENVELOPE should be stretched to fit the viewing area in the client. By default, reaspect is set to true and the pixel width and height ratio stays the same. By setting reaspect to false, the pixel width and height are stretched to fit the viewing area. The following two figures show the difference when reaspect is used. The figure on the left has reaspect set to true. The ENVELOPE is recalculated so that the map does not stretch. The figure on the right has reaspect set to false, and the map has been stretched to fit the viewing area.

Reaspect set to true

Reaspect set to false

MAPUNITS. MAPUNITS defines the units of the data used in the map. Units are decimal degrees, feet, or meters. If the elements FEATURECOORDSYS and FILTERCOORDSYS are not present, the author of the map configuration file is responsible for determining the MAPUNITS. If MAPUNITS is not included, the assumption is that the MAPUNITS are in decimal degrees. When MAPUNITS is incorrectly specified, measurements, buffers, and other functions using scales will not be correct, and the requested map may not contain any data. If FEATURECOORDSYS and FILTERCOORDSYS are present, the correct MAPUNITS is automatically selected by the ArcIMS Spatial Server. If MAPUNITS is included in the map configuration file, it is ignored.

BACKGROUND. BACKGROUND defines a color for the image background. It can also be used to make one color in the image transparent. Depending on the browser, the image formats that support transparent colors vary. JPG images do not support transparent colors. The table below lists which image formats support transparent colors for different browsers.

Browser	Supported transparent image formats
ArcIMS HTML Viewer in Internet Explorer	PNG8, GIF
ArcIMS HTML Viewer in Netscape 4.x	GIF
ArcIMS HTML Viewer in Netscape 6.x	PNG8, GIF
ArcExplorer 3	PNG24, PNG8, GIF
ArcIMS Java Viewers in Internet Explorer and Netscape	PNG24, PNG8, GIF

To make a color transparent, both the color and transcolor attributes of BACKGROUND must be set to the same color. When a color is set to transparent, layers underneath the transparent part of the image can be seen.

When the ArcIMS HTML Viewer is used, BACKGROUND added to the MapService is overridden by BACKGROUND in requests from the HTML Viewer. When the ArcIMS Java Viewers and ArcExplorer 3 are used, the BACKGROUND in the MapService is used by default and is not overridden.

FEATURECOORDSYS and FILTERCOORDSYS. FEATURECOORDSYS and FILTERCOORDSYS set the projection of the MapService. For an overview of the projection elements, see Using Projection Elements.

The following child elements are valid only with Image MapServices and are more commonly used in requests than in a map configuration file:

PROPERTIES and its child elements valid only with Image MapServices (in bold):

LEGEND. LEGEND defines a map's legend for an Image MapService. This legend is valid only in customized ArcIMS HTML Viewers and not in the ArcIMS Java Viewers or ArcExplorer 3. When LEGEND is included in the map configuration file, a legend image is always generated. However, this legend is ignored by the default ArcIMS HTML Viewer. The HTML Viewer generates a legend upon request and ignores any other generated legends. For more information on using LEGEND, see the LEGEND section in Using GET_IMAGE and IMAGE.
OUTPUT. OUTPUT defines a location and filename for the output maps and legend image files. If OUTPUT is not defined, the image output directory and URL location are determined at the time the MapService is started, and the ArcIMS Spatial Server assigns a filename. The ArcIMS Tasker, a Windows service or UNIX daemon, automatically deletes these generated images on a user-specified interval.

When OUTPUT is used in a map configuration file, the OUTPUT information overrides the output information stored when the MapService is started. When OUTPUT is used, the output files are not automatically deleted by ArcIMS Tasker. In order for the files to be deleted, the taskfile property must be set in tasker.properties. For information on setting this property, see the topic "Setting up ArcIMS Monitor and ArcIMS Tasker Property Files" in the System Administration: Administering Property Files chapter of the ArcIMS Help Contents.

When using an ArcIMS HTML Viewer, ArcIMS Java Viewer, ArcExplorer 3, or any other browser using the ArcIMS Servlet Connector, the OUTPUT element is restricted by default. In a map configuration file, OUTPUT is ignored. This restriction can be lifted by setting the property spatialServer.AllowRequestOutput to true in esrimap_prop. This property file is found in the servlet engine directory. For more information on the location of esrimap_prop and its properties, see the topic "Administering the ArcIMS Servlet Connector" in the System Administration chapter of the Using ArcIMS Help Contents.

These restrictions apply only when the ArcIMS Servlet Connector is used. They do not apply to the ActiveX or ColdFusion Connectors or to other connectors using the ArcIMS Application Server Link. The OUTPUT filename extensions are restricted to *.jpg, *.png, or *.gif, regardless of whether OUTPUT is restricted or not.

In general, it is not recommended to use OUTPUT in a map configuration file unless all requests can use the same output map or legend. Instead, if OUTPUT is needed, it should be used in GET_IMAGE and GET_EXTRACT requests. During a request, more information is known about the requesting client, and the output location and name can be tailored for that client. For more details on using OUTPUT, see the OUTPUT section in Using GET_IMAGE and IMAGE.

MAP: WORKSPACES

WORKSPACES specifies the location of all the data used in the map configuration file. All data locations must be visible to any computer hosting MapServices. Each workspace must have a unique reference name. Valid WORKSPACES in map configuration files are:

SHAPEWORKSPACE. Used to reference directories with shapefiles.
IMAGEWORKSPACE. Used to reference directories with images. Images can be accessed individually, as an image directory where all images in one directory can be tiled, or as image catalogs. A complete list of supported images is found in Using ArcIMS.
SDEWORKSPACE. Used to reference layers in ArcSDE. The layers can be raster or vector layers. Either ArcSDE or ArcSDE direct connect can be used.

Valid WORKSPACES in a map configuration file:

MAP: LAYER

LAYER is the parent element for defining a map layer. Attributes cannot be overridden by a request. The following attributes are required:

Id is a unique ID for a layer. When using ArcIMS Author, layers are assigned a number. However, the ID can be any combination of alpha and numeric characters. Each layer must have a unique ID or an error will result when trying to start a MapService.
Type specifies layer type. Use "featureclass" for shapefiles and ArcSDE vector layers. Use "image" for raster image files, GRIDs, and ArcSDE raster layers. Use "acetate" for adding graphics on top of the map.

The following attributes are optional:

Name is used for the layer name displayed in the legend in all ArcIMS Viewers. If name is not included, the ArcIMS Java Viewers use the LAYER id, and the HTML Viewer displays a blank name. It is highly recommended to always use name.
Maxscale and minscale are used to set the maximum and minimum scales that the layer displays. A relative scale can be used, such as 1:24000, or the scale can be calculated as the number of map units per pixel. The method for calculating units per pixel is shown with the LAYER element information. If these attributes are not used, the layer displays at all scales.

Applying maximum and minimum scales to a layer is a very important part of authoring map configuration files. The user should only see data that is relevant and useful at any given scale. If a layer has very detailed information, then this layer should not be available until the user has zoomed in to an appropriate level. The less data that must be accessed and rendered, the faster the map is drawn or data is transferred. A general rule of thumb is that a map should contain no more than 500 or so features at a given scale. In some cases, there may be more features, but realize that the amount of time to generate the map increases, especially when a map is projected.
Visible specifies whether the layer is turned on or off in the legend when the map is first accessed. If the ArcIMS Java Custom Viewer is used, selecting which layers to have visible is done during the ArcIMS Designer process. This overrides visible in the MapService. All other ArcIMS Viewers read visible directly from the MapService.

Sample LAYER with attributes:

MAP: LAYER child elements

A LAYER used in a map configuration file has several child elements. The purpose of these elements is to identify the data source and to render the data.

LAYER with child elements:

The types of child elements can be divided into several groups: DATASET, projection elements, query elements, EXTENSION elements, and renderer and symbol elements.

DATASET is required for a layer. It defines which data from a workspace to use. Information in DATASET cannot be overridden by a request.

The attribute name is required. For shapefiles, use the name of the data file without an extension such as STATES. For ArcSDE, use the full name of the layer such as DATA.STATES. For images, the name depends on the method for accessing an image. For more details on naming images, see the table in the Notes section in DATASET.

The attribute type is required for vector data and optional for image data. The value for type must match the shapefile or ArcSDE layer type: "point", "line", or "polygon". For images, always use the value "image".

The attribute workspace is required and references which workspace the data layer is in. The workspace value must be listed under WORKSPACES.
The projection elements COORDSYS and DENSIFY are used if the data layer is in a different projection than the MapService. These elements are metadata stating what projection the layer is in, but they do not reproject the data. For more information on the projection elements see Using the Projection Elements.
The query elements SPATIALQUERY and QUERY are used to select a subset of the layer. SPATIALQUERY should be used for both tabular and spatial queries. QUERY should only be used in stored queries.

When SPATIALQUERY is used with a layer in a map configuration file, a filter is set on a subset of the data and only that subset is available for viewing. When a request is made with SPATIALQUERY, the data outside of the MapService subset cannot be accessed.
The EXTENSION element is used to define geocoding, stored queries, and extract parameters for a layer. All three extensions can be used for a single layer, but each EXTENSION can only have one set of child elements.

For geocoding, use GCSTYLE. This extension sets up the type of geocoding that is permitted on the layer. More information on geocoding is available in Summary of Geocoding Elements.

For setting up parameters for the Extract Server, use EXTRACTPARAMS. Using this extension allows HTML clients to send requests that extract specified layers of a MapService into a set of shapefiles, yielding one shapefile for each layer. More information on the Extract EXTENSION is available in Using GET_EXTRACT and EXTRACT.

For setting up a stored query, use STOREDQUERIES. A stored query sets up a predefined query used in the ArcIMS Viewers.

The renderer and symbol elements are used to define the symbology and labeling for each layer in the map. The relationship between a renderer and a symbol in ArcXML is

      <RENDERER>
        <SYMBOL />
      </RENDERER>

Six renderers are available in ArcIMS.

VALUEMAPRENDERER and VALUEMAPLABELRENDERER also have three child elements used to create value maps.

Only one symbol or label at a time can be used inside a renderer. However, the renderers can be used in different combinations to create complex symbols at different scales.

Valid symbols inside SIMPLERENDERER and VALUEMAPRENDERER are

Point layers:
Line layers:
- All the symbols valid for point layers
- HASHLINESYMBOL
- SIMPLELINESYMBOL
Polygon layers:
- All the symbols valid for point and line layers
- GRADIENTFILLSYMBOL
- RASTERFILLSYMBOL
- SIMPLEPOLYGONSYMBOL

Valid symbols inside SIMPLELABELRENDERER and VALUEMAPLABELRENDERER are

For more detailed information on the renderers, see Using Renderer Elements.

Sample map configuration file

The following map configuration file uses many of the elements discussed above.

Example map configuration file:

<?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" />
      <SCREEN dpi="96" />
    </ENVIRONMENT>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-135.0" miny="-64.0" maxx="84.0" maxy="86.0" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-4" directory="<path to WORLD ESRIDATA>" />
      </WORKSPACES>
      <LAYER type="featureclass" name="Oceans" visible="true" id="0">
        <DATASET name="WORLD30" type="polygon" workspace="shp_ws-4" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL fillcolor="51,153,255"/>
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Countries" visible="true" id="1">
        <DATASET name="country" type="polygon" workspace="shp_ws-4" />
        <GROUPRENDERER>
          <VALUEMAPRENDERER lookupfield="POP_CNTRY">
            <RANGE lower="0" upper="50000000" label="Less than 50000000">
              <SIMPLEPOLYGONSYMBOL fillcolor="255,255,0"/>
            </RANGE>
            <RANGE lower="50000001" upper="100000000" label="50000000 - 100000000">
              <SIMPLEPOLYGONSYMBOL fillcolor="255,170,0" />
            </RANGE>
            <RANGE lower="100000001" upper="1281008319" label="Greater than 100000000">
              <SIMPLEPOLYGONSYMBOL fillcolor="255,85,0"/>
            </RANGE>
          </VALUEMAPRENDERER>
          <SCALEDEPENDENTRENDERER upper="1:35000000">
            <SIMPLELABELRENDERER field="CNTRY_NAME">
              <TEXTSYMBOL antialiasing="true" font="Arial Bold" fontstyle="bold" fontsize="12" />
            </SIMPLELABELRENDERER>
          </SCALEDEPENDENTRENDERER>
        </GROUPRENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The map configuration file contains information on the locale, map properties, workspaces, and how each layer should be drawn. In the ENVIRONMENT section, the LOCALE country and language are the "US" and "En". For UIFONT, the default font of Arial is used, and the default dpi in SCREEN is 96. The PROPERTIES elements show that the MAPUNITS are in decimal degrees and the ENVELOPE coordinates are -135.0,-64.0 and 84.0,86.0. In the WORKSPACES section, one SHAPEWORKSPACE is included for shapefiles in the WORLD ESRIDATA data set.

The map contains two layers:

Ocean. This layer contains one renderer, SIMPLERENDERER. The layer has a solid blue fill as described in SIMPLEPOLYGONSYMBOL.
Countries. This layer contains several renderers. A VALUEMAPRENDERER is used to define how each country should be colored based on population. Countries with a population less than 50 million are yellow, those with a population between 50 and 100 million are light orange, and those with a population greater than 100 million are dark orange. A SCALEDEPENDENTRENDERER is used for labeling. The labels do not turn on until the scale is less than 1:35000000.

The following figure shows a map drawn based on the instructions in the map configuration file.

If the initial extent is changed so the scale is less than 1:35000000, the map zooms in enough so that labels for countries appear.

Change in initial ENVELOPE:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-13.0" miny="36.0" maxx="34.0" maxy="69.0" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>...</WORKSPACES>
      <LAYER>...</LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The following figure shows a map at a scale of about 1:35000000 and includes labels.

Viewer Configuration Files

Viewer configuration files are the output when a file is saved in ArcExplorer 3 or the ArcIMS Java Viewers. The diagram below provides a more detailed flow of the process to create a viewer configuration file:

In Step 1, MapServices and local data sources are accessed and viewed in ArcExplorer 3 or an ArcIMS Java Viewer.
In Step 2, when a session is saved, the output is a viewer configuration file.

Framework of a viewer configuration file

The framework of a viewer configuration file is similar to a map configuration file. The framework includes the CONFIG, ENVIRONMENT, and MAP elements. These elements function the same in both map and viewer configuration files. PROPERTIES is fundamentally the same as well, but only ENVELOPE and MAPUNITS are included.

In many cases a viewer configuration file can look just like a map configuration file. This is true when only local data sources are included in the file and the only WORKSPACES present are SHAPEWORKSPACE, IMAGEWORKSPACE, and SDEWORKSPACE.

Viewer configuration files can contain additional elements that are not in a map configuration file. The following example shows some of these elements.

Example viewer configuration file:

<?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" />
      <SCREEN dpi="96" />
    </ENVIRONMENT>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-178.0" miny="12.89" maxx="-68.0" maxy="83.59" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
        <IMAGESERVERWORKSPACE name="mapper_ws-6" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" service="background" />
        <FEATURESERVERWORKSPACE name="ifs_ws-7" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" service="states" />
        <AVIMSWORKSPACE name="av_ws-6" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" view="Roads" map="roads21204240" />
        <MOIMSWORKSPACE name="mo_ws-4" url="http://mymachine.domain.com/scripts/esrimap.dll" service="GPS_Points" />
        <SHAPEWORKSPACE name="shp_ws-8" directory="<path to CANADA ESRIDATA" />
      </WORKSPACES>
      <LAYER type="image" name="Background" visible="true" id="0">
        <DATASET name="background" type="image" workspace="mapper_ws-6" />
      </LAYER>
      <LAYER type="featureclass" name="States" visible="true" id="1">
        <DATASET name="2" type="polygon" workspace="ifs_ws-7" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL boundarytransparency="1.0" filltransparency="1.0" fillcolor="255,255,153" boundarycaptype="round" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Provinces" visible="true" id="2">
        <DATASET name="province" type="polygon" workspace="shp_ws-8" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL boundarytransparency="1.0" filltransparency="1.0" fillcolor="127,27,27" boundarycaptype="round" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="image" name="Roads" visible="true" id="3">
        <DATASET name="mymachine.domain.com:roads21204240:Roads" type="image" workspace="av_ws-6" />
        <IMAGEPROPERTIES transparency="0.80" />
      </LAYER>
      <LAYER type="image" name="GPS Points" visible="true" id="4">
        <DATASET name="mymachine.domain.com:GPS_Points" type="image" workspace="mo_ws-4" />
      </LAYER>
    </MAP>
    <OVERVIEWMAP backgroundcolor="255,255,255" framefillcolor="255,0,0,80" frameoutlinecolor="255,0,0" zoomfactor="4.0">
      <LAYERDEF name="States" />
      <LAYERDEF name="Provinces" />
    </OVERVIEWMAP>
    <SCALEBAR backcolor="212,208,200" fontcolor="0,0,0" mapunits="decimal_degrees" scaleunits="feet" screenunits="inches" />
  </CONFIG>
</ARCXML>

The additional elements are:

IMAGESERVERWORKSPACE. IMAGESERVERWORKSPACE is included in the WORKSPACES section when an Image MapService is accessed.
FEATURESERVERWORKSPACE. FEATURESERVERWORKSPACE is included in the WORKSPACES section when a Feature MapService is accessed.
MOIMSWORKSPACE and AVIMSWORKSPACE. These two elements are included in the WORKSPACES section when a map is accessed from an ArcExplorer-enabled map in MapObjects IMS or from ArcView IMS, respectively.
SCALEBAR and OVERVIEWMAP. These two elements are client configuration elements that add a scale bar or overview map, respectively.

Each of these elements is described below.

IMAGESERVERWORKSPACE

IMAGESERVERWORKSPACE is used in the WORKSPACES section for Image MapService layers.

Using IMAGESERVERWORKSPACE:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>...</PROPERTIES>
      <WORKSPACES>
        <IMAGESERVERWORKSPACE name="mapper_ws-6" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" service="background" />
      </WORKSPACES>
      <LAYER type="image" name="Background" visible="true" id="0">
        <DATASET name="background" type="image" workspace="mapper_ws-6" />
      </LAYER>
    </MAP>
    <OVERVIEWMAP>...</OVERVIEWMAP>
    <SCALEBAR ... />
  </CONFIG>
</ARCXML>

References to an Image MapService in IMAGESERVERWORKSPACE are made in the service attribute. In the above example, the name of the Image MapService is "background". The url attribute gives the location of the Image MapService. In the example, the location is "http://mymachine.domain.com". In addition to the domain, the location of the ArcIMS servlet connector is also included. This information is the same for all ArcIMS sites and is "/servlet/com.esri.esrimap.Esrimap".

For the Image MapService layer, references to the MapService are made in DATASET. The attribute name is the same as IMAGESERVERWORKSPACE service. In this example, the name is "background". The DATASET type is always "image". Image MapService layers are always treated as one layer in a viewer configuration file, and the sublayers are not included.

FEATURESERVERWORKSPACE

FEATURESERVERWORKSPACE is used in the WORKSPACES section for Feature MapService layers.

Using FEATURESERVERWORKSPACE:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>...</PROPERTIES>
      <WORKSPACES>
        <FEATURESERVERWORKSPACE name="ifs_ws-7" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" service="states" />
      </WORKSPACES>
      <LAYER type="featureclass" name="States" visible="true" id="1">
        <DATASET name="2" type="polygon" workspace="ifs_ws-7" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL boundarytransparency="1.0" filltransparency="1.0" fillcolor="255,255,153" boundarycaptype="round" />
        </SIMPLERENDERER>
      </LAYER>
    </MAP>
    <OVERVIEWMAP>...</OVERVIEWMAP>
    <SCALEBAR ... />
  </CONFIG>
</ARCXML>

References to a Feature MapService in FEATURESERVERWORKSPACE are made in the service attribute. In the above example, the name of the Feature MapService is "states". The url attribute is used the same way as with Image MapService. In the example, the location of the ArcIMS Servlet Connector is "http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap".

Each layer in a Feature MapService is treated as a separate layer, and each layer can be accessed individually. In the above example, only one layer of a Feature MapService has been accessed.

For a Feature MapService layer, DATASET is always included, and rendering information is usually included. In DATASET, the attribute type is set to the same type as in the Feature MapService. In the above example the type is "polygon". The attribute name is set to the LAYER id in the Feature MapService. In this example, the LAYER id in the Feature MapService is "3", and therefore the DATASET name in the viewer configuration file is "3". The following examples highlight the differences between the map configuration file used as input to the Feature MapService and the output in the viewer configuration file.

Map configuration file used in the Feature MapService:

Viewer configuration file:

In the map configuration file, the LAYER id is "3", which is unique within the map configuration file, and the DATASET name is "STATES" and refers to a shapefile in the "shp_ws-1" workspace. In the viewer configuration file, the LAYER id is "1", which is unique within the viewer configuration file. The DATASET name is "3", which refers to the LAYER id in the map configuration file. The workspace reference is "ifs_ws-7", which refers to the workspace for the Feature MapService. The rest of the layer information in the map and viewer configuration files is identical.

When using ArcExplorer 3 and when permission is given in the ArcIMS Java Viewers, the layer rendering can be changed using the Layer Properties Dialog. In the following example, the States layer is rendered in light yellow by default.

Default viewer configuration file:

If a user changes the rendering, this new information is stored in the viewer configuration file. The change is local and does not affect the Feature MapService. In the next example, the rendering is changed from light yellow to various colors based on the population of each state.

After layer rendering has been changed in the viewer configuration file:

Remember that in a viewer configuration file, any rendering changes remain local to the machine that the configuration file resides on. The change does not affect the Feature MapService.

AVIMSWORKSPACE

AVIMSWORKSPACE is used in the WORKSPACES section to reference a map generated from ArcView IMS.

Using AVIMSWORKSPACE:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>...</PROPERTIES>
      <WORKSPACES>
        <AVIMSWORKSPACE name="av_ws-6" url="http://mymachine.domain.com/servlet/com.esri.esrimap.Esrimap" view="Roads" map="roads21204240" />
      </WORKSPACES>
      <LAYER type="image" name="Roads" visible="true" id="3">
        <DATASET name="mymachine.domain.com:roads21204240:Roads" type="image" workspace="av_ws-6" />
        <IMAGEPROPERTIES transparency="0.80" />
      </LAYER>
    </MAP>
    <OVERVIEWMAP>...</OVERVIEWMAP>
    <SCALEBAR ... />
  </CONFIG>
</ARCXML>

AVIMSWOKSPACE references a map in ArcView IMS using the attributes view and map. The values for these attributes are the ArcView IMS MapName and ViewName, respectively, and can be found in the applet HTML file of an ArcView IMS MapCaf� web site. For example, if the web site is named "MySite", open "MySiteapplet.html". Look for the parameters MapName and ViewName. For more information on using ArcView IMS with ArcIMS, see Appendix B of Using ArcIMS. As with other WORKSPACES types, the url attribute references the ArcIMS servlet connector.

The DATASET name for the layer references the machine and domain, MapName, and ViewName separated by colons (:). In the above example, the DATASET name is "mymachine.domain.com:roads21204240:Roads".

MOIMSWORKSPACE

MOIMSWORKSPACE is used in the WORKSPACES section to reference an ArcExplorer-enabled map generated from MapObjects IMS.

Using MOIMSWORKSPACE:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>
      <PROPERTIES>...</PROPERTIES>
      <WORKSPACES>
        <MOIMSWORKSPACE name="mo_ws-4" url="http://mymachine.domain.com/scripts/esrimap.dll" service="GPS_Points" />
      </WORKSPACES>
      <LAYER type="image" name="GPS Points" visible="true" id="4">
        <DATASET name="mymachine.domain.com:GPS_Points" type="image" workspace="mo_ws-4" />
      </LAYER>
    </MAP>
    <OVERVIEWMAP>...</OVERVIEWMAP>
    <SCALEBAR ... />
  </CONFIG>
</ARCXML>

References to an ArcExplorer-enabled MapObjects IMS map in MOIMSWORKSPACE are made in the service attribute. In the above example, the name of the map is "GPS_Points". The url attribute gives the location of esrimap.dll located on the machine with MapObjects IMS. ArcExplorer-enabled maps do not work with the ArcIMS Servlet Connector. However, the ArcIMS Servlet Connector can be used with regular MapObjects IMS sites.

The DATASET name references the machine and domain and the MapObjects IMS map name separated by a colon (:). In the above example, the DATASET name is "mymachine.domain.com:GPS_Points".

SHAPEWORKSPACE, IMAGEWORKSPACE, and SDEWORKSPACE

SHAPEWORKSPACE, IMAGEWORKSPACE, and SDEWORKSPACE are used when local data is referenced in the viewer configuration file. These WORKSPACES elements reference data exactly the same way as in a map configuration file.

OVERVIEWMAP and SCALEBAR

OVERVIEWMAP and SCALEBAR are client configuration elements and add an overview map or scale bar, respectively. Both elements are saved when using ArcExplorer 3 or an ArcIMS Java Standard Viewer. Only SCALEBAR is saved in an ArcIMS Java Custom Viewer even if an overview map is present. Also, the ArcIMS Java Custom Viewer ignores these elements when a viewer configuration file is read into the viewer.

If an overview map or scale bar are present when a viewer configuration file is saved, the OVERVIEW and SCALEBAR elements are included.

Using OVERVIEWMAP and SCALEBAR:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>...</ENVIRONMENT>
    <MAP>...</MAP>
    <OVERVIEWMAP backgroundcolor="255,255,255" framefillcolor="255,0,0,80" frameoutlinecolor="255,0,0" zoomfactor="4.0"<>
      <LAYERDEF name="Oceans" />
    <LAYERDEF name="Countries" />
  </OVERVIEWMAP>
    <SCALEBAR backcolor="212,208,200" fontcolor="0,0,0" mapunits="decimal_degrees" scaleunits="feet" screenunits="inches" />
  </CONFIG>
</ARCXML>

If these two elements are included in a map configuration file, they are ignored.

Default.axl: A Special Viewer Configuration File

Default.axl is a special viewer configuration file that is output by ArcIMS Designer when an ArcIMS Java Viewer is created. The diagram below shows the process to create default.axl:

In Step 1, one or more MapServices are selected during the ArcIMS Designer process.
In Step 2, when a web site is generated, one of the output files in the directory is default.axl.
In Step 3, when an ArcIMS Java Viewer is opened, default.axl is loaded in the viewer. The file contains information on which MapServices should be loaded in the viewer.

Framework of default.axl

Default.axl uses a subset of elements normally found in a viewer configuration file. Its primary purpose is to load MapService layers specified during the ArcIMS Designer process.

Example default.axl file:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <MAP>
      <PROPERTIES>
        <ENVELOPE minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
        <IMAGESERVERWORKSPACE name="mapper_ws-6" url="http://mycomputer.domain.com/servlet/com.esri.esrimap.Esrimap" service="background" />
        <FEATURESERVERWORKSPACE name="ifs_ws-7" url="http://mycomputer.domain.com/servlet/com.esri.esrimap.Esrimap" service="World" />
      </WORKSPACES>
      <LAYER type="image" name="background" visible="true" id="0">
        <DATASET name="background" type="image" workspace="mapper_ws-6" />
      </LAYER>
      <LAYER type="featureclass" name="Countries" visible="true" id="1">
        <DATASET name="0" type="polygon" workspace="ifs_ws-7" />
      </LAYER>
      <LAYER type="featureclass" name="United States" visible="true" id="2">
        <DATASET name="1" type="polygon" workspace="ifs_ws-7" />
      </LAYER>
    </MAP>
    <SCALEBAR backcolor="212,208,200" fontcolor="0,0,0" mapunits="decimal_degrees" scaleunits="feet" screenunits="inches" />
  </CONFIG>
</ARCXML>

Only elements that are needed to load the MapServices are included. The principal similarities and differences between default.axl and a viewer configuration file are

CONFIG and MAP. These elements are always present in a configuration file.
ENVIRONMENT. The ENVIRONMENT elements are not included in default.axl. Since the information on locale is already associated with the MapServices, the ENVIRONMENT information does not need to be duplicated in default.axl.
WORKSPACE elements. Only FEATURESERVERWORKSPACE and IMAGESERVERWORKSPACE are added during the ArcIMS Designer process. AVIMSWORKSPACE and MOIMSWORKSPACE can be added manually if a map from ArcView IMS or MapObjects IMS is included in the web site.

PROPERTIES. This section is the same as for viewer configuration files. The one exception is the use of ENVELOPE. In the Java Custom Viewer, two ENVELOPE elements may be included. If only one ENVELOPE is included, only the initial extent for the map is included. The following figure shows the initial extent of a world map when the following ENVELOPE is used:

Using ENVELOPE Initial_Extent:

If two ENVELOPE elements are included, the first is the map�s initial extent, and the second is the maximum zoom limit of the map. These extents are set during the ArcIMS Designer process. The coordinates used in the extent limit represent the maximum limit of data that can be shown. In the next example, the initial extent and the extent limit are set to an envelope that bounds the United States, although a world data set was used. In the Java Custom Viewer, only the region inside the extent limit displays.

Using ENVELOPE Initial_Extent and Extent_Limit:

LAYER and DATASET. The rules for assigning attribute values are the same as for viewer configuration files. However, no rendering information is included with the layer.

SCALEBAR. SCALEBAR is always included in default.axl with Java Standard Viewer web sites but not with Java Custom Viewer web sites.

Including SCALEBAR:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <MAP>...</MAP>
    <SCALEBAR backcolor="212,208,200" fontcolor="0,0,0" mapunits="decimal_degrees" scaleunits="feet" screenunits="inches" />
  </CONFIG>
</ARCXML>

OVERVIEWMAP. OVERVIEWMAP is not included in default.axl.

Relationship between Feature MapServices and default.axl

When ArcIMS Designer creates default.axl and a Feature MapService is included, one LAYER is included in default.axl for every LAYER in the Feature MapService. Since no rendering is included in default.axl, the rendering defined in the MapService is what is used by the ArcIMS Java Viewers. Any changes to the rendering in the MapService are immediately reflected in the ArcIMS Java Viewers.

Caution is needed when adding or deleting layers in a MapService. If a layer is added to a MapService but not to default.axl, the ArcIMS Java Viewer will not display the new layer. If a layer is deleted from a MapService but not default.axl, an error message appears in the ArcIMS Java Viewer because a layer referenced in default.axl cannot be found in the MapService. In summary, if a layer is added or deleted in a MapService, it should be added or deleted in default.axl.

Comparing Different CONFIG Files

The table below summarizes the similarities and differences between map configuration files, viewer configuration files, and default.axl.

	Map Config	Viewer Config	Default.axl
Primary purpose	Used as input to MapServices	Saves current map and viewer configuration on the client	Used to load MapServices in an ArcIMS Java Viewer
Created by	ArcIMS Author or XML Editor	ArcExplorer 3 or ArcIMS Java Viewers	ArcIMS Designer
File is located	On server	On client	On server
Data sources	Local network only and must be accessible by ArcIMS Spatial Server	MapServices and local network on client	MapServices only
Valid workspaces	SHAPEWORKSPACE, IMAGEWORKSPACE, SDEWORKSPACE	IMAGESERVERWORKSPACE, FEATURESERVERWORKSPACE, AVIMSWORKSPACE, MOIMSWORKSPACE, SHAPEWORKSPACE, IMAGEWORKSPACE, SDEWORKSPACE	IMAGESERVERWORKSPACE, FEATURESERVERWORKSPACE, AVIMSWORKSPACE, MOIMSWORKSPACE