Using GET_EXTRACT and EXTRACT

Introduction
Creating a Map Configuration File with an Extract Extension
- Using the extract EXTENSION
- Using SPATIALQUERY in a map configuration file
Limiting Zip File Size
Routing to the Extract Server
Using the GET_EXTRACT Request
The EXTRACT Response
Customizing the GET_EXTRACT Request
Transforming Geometry with the Extract Server

Introduction

The purpose of GET_EXTRACT and EXTRACT is to extract specified layers of an Image Service into a set of shapefiles, yielding one shapefile for each layer. Data can be extracted from shapefiles and ArcSDE vector layers. Raster and acetate layers cannot be extract. GET_EXTRACT is valid only with Image Services.

The request syntax for GET_EXTRACT is very much like GET_IMAGE. Many of the combinations of elements supported by GET_IMAGE are also supported by GET_EXTRACT. For a more detailed review of GET_IMAGE, see Using GET_IMAGE and IMAGE for Image Services.

A GET_EXTRACT request identifies which layers to extract, the extract envelope, and any query constraints to be included in the request. GET_EXTRACT does not support BUFFER or LEGEND. Once the request is processed, the data is compressed into a zip file, and the response contains the location of the zip file.

The typical scenario for using the Extract Server involves setting up an Image Service that contains an extract extension. GET_IMAGE requests are sent to the Image Service to manipulate the map and query data. When it is time to extract data, a GET_EXTRACT request is sent to the same Image Service but the request is routed to the Extract Server. The details of this scenario are covered below.

Creating a Map Configuration File with an Extract Extension

In order to trigger the Extract Server, an Extract extension must be included with at least one layer in the map configuration file. The extension does not need to be included with every layer. If one layer in the map configuration file includes the extensions, all vector layers can be extracted. The following map configuration file contains six layers: World, Countries, States, Provinces, World Cities, and US Cities. The WORLD30, CNTRY94, and US Cities layers include an extract extension. Details about the extension are given below.

An 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" />
    </ENVIRONMENT>
    <MAP dynamic="true">
      <PROPERTIES>
        <ENVELOPE minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
        <FILTERCOORDSYS id="4326" />
        <FEATURECOORDSYS id="4326"/>
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-0" directory="C:\ESRIDATA\WORLD" />
        <SHAPEWORKSPACE name="shp_ws-2" directory="C:\ESRIDATA\USA" />
        <SHAPEWORKSPACE name="shp_ws-3" directory="C:\ESRIDATA\CANADA" />
      </WORKSPACES>
      <LAYER type="featureclass" name="WORLD30" visible="true" id="Ocean">
        <DATASET name="WORLD30" type="polygon" workspace="shp_ws-0" />
        <EXTENSION type="extract" >
          <EXTRACTPARAMS clip="true" />
        </EXTENSION>
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,255" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="CNTRY94" visible="true" id="Countries">
        <DATASET name="CNTRY94" type="polygon" workspace="shp_ws-0" />
        <EXTENSION type="extract" >
          <EXTRACTPARAMS clip="true" />
        </EXTENSION>
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,255,153"/>
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="STATES" visible="true" id="States">
        <DATASET name="STATES" type="polygon" workspace="shp_ws-2" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,0,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="province" visible="true" id="Provinces">
        <DATASET name="province" type="polygon" workspace="shp_ws-3" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="World Cities" visible="true" id="Cities">
        <DATASET name="CITIES" type="point" workspace="shp_ws-0" />
      <SPATIALQUERY where="POPULATION > 300000" subfields="NAME POPULATION #ID# #SHAPE#"  />
        <SIMPLERENDERER>
          <SIMPLEMARKERSYMBOL color="102,0,102" width="8.0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="US Cities" visible="true" id="35">
        <DATASET name="CITIES" type="point" workspace="shp_ws-2" />
        <SPATIALQUERY where="POP1990 > 100000" subfields="CITY_NAME STATE_NAME POP1990 MALES FEMALES #ID# #SHAPE#"  />
        <SIMPLERENDERER>
          <SIMPLEMARKERSYMBOL color="0,255,0" type="star" width="8.0" />
        </SIMPLERENDERER>
        <EXTENSION type="extract" >
        <EXTRACTPARAMS clip="true" >
          <OUTPUTFILE file="us_cities" >
            <OUTPUTFIELD name="CITY_NAME" alias="City" />
            <OUTPUTFIELD name="STATE_NAME" alias="State" />
            <OUTPUTFIELD name="POP1990" alias="Population" />
            <OUTPUTFIELD name="MALES" alias="Male_pop" />
            <OUTPUTFIELD name="FEMALES" alias="Female_pop" />
          </OUTPUTFILE>
        </EXTRACTPARAMS>
      </EXTENSION>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

