Using GET_SERVICE_INFO and SERVICEINFO

Using GET_SERVICE_INFO and SERVICEINFO

Introduction
GET_SERVICE_INFO Framework
SERVICEINFO Framework
GET_SERVICE_INFO Attributes

Introduction

GET_SERVICE_INFO is a request for accessing information about a MapService such as the environment, properties, and layer information. This information is returned in a SERVICEINFO response.

The following map configuration file, started as an Image MapService, is used for the GET_SERVICE_INFO examples in this document. The file consists of two layers from the ESRIDATA data set and an acetate layer. The following table summarizes the layer names, file name, file type and layer ID number.

Layer Name	Data Name	Data Type	Layer ID
Background	WORLD_IMG.gif	Image	0
Countries	CNTRY94	Polygon	1
northarrow	N/A	Acetate	northarrow

Map configuration file used with the GET_SERVICE_INFO requests that follow:

<?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="-180.0" miny="-90.0" maxx="180.0" maxy="90.0" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
        <IMAGEWORKSPACE directory="<path to data>" name="jai_ws-4" />
        <SHAPEWORKSPACE name="shp_ws-5" directory="<path to WORLD ESRIDATA>" />
      </WORKSPACES>
      <LAYER type="image" name="Background" visible="true" id="0">
        <DATASET name="WORLD_IMG.gif" type="image" workspace="jai_ws-4" />
      </LAYER>
      <LAYER type="featureclass" name="Countries" visible="true" id="1">
        <DATASET name="CNTRY94" type="polygon" workspace="shp_ws-5" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltransparency="0.0" boundarywidth="2"/>
        </SIMPLERENDERER>
        <EXTENSION type="Extract">
          <EXTRACTPARAMS clip="true">
            <OUTPUTFILE file="world">
              <OUTPUTFIELD name="NAME" alias="Country" />
            </OUTPUTFILE>
          </EXTRACTPARAMS>
        </EXTENSION>
        <EXTENSION type="Geocode">
          <GCSTYLE name="SingleField">
            <GCFIELD id="KeyField" name="NAME" />
          </GCSTYLE>
        </EXTENSION>
        <EXTENSION type="StoredQuery">
          <STOREDQUERIES>
            <STOREDQUERY name="Country">
              <QUERY where="( NAME = [%var%] )" subfields="#SHAPE# AREA NAME ABBREVNAME FIPS_CODE WB_CNTRY" />
              <SQVAR position="0" name="[%var%]">
                <FIELD name="NAME" precision="0" type="12" size="40" />
              </SQVAR>
            </STOREDQUERY>
          </STOREDQUERIES>
        </EXTENSION>
      </LAYER>
      <LAYER type="acetate" name="northarrow" id="northarrow">
        <OBJECT units="pixel">
          <NORTHARROW type="6" size="40" coords="60 80" shadow="32,32,32" angle="0" antialiasing="True" overlap="False"/>
        </OBJECT>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The Background layer is an image of the world. The Countries layer contains country boundaries and includes three extensions: one for extract, one for geocode, and one for stored queries. The acetate layer consists of a north arrow. The map in the following figure is example output using this MapService.

GET_SERVICE_INFO Framework

A GET_SERVICE_INFO request requires only the GET_SERVICE_INFO element as shown in the example below.

GET_SERVICE_INFO request dpi:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO evelope="true" fields="true" renderer="true" extensions="true" />
  </REQUEST>
</ARCXML>

SERVICEINFO Framework

Depending on which attributes are used with GET_SERVICE_INFO, all or a subset of information about the MapService is returned in SERVICEINFO. By default, SERVICEINFO returns all information about a MapService. Based on the above request on the sample MapService, the following example shows the SERVICEINFO response.

