Using GET_EXTRACT and EXTRACT

Using GET_EXTRACT and EXTRACT

Introduction
Creating a Map Configuration File with an Extract Extension
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. To use the extract elements, you should understand map configuration file syntax, the relationship between map configuration files and ArcIMS services, how to send a request to the ArcIMS Spatial Server, and how to handle a response.

GET_EXTRACT requests are usually used with the Image Server. Although data can be extracted from a Feature Service, GET_EXTRACT must be made the same way it is for an Image Service. In the Java Viewers, the request must be made independently of the applets and the Java Viewer API. A request to the Extract Server cannot be made from ArcExplorer 4. GET_EXTRACT requests are not valid with the Feature or ArcMap Servers.

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.

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 HTML Viewer with 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 following map configuration file contains six layers: World, Countries, States, Provinces, World Cities, and US Cities. Each layer includes rendering information. In addition, the WORLD30, CNTRY94, and US Cities layers include an extract extension. Details about the extension are given below.

Figure 1: 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" />
      </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"  />
        <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"  />
        <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.

<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>

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, but 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. File names must use all English characters. In the above example, the shapefile is named us_cities.
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. In this 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. In order to use the Extract Server, at least one layer (any layer) must include the extract extension. The minimum information needed is the following:

Naming extracted shapefiles

Two different methods can be used to name extracted shapefiles. The naming scheme is set up in the map configuration file.

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".
The second method is to name a shapefile using OUTPUTFILE in a layer EXTENSION.

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. 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. (You could also use QUERY as QUERY can be used to set constraints on attributes. However, you are encouraged to use SPATIALQUERY since it can handle both attribute and spatial queries.) Only data that meets the query criteria is extracted. SPATIALFILTER can also be used with SPATIALQUERY to limit data extraction to that within the specified filter.

Routing to the Extract Server

The Extract Server is a private server. GET_EXTRACT requests are made to an Image or Feature 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?ClientVersion=4.0
        &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. Only layers of type featureclass can be extracted; any acetate and image 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 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>

SPATIALQUERY can also be used in a GET_EXTRACT request:

To set additional constraints on a layer based on attribute data in a specified field. (QUERY can also be used but SPATIALQUERY is recommended.) In the next example, SPATIALQUERY in the Countries layer will extract only countries beginning with the letter "C".
To limit which fields are extracted using the subfields attribute. In the States layer, only the fields STATE_NAME and POP1990 are extracted.

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. The dynamic layer must include a DATASET in order to be extracted. Acetate and image layers cannot be extracted.

To add a new layer, a WORKSPACES section must be included in the map configuration file or the request. It is recommended to always 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 can be extracted. The Ocean, Countries, World Cities, Rivers, and selected layers are extracted.

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, 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 the topic "Setting up ArcIMS Monitor and ArcIMS Tasker Property Files" in the System Administration: Administering Property Files chapter of the ArcIMS Help Contents.

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 4, or any other client using the ArcIMS Servlet Connector, the OUTPUT element is restricted by default.

In a GET_EXTRACT request, OUTPUT is ignored.

GET_EXTRACT request when OUTPUT is restricted:

In an EXTRACT response, the attribute file is not returned. The OUTPUT location is the default location specified when the service was started. The ArcIMS Spatial Server assigns the filename. OUTPUT includes only url and not file.

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 url="http://mymachine.domain.com/output/myservice_mymachine33934311.zip" />
    </EXTRACT>
  </RESPONSE>
</ARCXML>

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 the ArcIMS Help.

These restrictions apply only when the ArcIMS Servlet Connector is used. They do not apply to the ActiveX, ColdFusion, or Java Connectors. 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 are 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>