The examples in the remainder of this document use this map configuration file started as an Image Service.

Using the extract EXTENSION

In the map configuration file, the US Cities layer contains an extract EXTENSION. This extension notifies the ArcIMS Spatial Server that the Extract Server will be used. It also provides a place to customize the shapefile name and specify which attributes should be included.

The different extract elements are:

EXTRACTPARAMS (required) is the main element and must always be included when EXTENSION is used. An option is available to clip to the layers at the current extent boundary in the viewer using the clip attribute. When clip is set to true in the map configuration file, features are clipped at the extent of the viewer. However, none of a layer's database values are prorated for any clipped features. If clipping is not used, features partially within the envelope are extracted in their entirety.

The default for clip is "false". If you do not want a layer to be clipped, the EXTENSION and EXTRACTPARAMS elements are not required for the layer. In the map configuration file, STATES, Province, and World Cities do not include these elements. The layers will be extracted, and features will not be clipped.

In order to clip the features in a layer, the EXTENSION and EXTRACTPARAMS elements must be included, and clip must be set to "true". In the map configuration file, the WORLD30, CNTRY94, and World Cities layers include the extension elements, and clip is set to "true".
OUTPUTFILE (optional) is used to name the extracted shapefile.
Naming extracted shapefiles
Two different methods can be used to name extracted shapefiles. The naming scheme is set up in the map configuration file.
1. The default method for naming extracted shapefiles is to use the name of each layer's id attribute value. ArcIMS Author always assigns an ID using numbers. If you want to name your shapefile something more meaningful, you can assign a character string to the id. For example, for the WORLD30 layer, the extracted shapefile is named "Ocean".
2. The second method is to name a shapefile using OUTPUTFILE in a layer EXTENSION. For example, the US Cities layer uses the name "us_cities" in OUTPUTFILE. If OUTPUTFILE were not used, the file would be assigned the name "35", the same as the layer ID.
OUTPUTFIELD (optional) can be used to set an alias name for a field in the database. Shapefiles use DBF files to store attribute data, and a field in the DBF is limited to 10 characters. Since other databases often allow more than 10 characters, it's possible to end up with two fields in the DBF file with the same name. ArcIMS does not allow shapefiles with duplicate field names to be used.

OUTPUTFIELD allows the addition of an alias name to replace the actual field name. For example, when the data is extracted for the US Cities layer, the DBF file contains "City" instead of "CITY_NAME" for the first field, and so on.

To limit the extracted fields to those listed in OUTPUTFIELD, the attribute subfields must be included in a SPATIALQUERY (or QUERY). In the map configuration file, subfields is used in the following line:

<SPATIALQUERY where="POP1990 > 100000" subfields="CITY_NAME STATE_NAME POP1990 MALES FEMALES" />

As noted above, EXTRACTPARAMS is required, while OUTPUTFILE and OUTPUTFIELD are optional. The minimum information needed to use the extension is the following:

Using SPATIALQUERY in a map configuration file

SPATIALQUERY can be used to set both attribute and spatial constraints on a layer in a map configuration file. A query filter set in the map configuration file cannot be overridden in a request. Requests are constrained to within the features available in the filtered subset. In the above map configuration file, the World Cities layer has a constraint to show only cities with a population greater than 300,000, and the US Cities layer has a constraint to show cities with a population greater than 100,000. SPATIALFILTER can also be used with SPATIALQUERY to limit data extraction to that within the specified filter.

