MDAC 2.5 SDK - OLE DB Providers
OLE DB Provider for ODBC

Interface Implementation Notes

The following sections discuss how the ODBC Provider implements some interfaces.

IAccessor

• Accessors might not always be validated immediately at the time of creation. Instead, they may be validated at the time the first row is fetched. Errors will be returned at the first attempt to use such an accessor.
  
  
• The ODBC Provider supports DBACCESSOR_PASSBYREF accessors. These accessors return a single pointer to the ODBC Provider's internal row buffer. This provides a significant speed improvement over copy or IMalloc bindings. The pointer is valid only while the row handle is active (until ReleaseRows is called).
  
  
• The OLE DB specification does not enable a consumer to query for the layout of the internal buffer. The ODBC Provider will return DB_E_BADBINDINFO if the type does not match exactly or if the location of the status or length is incorrect.
  
  
• The ODBC Provider does not support the DBACCESSOR_OPTIMIZED flag. The flag is ignored (for example, there is no special processing) if it is specified on an accessor.

IColumnsInfo

• Columns that have an ODBC SQL type of SQL_LONGVARCHAR or SQL_LONGVARBINARY are returned as type DBTYPE_BYTES or DBTYPE_STR, and the DBCOLUMNFLAG_ISLONG is set in the dwFlags element of the DBCOLUMNINFO structure. The ODBC Provider does not instantiate an object for these columns. Instead these settings signify that the bytes stored in the column can be retrieved or stored by requesting an ISequentialStream interface, through which the bytes can be read from or written to.
  
  
• In some ODBC drivers, duplicate columns in an unprepared command cause the ODBC Provider to receive unexpected column names. If the command contains duplicate columns and the consumer prepares the command, unprepares the command, and then executes the command, these drivers do not generate column names for the duplicate columns. This causes a warning, DB_S_ERRORSOCCURRED, in IColumnsInfo::MapColumnsID.
  
  
• The ODBC Provider does not support the following DBCOLUMNFLAGS in IColumnsInfo::GetColumnInfo:

  DBCOLUMNFLAGS_MAYDEFER

  DBCOLUMNFLAGS_WRITE

  DBCOLUMNFLAGS_CACHEDEFERRED

IColumnsRowset

• The following columns return NULL values:

  DBCOLUMN_COLLATINGSEQUENCE

  DBCOLUMN_COMPUTEMODE

  DBCOLUMN_DEFAULTVALUE

  DBCOLUMN_DOMAIN

  DBCOLUMN_HASDEFAULT

  DBCOLUMN_ISUNIQUE.

• Driver-specific columns can be requested. There is no way to return the list of what these may be for the driver in use. Consumers should specify a COLUMNID of type DBCOLKIND_GUID_PROPID, with guid equal to GUID_NULL and ulPropid equal to the value of the ODBC driver-specific option (the fDescType parameter in SQLColAttributes). A heuristic is used to determine the data type of the option from the ODBC driver.

ICommandProperties

• When used with the Microsoft SQL Server ODBC driver, the ODBC Provider cannot support both DBPROP_CANHOLDROWS and DBPROP_OTHERINSERT if each is set to VARIANT_TRUE.

ICommandText

• If SQLNativeSQL is supported in the underlying ODBC driver, the ODBC Provider will initiate a call to this ODBC function when the consumer calls ICommandText::GetCommandText with pguidDialect set to NULL. The string returned from this call is not cached; users must call ICommandText::SetCommandText with the string returned by the ODBC driver to use the native SQL statement.
  
  
• If pguidDialect is set to NULL on input, the ODBC Provider returns the command in ppwszCommand in the dialect used to set the command text. The ODBC Provider also returns S_OK (barring any other errors) rather than DB_S_DIALECTIGNORED.

ICommandWithParameters

• The data type returned in ICommandWithParameters::GetParameterInfo should be considered without regard to sign. For example, if a database server is expected to return DBTYPE_I2, the ODBC Provider can return DBTYPE_UI2; this ambiguity occurs because the underlying ODBC function SQLDescribeParam does not return the sign of the data type. In addition, the following flags are not set, because the ODBC Provider has no mechanism to obtain the status from the ODBC driver with SQLDescribeParam:

  DBPARAMFLAGS_ISSIGNED

  DBPARAMFLAGS_ISINPUT

  DBPARAMFLAGS_ISOUTPUT

  The last two of the above flags can be set for stored procedures against SQL Server.

• If the ODBC driver returns SQL_NULLABLE_UNKNOWN for a parameter, the ODBC Provider will return DBPARAMFLAGS_ISNULLABLE for that parameter.

IDBSchemaRowset

