1.. _vector.ingres:
2
3INGRES
4======
5
6.. shortname:: INGRES
7
8.. build_dependencies:: INGRESS
9
10This driver implements read and write access for spatial data in
11`INGRES <http://www.actian.com/products/ingres/geospatial/>`__ database
12tables.
13
14When opening a database, its name should be specified in the form
15"@driver=ingres,[host=*host*,
16instance=\ *instance*],dbname=\ *[vnode::]dbname* [,options]". where the
17options can include comma separated items like
18"host=*ip_address*","instance=*instance*", "username=*userid*",
19"password=*password*", "effuser=*database_user*",
20"dbpwd=*database_passwd*", "timeout=*timeout*", "tables=table1/table2".
21
22**The driver and dbname values are required, while the rest are
23optional.** If username and password are not provided an attempt is made
24to authenticate as the current OS user.
25
26If the host and instance options are both specified, the username and
27password \*must\* be supplied as it creates a temporary `dynamic vnode
28connection <http://docs.actian.com/ingres/10.0/command-reference-guide/1207-dynamic-vnode-specificationconnect-to-remote-node>`__.
29The default protocol is TCP/IP. If any other protocol is expected to be
30used, a pre-built vnode is preferable. If vnode and these two options
31are passed at the same time, an error will occur.
32
33The option effuser and dbpwd are mapped to the real user name and
34password needs to be authorized in dbms, compared to the username and
35password which are used for OS level authorization.
36
37Examples:
38
39::
40
41     @driver=ingres,host=192.168.0.1, instance=II, dbname=test,userid=warmerda,password=test,effuser=frank, dbpwd=123, tables=usa/canada
42
43     @driver=ingres,host=192.168.0.1, instance=II, dbname=test,userid=warmerda,password=test,tables=usa/canada
44
45     @driver=ingres,dbname=test,userid=warmerda,password=test,tables=usa/canada
46
47     @driver=ingres,dbname=test,userid=warmerda,password=test,tables=usa/canada
48
49     @driver=ingres,dbname=test,userid=warmerda,password=test,tables=usa/canada
50
51     @driver=ingres,dbname=server::mapping
52
53     @driver=ingres,dbname=mapping
54
55If the tables list is not provided, an attempt is made to enumerate all
56non-system tables as layers, otherwise only the listed tables are
57represented as layers. This option is primarily useful when a database
58has a lot of tables, and scanning all their schemas would take a
59significant amount of time.
60
61If an integer field exists in a table that is named "ogr_fid" it will be
62used as the FID, otherwise FIDs will be assigned sequentially. This can
63result in different FIDs being assigned to a given record/feature
64depending on the spatial and attribute query filters in effect at a
65given time.
66
67By default, SQL statements are passed directly to the INGRES database
68engine. It's also possible to request the driver to handle SQL commands
69with :ref:`OGR SQL <ogr_sql_dialect>` engine, by passing **"OGRSQL"**
70string to the ExecuteSQL() method, as name of the SQL dialect.
71
72The INGRES driver supports OGC SFSQL 1.1 compliant spatial types and
73functions, including types: POINT, LINESTRING, POLYGON, MULTI\*
74versions, and GEOMETRYCOLLECTION.
75
76Driver capabilities
77-------------------
78
79.. supports_create::
80
81Caveats
82-------
83
84-  No fast spatial index is used when reading, so spatial filters are
85   implemented by reading and parsing all records, and then discarding
86   those that do not satisfy the spatial filter.
87
88Creation Issues
89---------------
90
91The INGRES driver does not support creation of new datasets (a database
92within INGRES), but it does allow creation of new layers (tables) within
93an existing database instance.
94
95-  The INGRES driver makes no allowances for character encodings at this
96   time.
97-  The INGRES driver is not transactional at this time.
98
99Layer Creation Options
100~~~~~~~~~~~~~~~~~~~~~~
101
102-  **OVERWRITE**: This may be "YES" to force an existing layer of the
103   desired name to be destroyed before creating the requested layer.
104-  **LAUNDER**: This may be "YES" to force new fields created on this
105   layer to have their field names "laundered" into a form more
106   compatible with MySQL. This converts to lower case and converts some
107   special characters like "-" and "#" to "_". If "NO" exact names are
108   preserved. The default value is "YES".
109-  **PRECISION**: This may be "TRUE" to attempt to preserve field widths
110   and precisions for the creation and reading of MySQL layers. The
111   default value is "TRUE".
112-  **GEOMETRY_NAME**: This option specifies the name of the geometry
113   column. The default value is "SHAPE".
114-  **INGRES_FID**: This option specifies the name of the FID column. The
115   default value is "OGR_FID"
116-  **GEOMETRY_TYPE**: Specifies the object type for the geometry column.
117   It may be one of POINT, LSEG, LINE, LONG LINE, POLYGON, or LONG
118   POLYGON. By default POINT, LONG LINE or LONG POLYGON are used
119   depending on the layer type.
120
121Older Versions
122--------------
123
124The INGRES GDAL driver also includes support for old INGRES spatial
125types, but these are not enabled by default. It enable these, the input
126*configure* script needs to include pointers to libraries used by the
127older version:
128
129::
130
131   INGRES_LIB="-L$II_SYSTEM/ingres/lib \
132            $II_SYSTEM/ingres/lib/iiclsadt.o \
133            $II_SYSTEM/ingres/lib/iiuseradt.o \
134            -liiapi.1 -lcompat.1 -lq.1 -lframe.1"
135