You can limit the subfields available for extraction using the SPATIALQUERY subfields attribute. For example, in the US Cities layer, subfields is used in the following line:

<SPATIALQUERY where="POP1990 > 100000" subfields="CITY_NAME STATE_NAME POP1990 MALES FEMALES" />

In this example, only the CITY_NAME, STATE_NAME, POP1990, MALES, and FEMALES fields are available for extraction. Remember that you can provide an alias name for these fields using OUTPUTFIELD.

You can also limit the number of features on a per layer basis using SPATIALQUERY featurelimit. This limit is useful if you have layers with thousands or millions of records. With this limitation in place, users can no longer request every feature in a layer in one request.

Limiting Zip File Size

When data is extracted and placed in zip files, these files have the potential to be very large depending on the number of layers and the number of features in each layer. By default, there is no size limit on zip files. You can set a limit in the Extract Server configuration file (aimses.cfg) located in <ArcIMS Installation Directory>\ArcIMS\server\etc on Windows or $AIMSHOME/server/etc on Unix and Linux. For more information, see ArcIMS Help.

Routing to the Extract Server

The Extract Server is a private server. GET_EXTRACT requests are made to an Image Service and must be routed to the Extract Server. This routing information is contained in the URL that is sent to the ArcIMS site such as in the following example (all one line):

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

Using the GET_EXTRACT Request

Once the map configuration file has been started as an Image Service, GET_EXTRACT requests can be made. The following example is a typical request to the Extract Server.

A typical GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
      </PROPERTIES>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

In general, although ENVELOPE is not required, it should always be included in the request to indicate the extent of the data to extract. If ENVELOPE is not included, all data is extracted. In the above request, the GET_EXTRACT request takes features from the six layers within the defined envelope and extracts them with their attributes to six shapefiles. The shapefiles are named Ocean, Countries, States, Provinces, Cities, and us_cities. Although rendering is included in the map configuration file, no rendering information is retained when the shapefiles are generated.

The EXTRACT Response

The EXTRACT response includes the envelope and the location of the zip file.

An EXTRACT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <EXTRACT>
      <ENVELOPE minx="-130.000000" miny="30.000000" maxx="-90.000000" maxy="60.000000" />
      <OUTPUT file="c:\arcims\output\myservice_mymachine33934311.zip" url="http://mymachine.domain.com/output/myservice_mymachine33934311.zip" />
    </EXTRACT>
  </RESPONSE>
</ARCXML>

In the above example, the shapefiles are zipped into a file named myservice_mymachine33934311.zip. This file is located on the server in the directory c:\arcims\output. The file can be accessed from a Web site using the URL http://mymachine.domain.com/output/myservice_mymachine33934311.zip.

Customizing the GET_EXTRACT Request

Constraints can be added to a GET_EXTRACT request in order to override information in the service. The following examples show different methods for extracting subsets of data using:

IMAGESIZE

In a GET_EXTRACT request, IMAGESIZE is used to calculate which layers should be extracted based on any scale dependencies. If a layer is out of range based on the scale, it is not extracted. If IMAGESIZE is not used in a request, the default image size used for calculating the extent is 400 x 300 pixels. When IMAGESIZE is used in GET_IMAGE requests, the same IMAGESIZE should be used in any GET_EXTRACT requests. If you find that a different set of layers is extracted compared to the list of layers in a map image, double-check that IMAGESIZE is the same for both GET_IMAGE and GET_EXTRACT.

In GET_EXTRACT, the only valid IMAGESIZE attributes are height and width. In the following example, height and width are set to 600 and 800, respectively.

Using IMAGESIZE in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
        <IMAGESIZE height="600" width="800" />
      </PROPERTIES>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

LAYERLIST and LAYERDEF

Layers in GET_EXTRACT can be switched on and off using the LAYERDEF element. Layers that are set to visible="false" are not extracted. In the following example, data for the States and Provinces layers is not extracted since the attribute visible has been set to "false".

