Detailed Design Specification
© 2006 Ingres Corporation
Project Name
ODBC enhancements for Ingres
2006r2 – SRS item 3.1.15
Author Ralph Loen
Last Saved Date
March 8, 2016
Revision 1.1
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Responsibility List
Assigned To
Ralph Loen
Teresa King
Chris Rogers
Bruce
Lunsford
Nick Makos
Dave Dargo
Elaine Grieco
Emma
McGratten
Andy Allbritten
Action
Owner
Peer Review
Peer Review
Peer Review
Responsibility
Engineer/Architect
Development Manager
QA Manager
Level 2 Support Manager
Peer Review
Peer Review
Peer Review
Peer Review
Level 1 Support Manager
Office of the CTO
Tech Writer
Product Manager
Peer Review
Services
Note: The Responsibility List reflects those required to review and provide feedback
for the document. .
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 2 of 31
Change History:
Revision Date
Last Revision By
Description of Change
14-apr-2006
Ralph Loen
Initial version.
20-apr-2006
Ralph Loen
Revised per initial DDS review.
18 feb 2010
Teresa King
Updated to reflect reality as some of the original items
were not implemented until later ODBC Driver releases.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 3 of 31
TABLE OF CONTENTS
1
INTRODUCTION .................................................................................................................. 7
1.1 OVERVIEW......................................................................................................................... 7
1.2 SCOPE ................................................................................................................................ 7
1.3 DEFINITIONS, ACRONYMS AND ABBREVIATIONS ............................................................. 8
1.4 REFERENCES ..................................................................................................................... 8
1.5 NOTEWORTHY ISSUES ....................................................................................................... 8
1.5.1
Dependencies on other Ingres 2006r2 projects ......................................................... 8
2
ARCHITECTURE ............................................................................................................... 10
2.1 SAMPLE FLOW/EXECUTION DIAGRAM ............................................................................. 10
2.2 I18N SPECIFIC ISSUES ...................................................................................................... 10
2.3 DESIGN LIMITATION AND ASSUMPTIONS ........................................................................ 10
2.3.1
Asynchronous ODBC functions ............................................................................... 10
2.3.2
The GUID data type................................................................................................. 10
2.3.3
Translation DLL ...................................................................................................... 10
2.3.4
Installer DLL ........................................................................................................... 10
2.3.5
Support for Scrollable Cursors ................................................................................ 11
2.3.6
SQLBulkOperations() .............................................................................................. 11
2.3.7
SQLSetPos()............................................................................................................. 11
2.3.8
Support for ODBC Bookmarks ................................................................................ 11
2.4 PLATFORM SPECIFIC ISSUES............................................................................................ 11
2.4.1
ODBC CLI on Non-Windows platforms .................................................................. 11
2.5 PATENT INFORMATION .................................................................................................... 11
3
EXTERNAL SPECIFICATION ......................................................................................... 12
3.1
3.2
3.3
3.4
3.5
4
USER PERSPECTIVE ......................................................................................................... 12
ADMINISTRATION PERSPECTIVE. .................................................................................... 12
MIGRATION ISSUES ......................................................................................................... 12
SECURITY IMPACT ........................................................................................................... 13
CHANGES INITIATED BY REVIEWS/INSPECTIONS/WALKTHROUGHS............................... 13
INTERNAL SPECIFICATION .......................................................................................... 14
4.1 ESTIMATED EFFORT ........................................................................................................ 14
4.2 PROGRAMMING ............................................................................................................... 15
4.2.1
Ingres ODBC Driver................................................................................................ 15
4.2.1.1
Detailed Implementation Description............................................................... 15
4.2.1.2
External Interfaces to the Other Modules ......................................................... 15
4.2.1.2.1 SQLColumnPrivileges()................................................................................ 15
4.2.1.2.2 SQLTablePrivileges() ................................................................................... 16
4.2.1.2.3 SQLDescribeParam() .................................................................................... 17
4.2.1.2.4 Updates to SQLGetInfo() .............................................................................. 18
4.2.1.2.5 Updates to SQLGetTypeInfo()...................................................................... 19
4.2.1.2.6 ISO date/time data types ............................................................................... 19
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 4 of 31
4.3
4.4
4.5
5
4.2.1.2.7 ISO interval data types .................................................................................. 20
4.2.1.2.8 Interval escape sequence syntax ................................................................... 23
4.2.1.2.9 CONVERT Scalar Function.......................................................................... 23
RESOURCES AND FILES ................................................................................................... 24
INTERFACE ...................................................................................................................... 25
REFERENCES ................................................................................................................... 25
IMPACT SUMMARY ......................................................................................................... 26
5.1 PRODUCT/COMPONENT IMPACTS .................................................................................... 26
5.1.1
Gateways ................................................................................................................. 26
5.1.2
Clusters .................................................................................................................... 26
5.1.3
Replicator ................................................................................................................ 26
5.1.4
CL/GL Changes ....................................................................................................... 26
5.1.5
Catalog Changes ..................................................................................................... 26
5.1.6
Upgrade ................................................................................................................... 26
5.1.7
Impacts on Visual tools ............................................................................................ 26
5.2 DOCUMENTATION ........................................................................................................... 26
5.2.1
Changes to DBA Guide............................................................................................ 26
5.2.2
Changes to SQL reference manual .......................................................................... 26
5.2.3
Changes to command reference manual.................................................................. 27
5.2.4
Changes to System Administrators Guide ............................................................... 27
5.2.5
Changes to other manuals ....................................................................................... 27
5.2.6
Help System ............................................................................................................. 27
6
QUALITY ISSUES .............................................................................................................. 28
6.1 UNIT TESTING SUMMARY ............................................................................................... 28
6.1.1
Unit Testing Description.......................................................................................... 28
6.2 TESTING RECOMMENDATIONS ........................................................................................ 28
6.3 REGRESSION RISK ASSESSMENT ..................................................................................... 28
6.3.1
Backward Compatibility Issues ............................................................................... 28
7
PACKAGING AND INSTALLATION IMPACT ............................................................ 30
8
SUPPORT IMPACT ............................................................................................................ 31
8.1
8.2
STANDARD ODBC TRACING ........................................................................................... 31
INGRES TRACE ENVIRONMENT VARIABLES ..................................................................... 31
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 5 of 31
PREFACE
This document describes external functional specifications as well as design
specifications for upgrades to the Ingres ODBC driver in support of Ingres 2006r2.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 6 of 31
1 INTRODUCTION
1.1 OVERVIEW
The 3.5 version of the Ingres ODBC Driver was introduced in Ingres 2.6. This
version of the driver supported all of the Level 1 and Level 2 functions that the
2.8 driver supported, plus many of the Level 3 functions that apply to the ODBC
3.x specification as outlined by Microsoft Corporation. However, some ODBC
functions were not implemented.
The SRS for Ingres 2006r2 specifies that the Ingres ODBC driver should be fully
compliant with the ODBC 3.x specification.
The primary benefits of the ODBC upgrades are:

Better integration with Microsoft products such as MS-Access and MSExcel, and with other third-party products that use the ODBC.

Simplifies migration from other databases, such as Oracle and
SQLServer.

Improved performance.
1.2 SCOPE
The Ingres ODBC driver will be shipped as two shared library images,
iilibodbcdriver.[sfx] and iilibodbcdriverro.[sfx]. The “sfx” tag refers to the file
extension of the library image and has different specifications, depending on the
host platform.
Support for the following ODBC 3.x functions will be added:

SQLBrowseConnect()

SQLDescribeParam()

SQLColumnPrivileges()

SQLTablePrivileges()
The ODBC will be modified to support these new functions in Ingres 2006r2:

The DESCRIBE INPUT query

New data types for ISO dates and time intervals
Support will be added for the following functions via the ODBC escape sequence
syntax:

CONVERT
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 7 of 31

INTERVAL scalar
1.3 DEFINITIONS, ACRONYMS AND ABBREVIATIONS
DATA SOURCE: A collection of definitions accessed by the Driver Manager that
define the behavior of ODBC drivers.
GUI: Graphic User Interface.
INGRES API: A compiled application interface, specific to Ingres, for accessing
data.
ODBC: Open DataBase Connectivity. An API specification that details an
application interface for SQL92 (Entry Level) access to a database.
ODBC DRIVER: A shared library that is dynamically loaded by the Driver
Manager and provides a protocol for access to vendor-specific databases.
ODBC DRIVER MANAGER: A shared library that is linked to ODBC
applications and provides default driver behavior and application API.
VNODE: An Ingres/Net Virtual NODE definition. A VNODE defines the host
name, transport protocol and network port of the target DBMS installation. A
VNODE also provides a user ID and password for the target system as
authorization to establish the network connection.
1.4 REFERENCES

Ingres 2006r2 SRS.

Microsoft ODBC Programmer’s Reference.
1.5 NOTEWORTHY ISSUES
1.5.1
Dependencies on other Ingres 2006r2 projects
Some ODBC functions required for the ODBC 3.x specification are linked to other
Ingres 2006r2 projects. These functions cannot be developed until those
projects have made the necessary components available for internal testing.
These functions include:

SQLDescribeParam() – Dependent on the Describe Input project,
SRS item 3.1.9.1.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 8 of 31