SERVICEINFO response:

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICEINFO>
      <ENVIRONMENT>
        <LOCALE language="en" country="US" />
        <UIFONT name="Arial" color="0,0,0" size="12" style="regular" />
        <SEPARATORS cs=" " ts=";"/>
        <SCREEN dpi="96"/>
        <IMAGELIMIT pixelcount="1048576" />
      </ENVIRONMENT>
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <LAYERINFO type="image" name="Background" visible="true" id="0">
        <ENVELOPE minx="-180" miny="-89.9747543334961" maxx="179.9423828125" maxy="90" />
      </LAYERINFO>
      <LAYERINFO type="featureclass" visible="true" name="Countries" id="1">
        <FCLASS type="polygon">
          <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="83.5960388183594" />
          <FIELD name="AREA" type="8" size="12" precision="3" />
          <FIELD name="NAME" type="12" size="40" precision="0" />
          <FIELD name="ABBREVNAME" type="12" size="12" precision="0" />
          <FIELD name="FIPS_CODE" type="12" size="2" precision="0" />
          <FIELD name="WB_CNTRY" type="12" size="3" precision="0" />
          <FIELD name="#SHAPE#" type="-98" size="0" precision="0" />
          <FIELD name="#ID#" type="-99" size="16" precision="0" />
        </FCLASS>
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltransparency="0.0" boundarywidth="2" />
        </SIMPLERENDERER>
        <EXTENSION type="extract">
          <EXTRACTPARAMS clip="true">
            <OUTPUTFILE file="world">
              <OUTPUTFIELD name="NAME" alias="Country"/>
            </OUTPUTFILE>
          </EXTRACTPARAMS>
        </EXTENSION>
        <EXTENSION type="Geocode" >
          <GCSTYLE name="SingleField" />
        </EXTENSION>
        <EXTENSION type="StoredQuery">
          <STOREDQUERIES>
            <STOREDQUERY name="Country">
              <QUERY subfields="#SHAPE# AREA NAME ABBREVNAME FIPS_CODE WB_CNTRY" where="( NAME = [%var%] )" >
              </QUERY>
              <SQVAR name="[%var%]" position="0">
                <FIELD name="NAME" type="12" precision="0" size="40" />
              </SQVAR>
            </STOREDQUERY>
          </STOREDQUERIES>
        </EXTENSION>
      </LAYERINFO>
      <LAYERINFO type="acetate" name="northarrow" visible="true" id="northarrow"/>
    </SERVICEINFO>
  </RESPONSE>
</ARCXML>

SERVICEINFO is divided into three sections: ENVIRONMENT, PROPERTIES, and LAYERINFO.

ENVIRONMENT

ENVIRONMENT takes its values from the MapService or assigns default values. LOCALE and UIFONT are required, so the information in SERVICEINFO is always taken directly from the MapService. With SCREEN and SEPARATORS, the values are either those assigned in the MapService or default values assigned by the ArcIMS Spatial Server. For SCREEN, the default value for dpi is 96. For SEPARATORS, the default for cs (coordinate separator) and ts (tuple separator) are a space and semicolon, respectively.

IMAGELIMIT is always included and is set when a MapService is started. By default, an image is limited in size to 4 MB, which corresponds to 1,048,576 pixels. Changes can be made to the image size and pixel count using the ArcIMS Administrator. For more information, see Using ArcIMS. The attribute pixelcount in GET_SERVICE_INFO reports the pixel count from the ArcIMS Administrator, but it cannot be changed using GET_SERVICE_INFO.

CAPABILITIES is included only when forbidden elements are added to an access control list (ACL). The ACL file is used for user authentication to grant users access to specific MapServices. One way to limit access is to forbid one or more of the five requests: GET_EXTRACT, GET_FEATURES, GET_GEOCODE, GET_IMAGE, or GET_SERVICE_INFO. For more information on forbidden elements, see "ArcIMS Servlet Connector" under the System Administration chapter in the ArcIMS Help.

In the example below, forbidden in CAPABILITIES is set to GET_GEOCODE and GET_EXTRACT. This means no requests with GET_GEOCODE or GET_EXTRACT will be processed.

ENVIRONMENT and its child elements:

PROPERTIES