Using LAYERDEF in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
<REQUEST>
  <GET_EXTRACT>
    <PROPERTIES>
      <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
      <LAYERLIST>
        <LAYERDEF id="Ocean" visible="true" />
        <LAYERDEF id="Countries" visible="true" />
        <LAYERDEF id="States" visible="false" />
        <LAYERDEF id="Provinces" visible="false" />
        <LAYERDEF id="Cities" visible="true" />
        <LAYERDEF id="35" visible="true" />
      </LAYERLIST>
    </PROPERTIES>
  </GET_EXTRACT>
</REQUEST>
</ARCXML>

The attribute nodefault can be used with LAYERLIST in a GET_EXTRACT request. When nodefault is set to "true", only the layers listed in the LAYERLIST are extracted. Remember that any acetate and raster layers in the LAYERLIST are ignored. The following example will produce the same results as the previous example. The changes are that nodefault is set to true in LAYERLIST, and the LAYERDEF information for States and Provinces has been removed.

Using LAYERLIST nodefault in a GET_EXTRACT request

SPATIALQUERY

SPATIALQUERY is used to set a spatial constraint on a layer. In the following example, a SPATIALQUERY for the Cities layer sets an envelope to a smaller extent than the ENVELOPE in PROPERTIES. The response includes only cities with a population greater than 300,000 within the newly defined envelope. Queries in a request cannot override a constraint already set in a service. The service already limits cities to those with a population greater than 300,000.

Using SPATIALQUERY with an envelope in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
<REQUEST>
  <GET_EXTRACT>
    <PROPERTIES>
      <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
      <LAYERLIST>
        <LAYERDEF id="Ocean" visible="true" />
        <LAYERDEF id="Countries" visible="true" />
        <LAYERDEF id="States" visible="false" />
        <LAYERDEF id="Provinces" visible="false" />
        <LAYERDEF id="Cities" visible="true" >
          <SPATIALQUERY>
            <SPATIALFILTER relation="area_intersection">
              <ENVELOPE minx="-120" miny="40" maxx="-100" maxy="60" />
            </SPATIALFILTER>
          </SPATIALQUERY>
        </LAYERDEF>
        <LAYERDEF id="35" visible="true" />
      </LAYERLIST>
    </PROPERTIES>
  </GET_EXTRACT>
</REQUEST>
</ARCXML>

In addition to spatial constraints, SPATIALQUERY can also be used:

To set additional constraints on a layer based on attribute data in a specified field. In the next example, SPATIALQUERY in the Countries layer extracts only countries beginning with the letter "C".
To limit which fields are extracted using subfields. In the States layer, only the fields STATE_NAME and POP1990 are extracted.
To limit the number of features using featurelimit.

Using SPATIALQUERY on attribute data in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
<REQUEST>
  <GET_EXTRACT>
    <PROPERTIES>
      <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
      <LAYERLIST>
        <LAYERDEF id="Ocean" visible="true" />
        <LAYERDEF id="Countries" visible="true" >
          <SPATIALQUERY where="NAME LIKE 'C%'" />
        </LAYERDEF>
        <LAYERDEF id="States" visible="true" >
          <SPATIALQUERY subfields="STATE_NAME POP1990" />
        </LAYERDEF>
        <LAYERDEF id="Provinces" visible="false" />
        <LAYERDEF id="Cities" visible="true" />
        <LAYERDEF id="35" visible="true" />
      </LAYERLIST>
    </PROPERTIES>
  </GET_EXTRACT>
</REQUEST>
</ARCXML>

Dynamic layers using LAYER

Dynamic layers not in the map configuration file can be included in the list of layers to extract using LAYER. Acetate and dynamic raster layers cannot be extracted.

Before dynamic layers can be added in a request, MAP must be set to dynamic in the map configuration file.

To add a new layer, a WORKSPACES section must be included in the map configuration file or the request. It is recommended to include WORKSPACES in the map configuration file since references to path names on the host computer are included. By keeping all WORKSPACES in the map configuration file, the directory locations remain hidden from users.