• The ODBC Provider cannot support restrictions on schema columns if the restrictions are not supported in the underlying ODBC driver.
  
  
• NULL values are returned in many columns that ANSI SQL-92 specifies as NOT NULL. These are cases in which the information is not available by means of ODBC.
  
  
• Schema rowsets do not expose IColumnsRowset or IRowsetLocate.
  
  
• The COLUMNS schema rowset is dependent on the information returned in the ODBC driver's implementation of SQLColumns. Since ODBC does not return ordinal information, the ODBC Provider always sets the value of ORDINAL_POSITION to NULL.

  The ODBC Provider returns any driver-specific columns that the ODBC driver returns in SQLColumns. This information is returned in columns beyond those described in the OLE DB specification.

  These additional columns include:

  ORDINAL, which is returned by the Microsoft® Access ODBC driver.

  ss_data_type and colid, which are returned by the Microsoft SQL Server 6.0 ODBC driver.

  "COLUMN_DEF", "SQL_DATA_TYPE", "SQL_DATETIME_SUB", "CHAR_OCTET_LENGTH", "ORDINAL_POSITION", "IS_NULLABLE", and "SS_DATA_TYPE", which are returned by the Microsoft SQL Server 6.5 ODBC driver.

• In the INDEXES schema rowset, the value of the TYPE column is set to DBPROPVAL_IT_BTREE if the value of the TYPE column returned by SQLStatistics is SQL_INDEX_CLUSTERED. The value of the NULL_COLLATION column is set to the value returned by SQLGetInfo for the SQL_NULL_COLLATION option.
  
  
• In the PROVIDER_TYPES schema rowset, the value of the DATA_TYPE column is set to DBTYPE_BYTES or DBTYPE_IUNKNOWN if the value of the DATA_TYPE column returned by SQLGetTypeInfo is a driver-specific SQL data type indicator.
  
  
• The PROVIDER_TYPES schema rowset does not support any restrictions.

IRowset

• GetNextRows may skip over rows if the underlying ODBC driver compacts data and some rows of the current rowset have been deleted.

IRowsetChange

• IRowsetChange is implemented using the ODBC function SQLSetPos. It therefore can be exposed only when the underlying ODBC driver supports SQLSetPos. If the underlying driver does not support SQLSetPos, query-based updating will be used based on an optimistic, by-value scheme.
  
  
• Newly inserted rows can be updated or deleted only through query-based updates; if query-based updating is unavailable, newly inserted rows cannot be updated. This is not the case for ODBC 3.x drivers, which return bookmarks for newly inserted rows and allow updates.
  
  
• You need to have an index on the table or else IRowsetChange::Insert Row will fail with any ISLONG column, returning an E_FAIL HRESULT.

IRowsetScroll

• If the ODBC driver supports the SQL_DIAG_CURSOR_ROW_COUNT diagnostic identifier, the two methods GetApproximatePosition and GetRowsAtRatio (which are methods of IRowsetScroll), are implemented. Depending on the type of cursor, GetInfo methods can be called to determine whether the row count is exact or approximate.

ISequentialStream

In deferred update mode, when a row's update fails, this provider does not release any of the ISequentialStream pointers due to the lack of knowledge about which pointers have and have not been read. The row is in an unknown state. If the consumer attempts to update again, failure might occur. Because responsibility for a reference on these failed interfaces still exists, this provider releases them in the following cases:

• If the consumer calls SetData for a given ISS-bound BLOB object—the old interface will be released and replaced with the new one in the deferred-update buffer.
  
  
• If the consumer calls Undo for the row.
  
  
• If the consumer resynchs the row.
  
  
• If the consumer releases the rowset.

Interface pointers are always released if the back-end updates succeed.

ITransaction

• Consumers that use the ODBC Provider should be aware of the ITransaction::Abort and ITransaction::Commit error XACT_E_CANTRETAIN, which specifies that retaining abort and commit operations are not supported and that the specified abort or commit succeeded, leaving the session in auto-commit mode. After receiving this error, consumers should check for extended error information. If extended error information is available, consumers should call ITransaction::GetTransactionInfo to determine the current transaction mode (manual-commit or auto-commit); there might be some cases in which the ODBC Provider cannot put the session in auto-commit mode despite the information implied in the XACT_E_CANTRETAIN error.

ITransactionJoin

• The ODBC Provider now supports Microsoft® Component Services (or Microsoft Transaction Server, if you are using Windows NT) and its coordinated transaction capabilities by implementing ITransactionJoin.
  
  
• Enabling support for Microsoft Component Services requires:
  • ODBC driver support for the connection attribute SQL_ATT_ENLIST_IN_DTC, which must be set.
    
    
  • That the consumer expose an IUnknown pointer from ITransactionCoordinate.