PROPERTIES in SERVICEINFO repeats back all information in the PROPERTIES section of a MapService. The overall ENVELOPE for the MapService is always included since it is required in a MapService. All other child elements are optional in a MapService and are included in the SERVICEINFO response only when included in the MapService. Optional child elements valid in both Feature and Image Mapservices include FEATURECOORDSYS and FILTERCOORDSYS. Optional child elements valid in Image Mapservices only include BACKGROUND, LEGEND, IMAGESIZE, and OUTPUT.

PROPERTIES and its child elements:

LAYERINFO

LAYERINFO describes the layer information in a MapService and includes the layer type, name of the layer, whether the layer is visible, the layer ID, and the minimum and maximum scales at which the layer can be displayed. All these parameters are defined in the MapService LAYER. None of these parameters can be overridden in a request.

There are three LAYERINFO types, each of which corresponds to the same LAYER type in a map configuration file.

Image. In addition to LAYERINFO, the child element ENVELOPE, is always included with an image layer.
Acetate. No child attributes are included in an acetate layer.
Featureclass. In addition to LAYERINFO, featureclass layers always include the child element FCLASS, which describes whether the featureclass is polygon, line, or point. Also, as discussed in the next section, depending on different attributes selected in GET_SERVICE_INFO, additional information about the featureclass layer can be included in the SERVICEINFO response.

The following example shows each of the layer types with the minimum required information.

LAYERINFO and minimum returned information:

GET_SERVICE_INFO Attributes

GET_SERVICE_INFO has five optional attributes, four of which determine what information about a featureclass layer is returned in SERVICEINFO.

envelope
fields
renderer
extensions

The fifth attribute is dpi, which is discussed later in this session.

If the above attributes are set to "false", the minimum amount of information about featureclass layers is returned.

GET_SERVICE_INFO request setting attributes false:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="false" fields="false" renderer="false" extensions="false"/>
  </REQUEST>
</ARCXML>

When all the attributes are set to false in GET_SERVICE_INFO, the SERVICEINFO response returns the minimum amount of information for LAYERINFO. The ENVIRONMENT and PROPERTIES elements return the same information regardless of whether the attributes are true or false.

SERVICEINFO response with ENVELOPE:

Envelope attribute

When envelope is set to true, the extent for each featureclass layer is included. This information is in addition to the extent of the MapService as a whole. The extent is always returned for image layers and no extent is included for acetate layers.

GET_SERVICE_INFO request using envelope:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="true" fields="false" renderer="false" extensions="false"/>
  </REQUEST>
</ARCXML>

In the SERVICINFO response, an ENVELOPE is included for all featureclass layers. This is in addition ot the ENVELOPE in the PROPERTIES section, and ENVELOPE for image layers. No ENVELOPE is included for acetate layers.

SERVICEINFO response with ENVELOPE:

Fields attribute

When fields is set to true in GET_SERVICE_INFO, fields in the shapefile or ArcSDE table are returned in FIELD in the SERVICEINFO response. If joined tables are used, they are included in the FIELD list. In the request below, fields is set to true. The response includes FIELD information for the Countries featureclass layer.

GET_SERVICE_INFO request with fields:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="false" fields="true" renderer="false" extensions="false"/>
  </REQUEST>
</ARCXML>

SERVICEINFO response with FIELD:

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICEINFO>
      <ENVIRONMENT>
        <LOCALE language="en" country="US" />
        <UIFONT name="Arial" color="0,0,0" size="12" style="regular" />
        <SEPARATORS cs=" " ts=";"/>
        <SCREEN dpi="96"/>
        <IMAGELIMIT pixelcount="1048576" />
      </ENVIRONMENT>
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <LAYERINFO type="image" name="Background" visible="true" id="0">
        <ENVELOPE minx="-180" miny="-89.9747543334961" maxx="179.9423828125" maxy="90" />
      </LAYERINFO>
      <LAYERINFO type="featureclass" visible="true" name="Countries" id="1">
        <FCLASS type="polygon">
          <FIELD name="AREA" type="8" size="12" precision="3" />
          <FIELD name="NAME" type="12" size="40" precision="0" />
          <FIELD name="ABBREVNAME" type="12" size="12" precision="0" />
          <FIELD name="FIPS_CODE" type="12" size="2" precision="0" />
          <FIELD name="WB_CNTRY" type="12" size="3" precision="0" />
          <FIELD name="#SHAPE#" type="-98" size="0" precision="0" />
          <FIELD name="#ID#" type="-99" size="16" precision="0" />
        </FCLASS>
      <LAYERINFO type="acetate" name="northarrow" visible="true" id="northarrow"/>
    </SERVICEINFO>
  </RESPONSE>