In the next example, Rivers is located in the shp_ws-0 workspace, the same workspace as Ocean, Countries, and Cities. The example also includes the dynamic layer made up of a selected set from an existing layer in the service. Both of these dynamic layers are extracted along with the Ocean, Countries, and World Cities.

Including a dynamic LAYER for extraction

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-147" miny="-46" maxx="-43" maxy="70" />
        <LAYERLIST>
          <LAYERDEF id="Ocean" visible="true" />
          <LAYERDEF id="Countries" visible="true" />
          <LAYERDEF id="States" visible="false" />
          <LAYERDEF id="Provinces" visible="false" />
          <LAYERDEF id="Cities" visible="true" />
          <LAYERDEF id="35" visible="false" />
        </LAYERLIST>
      </PROPERTIES>
      <LAYER type="featureclass" name="Rivers" visible="true" id="Rivers">
        <DATASET name="RIVERS" type="line" workspace="shp_ws-0" />
      </LAYER>
      <LAYER type="featureclass" name="Selected Countries" visible="true" id="Selected">
        <DATASET fromlayer="countries" />
        <SPATIALQUERY where="NAME='Brazil'" />
      </LAYER>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

Dynamic layers and LAYERLIST

The attribute nodefault can be used with LAYERLIST to extract only specified layers in the service and specified dynamic layers. In the next example, only Ocean, Countries, World Cities, and Rivers are extracted. If a layer is not in the LAYERLIST, it is not extracted.

Specifying layers for extraction

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-147" miny="-46" maxx="-43" maxy="70" />
        <LAYERLIST nodefault="true">
          <LAYERDEF id="Ocean" visible="true" />
          <LAYERDEF id="Countries" visible="true" />
          <LAYERDEF id="Cities" visible="true" />
          <LAYERDEF id="Rivers" visible="true" />
        </LAYERLIST>
      </PROPERTIES>
      <LAYER type="featureclass" name="Rivers" visible="true" id="Rivers">
        <DATASET name="RIVERS" type="line" workspace="shp_ws-0" />
      </LAYER>
      <LAYER type="featureclass" name="Selected Countries" visible="true" id="Selected">
        <DATASET fromlayer="countries" />
        <SPATIALQUERY where="NAME='Brazil'" />
      </LAYER>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

OUTPUT

OUTPUT, when used in a GET_EXTRACT request, defines the location and filename of the zip file. By default, the output directory and URL location are determined at the time the Image Service is started. When a request is made, the ArcIMS Spatial Server assigns a filename. The name includes the service name, the computer name the image was generated on, and a randomly generated number. If the service is named "world" and the computer is "MYCOMPUTER", then an example zip file is "world_MYCOMPUTER1248849.zip". The ArcIMS Tasker Windows service or UNIX daemon automatically deletes the zip files on a user-specified interval.

OUTPUT can be used in both a map configuration file and in a request. When used in a map configuration file, the OUTPUT information overrides the output information stored when the service is started. When used in a request, OUTPUT overrides information in both the map configuration file and when the service 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 ArcIMS Help.

OUTPUT works with paired attributes. If one of the attributes is used, its pair is also required. The attribute pairs are listed in the table below.

Attribute	Paired Attribute	Filename Assignment
path	baseurl	ArcIMS assigns random filename.
name	url	User assigns a filename.

If path and baseurl are used, output files can be redirected to a new directory but ArcIMS assigns the filename. In the example below, the new output directory is c:\arcims\newdirectory, and the new URL is http://mymachine.domain.com/newdirectory.

Using OUTPUT path and baseurl in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
        <OUTPUT path="c:\arcims\newdirectory" baseurl="http://mycomputer.domain.com/newdirectory" />
      </PROPERTIES>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

Based on the above request, a zip file is generated and placed in c:\arcims\newdirectory. The ArcIMS Spatial Server generated the filename, which is myservice_mymachine2286774.zip.

EXTRACT response when OUTPUT path and baseurl are used

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <EXTRACT>
      <ENVELOPE minx="-130.000000" miny="30.000000" maxx="-90.000000" maxy="60.000000" />
      <OUTPUT file="c:\arcims\newdirectory\myservice_mymachine2286774.zip" url="http://mymachine.domain.com/newdirectory/myservice_mymachine2286774.zip" />
    </EXTRACT>
  </RESPONSE>
