<html>
<head>
<title>ESRI ArcSDE</title>
</head>
<body bgcolor="#ffffff">
<h1>ESRI ArcSDE</h1>
OGR optionally supports reading ESRI ArcSDE database instances. ArcSDE is
a middleware spatial solution for storing spatial data in a variety of backend
relational databases. The OGR ArcSDE driver depends on being built with the
ESRI provided ArcSDE client libraries. <p>
ArcSDE instances are accessed with a datasource name of the following
form. The server, instance, username and password fields are required. The instance
is the port number of the SDE server, which generally defaults to 5151.
If the layer parameter is specified then the SDE driver is able to skip reading
the summary metadata for each layer; skipping this step can be a significant time savings. <p>
<b>Note</b>: Only GDAL 1.6+ supports querying against versions and write
operations. Older versions only support querying against the base (SDE.DEFAULT) version
and no writing operations. <p>
<pre>
SDE:server,instance,database,username,password[,layer]
</pre>
To specify a version to query against, you *must* specify a layer as well.
The SDE.DEFAULT version will be used when no version name is specified. <p>
<pre>
SDE:server,instance,database,username,password,layer,[version]
</pre>
You can also request to create a new version if it does not already exist.
If the child version already exists, it will be used unless the SDE_VERSIONOVERWRITE
environment variable is set to "TRUE". In that case, the version will be deleted
and recreated. <p>
<pre>
SDE:server,instance,database,username,password,layer,[parentversion],[childversion]
</pre>
The OGR ArcSDE driver does not support reading CAD data (treated as BLOB
attribute), annotation properties, measure values at vertices, or raster data.
The ExecuteSQL() method does <b>not</b> get passed through to the underlying
database. For now it is interpreted by the limited OGR SQL handler.
Spatial indexes are used to accelerate spatial queries.<p>
The driver has been tested with ArcSDE 9.x, and should work with newer
versions, as well as ArcSDE 8.2 or 8.3. Both 2D and 3D geometries are
supported. Curve geometries are approximated as line strings (actually
still TODO).<p>
ArcSDE is generally sensitive to case-specific, fully-qualified tablenames.
While you may be able to use short names for some operations, others (notably deleting)
will require a fully-qualified name. Because of this fact, it is generally best
to <b>always</b> use fully-qualified table names. <p>
<h3>Layer Creation Options</h3>
<ul>
<li>
<b>OVERWRITE</b>: This can be set to allow an existing layer to be
overwritten during the layer creation process. If set, and the value
is not "NO", the layer will first be deleted prior to creating a new
layer of the same name as an existing layer. Set to "NO" explicitly,
or do not include the option to treat attempts to create new layers
which collide with existing layers of the same name as an error.
Off by default.
</li>
<li>
<b>GEOMETRY_NAME</b>: By default OGR creates new layers with the
geometry (feature) column named `SHAPE'. If you wish to use a different
name, it can be supplied with the GEOMETRY_NAME layer creation option.
</li>
<li>
<b>SDE_FID</b>: Can be set to override the default name of the feature
ID column. The default is "OBJECTID".
</li>
<li>
<b>SDE_KEYWORD</b>: The DBTUNE keyword with which to create the layer.
Defaults to "DEFAULTS".
</li>
<li>
<b>SDE_DESCRIPTION</b>: The text description of the layer. Defaults to
"Created by GDAL/OGR 1.6" (Also used as the version description when
creating a new child version from a parent version.)
</li>
<li>
<b>SDE_MULTIVERSION</b>: If this creation option is set is set to
"FALSE", multi-versioning will be disabled for the layer at creation
time. By default, multiversion tables are created when layers are created
on an SDE datasource.
</li>
</ul>
<h3>Environment variables</h3>
<ul>
<li><b>OGR_SDE_GETLAYERTYPE</b>: This may be "TRUE" to determine the
geometry type from the database. Otherwise, the SDE driver will always
return an Unknown geometry type.
</li>
<li><b>OGR_SDE_SEARCHORDER</b>: This may be "ATTRIBUTE_FIRST" to tell ArcSDE
to filter based on attributes *before* using a spatial filter or
"SPATIAL_FIRST" to use the spatial filter. By default, it uses the
spatial filter first.
</li>
<li>
<b>SDE_VERSIONOVERWRITE</b>: If set to "TRUE", the specified child
version will be deleted before being recreated. Note that this action
does nothing to reconsile any edits that existed on that version before
doing so and essentially throws them away.
</li>
</ul>
<h3>Examples</h3>
See the <a href="http://trac.osgeo.org/gdal/browser/trunk/autotest/ogr/ogr_sde.py">ogr_sde.py</a> test script for some example connection strings and usage of the driver.<p>
</body>
</html>