</ARCXML>

Renderer attribute

When renderer is set to true in GET_SERVICE_INFO, all rendering information for a featureclass layer is included in the SERVICEINFO response. In the next example, renderer is set to true. The response includes renderer information for the Countries featureclass layer. The returned information duplicates what is in the map configuration file.

GET_SERVICE_INFO request with renderer:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="false" fields="false" renderer="true" extensions="false"/>
  </REQUEST>
</ARCXML>

SERVICEINFO response with rendering:

Extensions attribute

When extensions is set to true in GET_SERVICE_INFO, all extension information for a featureclass layer is included in the SERVICEINFO response. The three extension types are:

StoredQuery. Defines data for a stored query using STOREDQUERY.
Extract. Allows data to be extracted in shapefile format generated by the Extract Server. The extension is set up using EXTRACTPARAMS.
Geocode. Identifies the geocoding style for a layer using GCSTYLE.

In the request below, extensions is set to true. The response includes three extensions for the Countries featureclass layer. The returned information duplicates what is in the map configuration file for "StoredQuery" and "Extract". The response for the "Geocode" extension does not include everything in the map configuration file, only GCSTYLE.

GET_SERVICE_INFO request with extensions:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="false" fields="false" renderer="false" extensions="true"/>
  </REQUEST>
</ARCXML>

SERVICEINFO response with extensions:

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICEINFO>
      <ENVIRONMENT>
        <LOCALE language="en" country="US" />
        <UIFONT name="Arial" color="0,0,0" size="12" style="regular" />
        <SEPARATORS cs=" " ts=";"/>
        <SCREEN dpi="96"/>
        <IMAGELIMIT pixelcount="1048576" />
      </ENVIRONMENT>
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <LAYERINFO type="image" name="Background" visible="true" id="0">
        <ENVELOPE minx="-180" miny="-89.9747543334961" maxx="179.9423828125" maxy="90" />
      </LAYERINFO>
      <LAYERINFO type="featureclass" visible="true" name="Countries" id="1">
        <FCLASS type="polygon">
        <EXTENSION type="extract">
          <EXTRACTPARAMS clip="true">
            <OUTPUTFILE file="world">
              <OUTPUTFIELD name="NAME" alias="Country"/>
            </OUTPUTFILE>
          </EXTRACTPARAMS>
        </EXTENSION>
        <EXTENSION type="Geocode" >
          <GCSTYLE name="SingleField" />
        </EXTENSION>
        <EXTENSION type="StoredQuery">
          <STOREDQUERIES>
            <STOREDQUERY name="Country">
              <QUERY subfields="#SHAPE# AREA NAME ABBREVNAME FIPS_CODE WB_CNTRY" where="( NAME = [%var%] )" >
              </QUERY>
              <SQVAR name="[%var%]" position="0">
                <FIELD name="NAME" type="12" precision="0" size="40" />
              </SQVAR>
            </STOREDQUERY>
          </STOREDQUERIES>
        </EXTENSION>
      </LAYERINFO>
      <LAYERINFO type="acetate" name="northarrow" visible="true" id="northarrow"/>
    </SERVICEINFO>
  </RESPONSE>
</ARCXML>

Extensions attribute when GET_SERVICE_INFO is routed to the Geocode Server

In order to retrieve all information about a Geocode extension, the GET_SERVICE_INFO request must be routed to the Geocode Server. This routing information is contained in the URL sent to the ArcIMS site such as in the following example (all one line):

http://myComputer.domain.com/servlet/com.esri.esrimap.Esrimap?ClientVersion=3.1
      &ServiceName=myservice
      &CustomService=Geocode
      &Form=True&Encode=True