</ARCXML>

If the attribute pair name and url is used, an output filename must be included along with the path. In the next example, the file is called "myzipfile.zip".

Using OUTPUT name and url in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
        <OUTPUT name="c:\arcims\newdirecotory\myzipfile.zip" url="http://mycomputer.domain.com/newdirectory/myzipfile.zip" />
      </PROPERTIES>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

In this response, a zip file named myzipfile.zip is generated and placed in c:\arcims\newdirectory. The URL is http://mymachine.domain.com/newdirectory/myzipfile.zip.

EXTRACT response when OUTPUT name and url are used

Figure 3: An EXTRACT Response. <?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <EXTRACT>
      <ENVELOPE minx="-130.000000" miny="30.000000" maxx="-90.000000" maxy="60.000000" />
      <OUTPUT file="c:\arcims\newdirectory\myzipfile.zip" url="http://mymachine.domain.com/newdirectory/myzipfile.zip" />
    </EXTRACT>
  </RESPONSE>
</ARCXML>

Restricting OUTPUT

When using an ArcIMS HTML Viewer, ArcIMS Java Viewer, ArcExplorer-Java Edition, or any other client using the ArcIMS Servlet Connector, the OUTPUT element is restricted by default.

In a GET_EXTRACT request, OUTPUT is ignored. All zip files are written to the Output directory assigned when the service was started or the Output directory listed in the map configuration file.
In an EXTRACT response, the attribute file is not returned.

These restrictions can be lifted by setting the properties spatialServer.AllowRequestOutput and spatialServer.AllowResponsePath to "true" in esrimap_prop. This property file is found in the same directory as the ArcIMS Servlet Connector. For more information on the location of Esrimap_prop and its properties, see ArcIMS Help.

These restrictions apply only when the ArcIMS Servlet Connector is used. These restrictions apply only when the ArcIMS Servlet Connector is used. They do not apply to the ActiveX, ColdFusion, or Java Connectors, or to the .NET Link. The OUTPUT filename extension is restricted to *.zip regardless of whether OUTPUT is restricted or not.

Transforming Geometry with the Extract Server

The coordinate system of extracted shapefiles can be changed on-the-fly using the following elements:

For a complete discussion on the different elements, refer to Using Projection Elements.

COORDSYS is used when adding dynamic LAYERS and no *.prj file is associated with a shapefile or coverage or no spatial references table is available in ArcSDE. FILTERCOORDSYS is used to specify the coordinate system of the requesting client. All the examples so far have been in geographic coordinates (decimal degrees) with an id="4326". FEATURECOORDSYS is used to specify the coordinate system to which the service should be transformed.

In the next example, FILTERCOORDSYS is in geographic coordinates with an id="4326". Note that the envelope coordinates used for the extraction must match the coordinate system of FILTERCOORDSYS and are also in geographic coordinates. The extracted shapefiles are requested in Robinson, so FEATURECOORDSYS is set to id="54030".

Using FILTERCOORDSYS and FEATURECOORDSYS in a GET_EXTRACT request

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_EXTRACT>
      <PROPERTIES>
        <ENVELOPE minx="-130" miny="30" maxx="-90" maxy="60" />
        <FILTERCOORDSYS id="4326" />
        <FEATURECOORDSYS id="54030" />
      </PROPERTIES>
    </GET_EXTRACT>
  </REQUEST>
</ARCXML>

In the EXTRACT response, the location of the zip file is returned along with the ENVELOPE in Robinson coordinates ("54030").

EXTRACT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <EXTRACT>
      <ENVELOPE minx="-11777530.8282994" miny="3205046.64322241" maxx="-6782838.54770184" maxy="6329105.54868597" />
      <OUTPUT url="http://mymachine.domain.com/output/myservice_mymachine33934311.zip" />
    </EXTRACT>
  </RESPONSE>
</ARCXML>