ISO date and interval data types – Dependent on the ANSI Date and
Time support, SRS item 3.1.5.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 9 of 31
2 ARCHITECTURE
2.1
SAMPLE FLOW/EXECUTION DIAGRAM
A typical Ingres ODBC client can connect locally to a DBMS or use Ingres/Net
(GCC) to connect to a remote DBMS, as show below:
ODBC Client
DBMS
GCC
GCC
DBMS
2.2 I18N SPECIFIC ISSUES
Any new ODBC error messages will require localization in German, French,
Spanish, Japanese, Italian, Brazilian-Portuguese and Simplified Chinese.
2.3 DESIGN LIMITATION AND ASSUMPTIONS
2.3.1
Asynchronous ODBC functions
As specified in SRS item 3.1.15, the ODBC will not support asynchronous
processing at this time.
2.3.2
The GUID data type
The ODBC will not support the GUID (Globally Unique Identifier) data type. This
data type is specific to Microsoft Access databases.
2.3.3
Translation DLL
Ingres will not provide a Translation DLL. Translation DLL’s are used when a
client application uses a different character set than the DBMS. Ingres handles
this requirement via the II_CHARSETxx environment variable.
2.3.4
Installer DLL
Ingres will not provide an Installer DLL. On Windows, Microsoft provides an
installer DLL, which drives a set of ODBC API calls to configure ODBC drivers.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 10 of 31
The existing installer DLL may be used to install the Ingres ODBC driver if
required. On Windows, the Ingres ODBC driver may be installed from the Ingres
installer software or the Ingres ODBC Standalone Patch Installer. On Linux, the
odbcinst and iisuodbc utilities use the Ingres ODBC Configuration API to
configure driver information.
2.3.5
Support for Scrollable Cursors
Support for Scrollable Cursors will not be added with this release but with a
future release.
2.3.6
SQLBulkOperations()
Support for SQLBulkOperations() will not be added with this release but with a
future release. This feature depends upon the Ingres ODBC Driver supporting
scrollable cursors.
2.3.7
SQLSetPos()
Support for SQLSetPos() will not be added with this release but with a future
release. This feature depends upon the Ingres ODBC Driver supporting
scrollable cursors.
2.3.8
Support for ODBC Bookmarks
Support for ODBC Booksmarks will not be added with this release but with a
future release. This feature depends upon the Ingres ODBC Driver supporting
scrollable cursors.
2.4 PLATFORM SPECIFIC ISSUES
2.4.1
ODBC CLI on Non-Windows platforms
Non-windows platforms have the option to use the ODBC CLI (Call-Level
Interface), which functions as a dedicated Driver Manager. The ODBC CLI will
need to be updated to support the new ODBC functions as specified in section
1.2. This includes both the Driver Manager library and the ODBC trace library.
2.5 PATENT INFORMATION
N/A.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 11 of 31
3 EXTERNAL SPECIFICATION
3.1 USER PERSPECTIVE
Additional ODBC applications will work unmodified with Ingres.
3.2 ADMINISTRATION PERSPECTIVE.
On Windows, the libiiodbcdriver.dll and libiiodbcdriverro.dll files reside in
%II_SYSTEM%\ingres\bin. On Linux, the libiiodbcdriver.1.so and
libiiodbcdriverro.1.so files reside in $II_SYSTEM/ingres/lib. These locations are
determined by the Ingres installer.
A trace library, named libiiodbctrace.dll on Windows and libiiodbctrace.1.so on
Linux, will be made available as part of the installation, but the source code for
these files will not be published as Open Source; most of the code was provided
by Microsoft as sample code from the Microsoft Data Access SDK.
On Linux, customers have the option not to install the ODBC if the “custom”
package is selected. If the customer wishes to install the ODBC at a later date,
the iisuodbc, iiodbcinst, and iiodbcadmn utilities will allow the customer to install
and configure the ODBC post-installation.
On Windows, the Ingres ODBC driver is installed by default.
On Linux, customers have the option of linking their applications with the Ingres
ODBC CLI, unixODBC Driver Manager, or the CAI/PT Driver Manager. All of
these driver managers are supported by the Ingres ODBC driver.
The Ingres ODBC driver will have the name “Ingres 2006r2” in addition to
“Ingres” in the registry (Windows) or odbcinst.ini file (Linux).
On Linux, ODBC CLI will recognize the driver configuration attribute Vendor with
the value of “Ingres Corporation”. Vendor values of “Computer Associates” will
no longer be accepted as valid entries and will cause the ODBC CLI to ignore the
driver definition.
3.3 MIGRATION ISSUES
On Windows, the names of the ODBC DLL’s have been changed to be more
compatible with non-Windows platforms. The driver name has been changed to
“Ingres 2006r2” in addition to “Ingres”. This introduces some backwardcompatibility issues. See section 6.3.1, “Backward Compatible Issues”.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 12 of 31
3.4 SECURITY IMPACT
Not applicable.
3.5 CHANGES INITIATED BY REVIEWS/INSPECTIONS/WALKTHROUGHS
Date
Type
No
Change Description
1
2
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 13 of 31
4 INTERNAL SPECIFICATION
4.1 ESTIMATED EFFORT
Function
Man-days
SQLTablePrivileges() and SQLColumnPrivileges() code and test
5
SQLDescribeParam() - code 1
3
SQLDescribeParam() - test
2
ISO dates - code and test 2
5
ISO time intervals - code 3
8
ISO time intervals - test
5
Scrollable cursors - code 4
Scrollable cursors - test
Bookmarks - code
5
Bookmarks – test
10
5
10
15
CONVERT scalar function - code
5
ODBC CLI updates - code and test 6
5
ODBC DSN Configuration utility - code and test
5
CONVERT scalar function - test
3
INTERVAL literal escape sequence - code and test
2
SQLGetTypeInfo() updates – code and test
1
SQLGetInfo() updates - code and test
2
Additional QA tests
Total
10
125
1
Depends on Describe Input
Depends on ISO Dates
3
Depends on ISO Time Intervals
4
Depends on Scrollable Cursors
5
Depends on Scrollable Cursors
6
Depends on Scrollable Cursors
2
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 14 of 31
4.2 PROGRAMMING
4.2.1
Ingres ODBC Driver
4.2.1.1 Detailed Implementation Description
ODBC applications are linked against the Driver Manager library. The Ingres
ODBC Driver is loaded into the application via the SQLConnect() or
SQLDriverConnect() functions.
4.2.1.2 External Interfaces to the Other Modules
Support the ODBC 3.x specification as described in the Microsoft ODBC
Programmer’s Reference, except as noted in Section 2.3, Design Limitations and
Assumptions.
4.2.1.2.1 SQLColumnPrivileges()
SQLColumnPrivileges() has the following syntax:
SQLColumnPrivileges( <StatementHandle>, <CatalogName>,
<NameLength1>, <SchemaName>, <NameLength2>,
<TableName>, <NameLength3>, <ColumnName>,
<NameLength4> )
All of the arguments to SQLColumnPrivileges() are input arguments.
<StatementHandle> is the statement handle. <CatalogName> specifies the
catalog. This argument is ignored in the Ingres ODBC driver. <NameLength1>
is length of the <CatalogName> string, also ignored. <SchemaName> specifies
the schema name. In Ingres, this is the table owner name. <NameLength2> is
the length of the <SchemaName> string. <TableName> specifies the table
name. <NameLength3> is the length of the <TableName> string.
<ColumnName> specifies the column name. <NameLength4> is length of the
<ColumnName> string.
SQLColumnPrivileges() returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,
SQL_ERROR, or SQL_INVALID_HANDLE.
If successful, SQLColumnPrivileges() returns a list of columns and associated
privileges for the specified table. The driver returns the information as a standard
catalog result set, which is available for query via SQLFetch().
The contents of the result set are as follows:
Column Name
Column
Number
Data
Type
Description
TABLE_CAT
1
Varchar
Catalog identifier; NULL for Ingres.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 15 of 31
TABLE_SCHEM
2
Varchar
Schema identifier. Corresponds to table
owner name on Ingres.
TABLE_NAME
3
Varchar
not NULL
Table identifier.
COLUMN_NAME
4
Varchar
not NULL
Column name.
GRANTOR
5
Varchar
Name of the user who granted the privilege;
NULL if not applicable to the data source.
GRANTEE
6
Name of the user to whom the privilege was
granted.
PRIVILEGE
7
Varchar
not NULL
Varchar
not NULL
IS_GRANTABLE
8
Varchar
Indicates whether the grantee can grant the
privilege to others: "YES”,
"NO", or "NULL".
Identifies the column privilege. May be
SELECT, INSERT, UPDATE, or REFERENCES.
4.2.1.2.2 SQLTablePrivileges()
SQLTablePrivileges() has the following syntax:
SQLTablePrivileges( <StatementHandle>, <CatalogName>,
<NameLength1>, <SchemaName>, <NameLength2>,
<TableName>, <NameLength3> )
All of the arguments to SQLTablePrivileges() are input arguments.
<StatementHandle> is the statement handle. <CatalogName> specifies the
catalog name. This argument is ignored in the Ingres ODBC driver.
<NameLength1> is length of the <CatalogName> string, also ignored.
<SchemaName> specifies the schema name. In Ingres, this is the table owner
name. <NameLength2> is the length of the <SchemaName> string.
<TableName> specifies the table name. <NameLength3> is the length of the
<TableName> string
SQLTablePrivileges() returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,
SQL_ERROR, or SQL_INVALID_HANDLE.
If successful, SQLTablePrivileges() returns a list of tables and the privileges
associated with each table. The driver returns the information as a standard
catalog result set, which is available for query via SQLFetch().
The contents of the result set are as follows:
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 16 of 31
Column name
Column
number
Data type
Comments
TABLE_CAT
1
Varchar
Catalog name; NULL in Ingres.
TABLE_SCHEM
2
Varchar
Schema identifier. Corresponds to table
owner name on Ingres.
TABLE_NAME
3
Varchar
not NULL
Table name.
GRANTOR
4
Varchar
Name of the user who granted the privilege.
GRANTEE
5
Name of the user to whom the privilege was
granted.
PRIVILEGE
6
Varchar
not NULL
Varchar
not NULL
IS_GRANTABLE
7
Varchar
The table privilege. May be SELECT,
INSERT, UPDATE, or REFERENCES,
Indicates whether the grantee is permitted
to grant the privilege to other users; "YES",
"NO", or NULL.
4.2.1.2.3 SQLDescribeParam()
SQLDescribeParam() has the following syntax:
SQLDescribeParam( <StatementHandle>, <ParameterNumber>,
<DataTypePtr>, <ParameterSizePtr>,
<DecimalDigitsPtr>, <NullablePtr> )
<StatementHandle> is the statement handle. <ParameterNumber> is an input
argument specifying the parameter marker number, ordered sequentially in
increasing parameter order, starting at 1. <DataTypePtr> is an output argument,
and is a pointer to a buffer in which to return the SQL data type of the parameter.
When ColumnNumber is equal to 0 (for a bookmark column), SQL_BINARY is
returned in *DataTypePtr for variable-length bookmarks. <ParameterSizePtr> is
an output argument; it points to a buffer in which to return the column size.
<DecimalDigitsPtr> is an output argument that specifies the precision of the
target column. <NullablePtr> is an output parameter that points to a buffer
indicating the nullability of the parameter. <NullablePtr> may resolve to one of
the following:

SQL_NO_NULLS: The parameter does not allow NULL values (this
is the default value).

SQL_NULLABLE: The parameter allows NULL values.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 17 of 31

SQL_NULLABLE_UNKNOWN: The driver cannot determine if the
parameter allows NULL values.
SQLDescribeParam() returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,
SQL_ERROR, or SQL_INVALID_HANDLE.
SQLDescribeParam() returns the description of a parameter marker associated
with a prepared SQL statement. This information is also available in the fields of
the IPD (Implementation Row Descriptor), after SQLDescribeParam() is called.
In Ingres, SQLDescribeParam() will internally invoke a DESCRIBE INPUT query
to obtain a tuple descriptor which specifies the column characteristics of the
target table(s) that are derived from the parameter markers in the stored query.
4.2.1.2.4 Updates to SQLGetInfo()
SQLGetInfo() will now support the following attributes:
Attribute
SQL_BATCH_ROW_COUNT
SQL_BATCH_SUPPORT
SQL_CONVERT_BIGINT
SQL_CONVERT_BINARY
SQL_CONVERT_CHAR
SQL_CONVERT_DATE
SQL_CONVERT_DECIMAL
SQL_CONVERT_DOUBLE
SQL_CONVERT_FLOAT
SQL_CONVERT_FUNCTIONS
SQL_CONVERT_INTERVAL_DAY_TIME
SQL_CONVERT_INTERVAL_YEAR_MONTH
SQL_CONVERT_INTEGER
SQL_CONVERT_LONGVARBINARY
SQL_CONVERT_LONGVARCHAR
SQL_CONVERT_NUMERIC
SQL_CONVERT_REAL
SQL_CONVERT_SMALLINT
SQL_CONVERT_TIME
SQL_CONVERT_TIMESTAMP
SQL_CONVERT_TINYINT
SQL_CONVERT_VARBINARY
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 18 of 31
SQL_CONVERT_VARCHAR
SQL_CONVERT_WCHAR
SQL_CONVERT_WVARCHAR
SQL_TIMEDATE_ADD_INTERVALS
SQL_TIMEDATE_DIFF_INTERVALS
4.2.1.2.5 Updates to SQLGetTypeInfo()
SQLGetTypeInfo() will now support the following data types:
Attribute
SQL_C_INTERVAL_YEAR
SQL_C_INTERVAL_MONTH
SQL_C_INTERVAL_DAY
SQL_C_INTERVAL_HOUR
SQL_C_INTERVAL_MINUTE
SQL_C_INTERVAL_SECOND
SQL_C_INTERVAL_YEAR_TO_MONTH
SQL_C_INTERVAL_DAY_TO_HOUR
SQL_C_INTERVAL_DAY_TO_MINUTE
SQL_C_INTERVAL_DAY_TO_SECOND
SQL_C_INTERVAL_HOUR_TO_MINUTE
SQL_C_INTERVAL_HOUR_TO_SECOND
SQL_C_INTERVAL_MINUTE_TO_SECOND
SQL_TYPE_TIMESTAMP_WITH_TIMEZONE
4.2.1.2.6 ISO date/time data types
Standard SQL contains 3 distinct date/time data types: date, time, and timestamp
(a combined date and time). The declaration syntax is as follows:

DATE

TIME [(<precision>)] [<time zone option>]

TIMESTAMP [(<precision>)] [<time zone option>]
<Precision> is an integer declaring the fractions of seconds to be stored with the
TIME or TIMESTAMP; <time zone option> is either WITH TIME ZONE or
WITHOUT TIME ZONE and indicates whether TIME and TIMESTAMP values
can be accompanied by a time zone displacement value.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 19 of 31
The ODBC has SQL_TIME_STRUCT, SQL_DATE_STRUCT and
SQL_TIMESTAMP_STRUCT structures that resolve directly from the
corresponding ISO standard. The ODBC also has type definitions that
correspond directly to the ISO standard: SQL_C_TYPE_DATE,
SQL_C_TYPE_TIME, and SQL_C_TYPE_TIMESTAMP.
If the DBMS version is determined to be earlier than Ingres 2006r2, a date/time
parameter will always be bound to IIAPI_DTE_TYPE.
If the DBMS version is determined to be Ingres 2006r2 or later, date/time
parameters will be bound to their ISO counterparts in the API. If the target
column is in fact an Ingres date, it is assumed that the DBMS will convert the API
ISO data type seamlessly. If this if not the case, the ODBC will be required to
execute a “DESCRIBE INPUT” query to determine the correct API type.
4.2.1.2.7 ISO interval data types
An interval is defined as the difference between two dates and times. Intervals
are expressed in one of two different ways. One is a year-month interval that
expresses intervals in terms of years and an integral number of months. The
other is a day-time interval that expresses intervals in terms of days, minutes,
and seconds. These two types of intervals are distinct and cannot be mixed,
because months can have varying numbers of days.
An interval consists of a set of fields. There is an implied ordering among the
fields. For example, in a year-to-month interval, the year comes first, followed by
the month. Similarly, in a day-to-minute interval, the fields are in the order day,
hour, and minute. The first field in an interval type is called the leading field, or
the high-order field. The last field is called the trailing field.
In all intervals, the leading field is not constrained by rules of the Gregorian
calendar. For example, in an hour-to-minute interval, the hour field is not
constrained to be between 0 and 23 (inclusive), as it normally is. The trailing
fields subsequent to the leading field follow the usual constraints of the Gregorian
calendar.
Each of the interval C data types uses the same structure,
SQL_INTERVAL_STRUCT, to contain the interval data. Year-month intervals
are described by the SQL_YEAR_MONTH_STRUCT, and day-second intervals
are described by the SQL_DAY_SECOND_STRUCT structures.
The ODBC expresses an interval as a union of year-month and day-second
structures, prepended by range indicator and sign indicator. The structure is
listed below:
typedef struct tagSQL_INTERVAL_STRUCT
{
SQLINTERVAL interval_type;
SQLSMALLINT interval_sign;
union {
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 20 of 31
SQL_YEAR_MONTH_STRUCT year_month;
SQL_DAY_SECOND_STRUCT day_second;
} intval;
} SQL_INTERVAL_STRUCT;
The range indicator (“interval_type”) indicates the significant fields referenced in
the subordinate interval structure. For example, the SQL_C_INTERVAL_YEAR
and SQL_C_INTERVAL_YEAR_TO_MONTH data types are both described by
SQL_INTERVAL_STRUCT, but in SQL_C_INTERVAL_YEAR, only the year
portion of SQL_YEAR_MONTH_STRUCT is significant; for
SQL_C_INTERVAL_YEAR_TO_MONTH, both the year and month are
significant. For day-second interval types, the range indicator always covers
contiguous blocks of data; intervening fields are not skipped. The table below
lists the ODBC interval types:
SQL type identifier
SQL “C” type identifier
SQL data
type
SQL_INTERVAL_MONTH
SQL_C_INTERVAL_MONTH
INTERVAL
MONTH
SQL_INTERVAL_YEAR
SQL_C_INTERVAL_YEAR
INTERVAL
YEAR
SQL_INTERVAL_YEAR_TO_MONTH
SQL_C_INTERVAL_YEAR_TO_MONTH
INTERVAL
YEAR TO
MONTH
SQL_INTERVAL_DAY
SQL_C_INTERVAL_DAY
INTERVAL
DAY
SQL_INTERVAL_HOUR
SQL_C_INTERVAL_HOUR
INTERVAL
HOUR
SQL_INTERVAL_MINUTE
SQL_C_INTERVAL_MINUTE
INTERVAL
MINUTE
SQL_INTERVAL_SECOND
SQL_C_INTERVAL_SECOND
INTERVAL
SECOND
SQL_INTERVAL_DAY_TO_HOUR
SQL_C_INTERVAL_DAY_TO_HOUR
INTERVAL
DAY TO
HOUR
SQL_INTERVAL_DAY_TO_MINUTE
SQL_C_INTERVAL_DAY_TO_MINUTE
INTERVAL
DAY TO
MINUTE
SQL_INTERVAL_DAY_TO_SECOND
SQL_C_INTERVAL_DAY_TO_SECOND
INTERVAL
DAY TO
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 21 of 31
SECOND
SQL_INTERVAL_HOUR_TO_MINUTE
SQL_C_INTERVAL_HOUR_TO_MINUTE
INTERVAL
HOUR TO
MINUTE
SQL_INTERVAL_HOUR_TO_SECOND
SQL_C_INTERVAL_HOUR_TO_SECOND
INTERVAL
HOUR TO
SECOND
Coercion with other data types may not be allowed, or may be subject to
restrictions. The restrictions are that only one field in the corresponding interval
structure may be set. For example, SQL_C_INTERVAL_YEAR may be coerced
to SQL_INTEGER, but SQL_C_INTERVAL_YEAR_TO_MONTH may not,
because SQL_C_INTERVAL_YEAR_TO_MONTH references both the year and
month fields.
Coercion between compatible interval types may produce a truncation warning.
For instance, coercion of the SQL_C_INTERVAL_MONTH value “00 03” will lose
significant data if coerced into SQL_INTERVAL_YEAR; the value of the months
will be lost.
The table below shows the coercion rules for the various ODBC data types:
ODBC variable type
Year-month interval types to
year-month interval types
Year-month interval types to
day-second interval types
Day-second interval types to
day-second interval types
Day-second interval types to
year-month interval types
SQL_C_CHAR
SQL_C_LONG
SQL_C_SHORT
SQL_C_FLOAT
SQL_C_DOUBLE
SQL_C_NUMERIC
SQL_C_DATE
SQL_C_TIME
SQL_C_TIMESTAMP
SQL_C_BINARY
SQL_C_BIT
SQL_C_SBIGINT
Supported
coercion
yes
no
yes
no
yes
with restrictions
with restrictions
no
no
with restrictions
no
no
no
yes
with restrictions
with restrictions
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 22 of 31
SQL_C_UBIGINT
SQL_C_TINYINT
SQL_C_WCHAR
with restrictions
with restrictions
yes
The coercion rules above apply when SQLBindParameter() is invoked to convert
program variables into ODBC interval data types.
The present view is that the API will support only one data type to describe
intervals. Therefore, the ODBC will need to convert the intervals to strings when
calling the API to send parameters or fetch data.
4.2.1.2.8 Interval escape sequence syntax
ODBC uses escape sequences for interval literals. The syntax of this escape
sequence is as follows:
{ INTERVAL [<sign>] <interval_string> (
<interval_qualifier> }
An example of an interval literal of five seconds is shown below:
{ INTERVAL '5' SECOND(1,0)}
The ODBC will convert the above syntax to the literal string “interval ( 'seconds',
'5 seconds' )”.
4.2.1.2.9 CONVERT Scalar Function
The format of the CONVERT scalar function is:
{ FN CONVERT ( <value_exp>, <data_type> ) }
The CONVERT function returns the value specified by <value_exp> converted to
the specified <data_type>.
When the ODBC encounters the CONVERT function in a query string, it replaces
the ODBC escape sequence syntax with the appropriate Ingres query string. For
example, if an application specifies the following statement:
SELECT EMPNO FROM EMPLOYEES WHERE {fn CONVERT ( EMPNO,SQL_CHAR )} LIKE '1%'
The ODBC converts the string to the following syntax:
SELECT EMPNO FROM EMPLOYEES WHERE char ( EMPNO ) LIKE '1%'
The following table lists the supported ODBC data types and their corresponding
scalar functions in the resulting query string:
ODBC type
Ingres Scalar
Function
SQL_BIGINT
SQL_BINARY
SQL_CHAR
int8()
byte()
char()
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 23 of 31
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_INTEGER
SQL_LONGVARBINARY
SQL_LONGVARCHAR
SQL_NUMERIC
SQL_REAL
SQL_SMALLINT
SQL_DATE
SQL_TIME
SQL_TIMESTAMP
SQL_TINYINT
SQL_VARBINARY
SQL_VARCHAR
SQL_WCHAR
SQL_WVARCHAR
SQL_INTERVAL_YEAR
SQL_INTERVAL_DAY
SQL_INTERVAL_HOUR
SQL_INTERVAL_MINUTE
SQL_INTERVAL_SECOND
decimal()
float8()
float4()
int2()
long_varbyte()
long_varchar()
decimal()
float4()
int2()
date()
date()
date()
int1()
varbyte()
varchar()
nchar()
nvarchar()
interval()
interval()
interval()
interval()
interval()
If the DBMS supports scalar functions that return ISO time and ISO timestamp,
these functions will be substituted for date() as they become available. The
ODBC will not supply scalars for ISO data types, SQL_WCHAR,
SQL_WVARCHAR, SQL_DECIMAL, and SQL_NUMERIC if the target DBMS
does not support scalars for these data types.
4.3 RESOURCES AND FILES
On Windows, the primary external resource is the Microsoft ODBC Driver
Manager and ODBC Administrator. If not installed natively, these components
may be installed via the MS Data Access SDK (see
http://msdn.microsoft.com/data/mdac/downloads/default.aspx). On Linux, the
Ingres ODBC driver may be used with the unixODBC Driver Manager, the
CAI/PT Driver Manager, or the Ingres ODBC CLI. The Ingres ODBC CLI
includes the iisuodbc and iiodbcinst utilities for installing the driver manager and
the iiodbcadmn utility for configuring ODBC data sources. The CAI/PT and
unixODBC environments provide DSN configuration utilities.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 24 of 31
4.4 INTERFACE
The Ingres ODBC driver will conform to the ODBC 3.x specification, including
Microsoft extensions, as outlined in the Microsoft ODBC Programmer’s
Reference and ISO/IEC 9075-3:1995 (E) Call-Level Interface (SQL/CLI).
Exceptions are noted in section 2.3, “Design Limitations and Assumptions”.
4.5 REFERENCES
The Microsoft ODBC Programmer’s Reference is available at
http://msdn.microsoft.com/library. The ISO/IEC 9075-3:1995 specification is
available at http://linux.nist.fss.ru/hr/doc/mstd/iso/9075-3-95.htm.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 25 of 31
5 IMPACT SUMMARY
5.1 PRODUCT/COMPONENT IMPACTS
None.
5.1.1
Gateways
None.
5.1.2
Clusters
None.
5.1.3
Replicator
None.
5.1.4
CL/GL Changes
None.
5.1.5
Catalog Changes
None.
5.1.6
Upgrade
None.
5.1.7
Impacts on Visual tools
None.
5.2 DOCUMENTATION
5.2.1
Changes to DBA Guide
None.
5.2.2
Changes to SQL reference manual
None.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 26 of 31
5.2.3
Changes to command reference manual
None.
5.2.4
Changes to System Administrators Guide
None.
5.2.5
Changes to other manuals
The Ingres Connectivity Guide will state that the Ingres ODBC driver supports the
full ODBC 2.0 and ODBC 3.x specifications, except as noted in section 2.3,
“Design Limitations and Assumptions.
5.2.6
Help System
None.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 27 of 31
6 QUALITY ISSUES
6.1 UNIT TESTING SUMMARY
Testing individual functions or subroutines in isolation is called unit testing. Unit
testing in some cases requires the developer to use stubs and drivers.
6.1.1
Unit Testing Description
Unit tests will be written for the following capabilities:

SQLBrowseConnect()

SQLDescribeParam()

SQLColumnPrivileges()

SQLTablePrivileges()

The DESCRIBE INPUT query

New data types for ISO dates and time intervals

Escape syntax for CONVERT

Escape syntax for INTERVAL scalar
As these tests are compiled, they will be added to the Quiktest utility used for
regression testing by development and support.
6.2 TESTING RECOMMENDATIONS
Since none of the functions above are currently tested by the QA ODBC test
suite, these need to be added. It is the responsibility of Development to create
these tests and to follow through with QA to certify test canons and to integrate
the new tests into the existing QA test suite.
6.3 REGRESSION RISK ASSESSMENT
The new ODBC capabilities provide no additional risk.
6.3.1
Backward Compatibility Issues
If Ingres 2006r2 is installed in the same directory previously used by Ingres 2006,
existing ODBC DSN definitions will be invalid.
If customers wish to run the ODBC in both Ingres 2006 and Ingres 2006r2
environments on the same machine, existing DSN definitions that point at
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 28 of 31
“Ingres” will now reference the Ingres 2006r2 version of the Ingres ODBC (Linux
only). On Windows, existing DSN definitions will still point at Ingres 2006
because the driver path is hard-coded in the registry and takes precedence over
the driver name.
In order to minimize confusion, it is recommended that all customers delete their
existing ODBC DSN definitions and create new ones after installing the Ingres
ODBC driver. Alternatively, a utility will be provided that allows the user to view
and update the current driver names and their hard-coded path references in the
ODBC DSN definitions. This utility will be provided for both Windows and Linux.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 29 of 31
7 PACKAGING AND INSTALLATION IMPACT
The Ingres ODBC Driver is included as a component of Ingres. All of the
components are freely available from
http://www.ingres.com/products/Prod_Download_Portal.html.
On Windows, the libiiodbcdriver.dll and libiiodbcdriverro.dll files reside in
%II_SYSTEM%\ingres\bin. On Linux, the libiiodbcdriver.1.so and
libiiodbcdriverro.1.so files reside in $II_SYSTEM/ingres/lib. These locations are
determined by the Ingres installer.
Two include files, sql.h and sqlext.h, reside in $II_SYSTEM/ingres/files. These
files may be used instead of sql.h, sqlext.h, and sqltypes.h files provided in the
Data Access SDK environment (Windows) or unixODBC environment (Windows).
On Linux, if the customer chooses not to install the Ingres ODBC driver (via the
“Custom” option in the Ingres installer), the iiodbcinst and iisuodbc utilities allow
the Ingres driver to be configured after installation.
ODBC data source definitions (DSN’s) are configurable via the iiodbcadmn utility
on Linux and the odbcad32 utility on Windows.
Source code for the Ingres ODBC driver is available in the SVN repository at
http://opensource.ingres.com/projects/ingres.
A trace library, named libiiodbctrace.dll on Windows and libiiodbctrace.1.so on
Linux, will be made available as part of the installation, but the source code for
these files will not be published as Open Source; most of the code was provided
by Microsoft as sample code from the Microsoft Data Access SDK.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 30 of 31
8 SUPPORT IMPACT
8.1 STANDARD ODBC TRACING
The Ingres ODBC CLI will follow the existing convention of ODBC tracing as
performed by the unixODBC Driver Manager and Microsoft ODBC Driver
Manager. The registry or configuration files will be scanned for trace and trace
log settings. Tracing output will be very similar to what is currently provided by
the Ingres ODBC tracing DLL on Windows.
8.2 INGRES TRACE ENVIRONMENT VARIABLES
The Ingres ODBC driver currently recognizes the Ingres environment variable,
II_ODBC_TRACE, for documentation of internal ODBC routines. Response to
the II_ODBC_TRACE variable will be revised similar to other types of Ingres
tracing such as GCA. Trace levels are shown below:
Trace
Level
Trace Contents
1
Standard ODBC tracing.
2
Includes ODBC CLI state and internal routines.
3
Includes internal ODBC driver routines.
The Ingres environment variable, II_ODBC_LOG, specifies the path and file
name for an ODBC trace log file. The Ingres ODBC CLI will log from additional
trace variables such as II_GCA_TRACE and II_API_TRACE.
1067657506r2
INGRES CONFIDENTIAL AND PROPRIETARY INFORMATION FOR INTERNAL USE ONLY.
Page 31 of 31