The GET_SERVICE_INFO request is the same as in the previous example. However, by routing the request to the Geocode Server, complete geocode extension information is returned. This information is similar to the information in the map configuration file. However, where GCFIELD is used in the map configuration file, GCINPUT is used in the SERVICEINFO response.

GET_SERVICE_INFO request with extensions routed to Geocode Server:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO envelope="false" fields="false" renderer="false" extensions="true"/>
  </REQUEST>
</ARCXML>

SERVICEINFO response with Geocode extension information:

Dpi attribute

One final attribute in GET_SERVICE_INFO is dpi (dots per inch). If a value is assigned to dpi in GET_SERVICE_INFO, this new value is returned in SCREEN in the SERVICEINFO response. Based on the new dpi, the minimum and maximum scales returned for scale dependent elements such as SCALEDEPENDENTRENDERER, LAYERINFO, LAYER, and OBJECT are recalculated. The recalculation is useful in situations where the map configuration file was created on a machine with one dpi, but the client uses a different dpi.

If dpi is not included in GET_SERVICE_INFO, the dpi set in SCREEN in the map configuration file is used. If SCREEN is not included in the map configuration file, a default value of "96" is assumed.

The ArcIMS Java Viewers and ArcExplorer 3 send the dpi of the client in a GET_SERVICE_INFO request. The ArcIMS HTML Viewer does not send the dpi of the client. It uses the SCREEN dpi in the map configuration file or a default value of "96". Therefore, when using the ArcIMS HTML Viewer, the dpi of the client may not have the same dpi as the map configuration file. This means that scale dependencies will behave slightly different in the HTML Viewer.

The minimum and maximum scale values in LAYERINFO are listed as number of map units per pixel. In requests and the map configuration file, scales can be set using a relative scale ratio such as 1:24000. In this example, 1 meter equals 24000 meters or 1 inch equals 24000 inches.

Map units per pixel refers to the number of meters, feet, or decimal degrees represented by one pixel in a map. To convert from a relative scale to map units per pixel, the size of a pixel must first be calculated. The formula for finding the number of meters in a pixel is 0.0254 / dpi where:

The value 0.0254 is the number of meters in an inch.
Dpi is the dpi set in the MapService or request. If no dpi is set in the MapService or request, the dpi is assumed to be 96.

As an example of calculating pixel size, if the dpi is 96, the pixel size is 0.0254 / 96 or 0.000265 m.

Once the pixel size is known, the relative scale can be converted to map units per pixel:

If the scale is in meters. To calculate the number of meters per pixel, take the relative scale and multiply by the pixel size (0.000265). For example, if the relative scale is 1:24000, then the number of meters per pixel is 24000 * 0.000265, or 6.36 meters.
If the scale is in feet. Do the calculation for meters (#1). Multiply the result by 3.28 (the number of feet in a meter). For example, if the number of meters per pixel is 6.36, the number of feet per pixel is 6.36 * 3.28, or 20.86 feet.
If the scale is in decimal degrees. For these calculations, the earth is assumed to be an exact circle with a circumference of 40030.174 km. One degree is 111.195 km (40030.174/360 degrees) or 111195 meters. To calculate the number of degrees, first do the calculation for meters (#1). Next, divide the result by 111195. For example, if the number of meters per pixel is 6.36, the number of degrees per pixel is 6.36 / 111195, or 0.0000571968.

If the maxscale for a LAYER is set to 1:12500000 in the map configuration file, and the dpi in GET_SERVICE_INFO is "96", then the maxscale for LAYERINFO is "3307.29828126323", or approximately 3307 meters per pixel.

If the dpi in GET_SERVICE_INFO is "120", then the maxscale for LAYERINFO is "2645.83862501058", or approximately 2645 meters per pixel.

The next examples show a GET_SERVICE_INFO request that includes dpi and the response.

GET_SERVICE_INFO request with dpi:

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO dpi="192" envelope="false" fields="false" renderer="false" extensions="false"/>
  </REQUEST>
</ARCXML>

SERVICEINFO response: