------------------------------------
Oracle Provider for OLE DB 8.1.7.2.0
------------------------------------
Copyright (C) Oracle Corporation 2001

This document provides information that supplements the Oracle Provider
for OLE DB documentation.


IMPORTANT INSTALLATION INFORMATION
==================================
The OraOLEDB provider, being a COM component, is NOT multiple Oracle
Home compliant. Only one version of OraOLEDB can exist on a machine at
a time.

If you have Oracle Provider for OLE DB installed on your machine,
deinstall that provider before installing the new provider.


Microsoft Visual Basic 6.0 Notes
================================
The Microsoft ActiveX Data Objects and Microsoft ActiveX Data Objects
Recordset libraries must be included as Project References.


Microsoft Visual C++ 6.0 Notes
==============================
OraOLEDB.h must be included in the relevant .cpp files in the VC++
project. Also, #define DBINITCONSTANTS needs to be added to one of
the .cpp files in the project.


1. BUG FIXES (in 8.1.7.2.0)
=============================

1.1  Interface leak when inserting rows in a recordset using client cursor.
     This causes the connection pooling to be disabled. (Bug #1545038)

1.2  IRowset::GetData call for 100 records after retrieving 1 record returns 
     E_FAIL for forward only read only recordset (Bug #1623117)

1.3  Fraction gets truncated in FLOAT column when decimal separator is 
     changed to comma (Bug #1633090)

1.4  Properties are not set properly on a recordset returned from a stored
     procedure (Bug #1683372)

1.5  Inserted value too large error (ORA-1401) while setting VARCHAR2 Column
     to NULL (Bug #1729642)


2. BUG FIXES (in 8.1.7.1.0)
=============================

2.1  Stored procedure OUT VARCHAR parameters are not NULL terminated 
     (Bug #1230040)

2.2  Unable to create triggers with :new and :old keywords (Bug #1540595)

2.3  Synonyms for stored procedures returning a REF Cursor does not work
     (Bug #1555773)

2.4  GetChunk returns incorrect data from LONG RAW columns (Bug #1571160)

2.5  DB_E_DATAOVERFLOW for DBSCHEMA_COLUMNS schema rowset if the column is 
     nullable (Bug #1571390)

2.6  GetChunk on a CLOB column against UTF8 database returns incorrect data 
     (Bug #1582093)

2.7  Intermittent access violation in OCIAttrGet (Bug #1590023)

2.8  Executing SELECT statement with a CHAR column having only spaces causes 
     a crash (Bug #1609027)

2.9  OraOLEDB sets RAW column to NULL during column update (Bug #1612285)

2.10 OraOLEDB truncates CHAR column trailing blanks against UTF8 database
     (Bug #1615235)


3. NEW CONNECTION STRING ATTRIBUTE (in 8.1.7.1.0)
=================================================

OraOLEDB introduces a new Connection String attribute, which is set in
the same way as the other Connection String attributes are set. The
provider-specific attribute is:

VCharNull - enables or disables the NULL termination of VARCHAR OUT
parameters from stored procedures. Valid values are 0 (disabled) and
1 (enabled). The default is 1 which indicates that VARCHAR OUT
parameters are NULL terminated. A value of 0 indicates that VARCHAR
OUT parameters are padded with spaces.

The default value for this attribute is located under the \\HKEY_LOCAL_
MACHINE\SOFTWARE\ORACLE\OLEDB registry key. If this attribute is not
provided at connection time, the default registry values are used.

Note that with this connection attribute enabled, applications need to
pad the stored procedure IN and IN OUT CHAR parameters with spaces
explicitly, if the parameter is to be used in a WHERE clause.

4. NEW FEATURES AND IMPROVEMENTS (in 8.1.7.0.0)
===============================================
4.1  Unicode Support

     OraOLEDB began supporting the Unicode character set against Oracle8i
     and Oracle8 databases with the 8.1.6.1.0 release. However, in that
     release, the provider required the client character set to be set
     to UTF8 to enable its support.

     With 8.1.7.0.0 release, OraOLEDB no longer requires the client character
     set to be set to UTF8. The provider still supports this configuration
     but no longer requires it. Now, all the user needs to ensure is that
     the database character set is set to UTF8. The client character set,
     as always, should be set to the native character set of the client
     machine.

     For more information, refer to the documentation that is installed
     with Oracle Provider for OLE DB.

4.2  LOB parameters to Stored Procedures

     OraOLEDB now supports accesssing LOB parameters to Stored Procedures.
     This support is dependent on the use of the SPPrmsLOB custom property
     described below and as well as in the documentation.

4.3  NCHAR parameters to SQL statements

     OraOLEDB now supports binding N datatype (NCHAR, NVARCHAR and NCLOB)
     parameters to SQL statements. This support is dependent on the use of
     the NDatatype custom property described below as well as in the
     documentation.

4.4  Custom Properties for Commands

     OraOLEDB now provides a Custom Command Property Set having three
     Custom Properties. These properties have been added to allow consumers
     to selectively enable certain features so as to limit the overhead
     of extra processing to only when required. These properties are:

     (a) PLSQLRSet: This property is functionally the same as the connection
         string attribute with the same name. It should be set to TRUE when
         the Stored Procedure is returning a rowset (REF CURSOR).
         For performance, Consumers should begin using this property rather
         than the connection string attribute.

     (b) NDatatype: This property should be set to TRUE if any of the
         parameters bound to the SQL are of Oracle's N datatypes
         (NCHAR, NVARCHAR or NCLOB).

     (c) SPPrmsLOB: This property should be set to TRUE if any of the
         parameters bound to the Stored Procedure are of Oracle's LOB
         datatypes (CLOB, BLOB, or NCLOB).
         Note that the LOB parameters can be IN, OUT and IN/OUT against
         Oracle8i (8.1.x) databases but are limited to only OUT against
         Oracle8 (8.0.x) databases.

     When used, all the custom properties should be set to TRUE before
     the Command.Execute() and reset to FALSE after it.

     Please note that ADO requires custom properties to be set to TRUE
     before each Command.Execute().

     For more information, refer to the documentation that is installed
     with Oracle Provider for OLE DB.

4.5  Multiple Rowsets

     OraOLEDB now supports returning Multiple Rowsets from a Stored
     Procedure.

4.6  Non-Packaged Stored Procedures/Functions returning Rowset

     The Provider now supports returning rowset from Non-Packaged Stored

     Procedures/Functions. (OraOLEDB 8.1.6.0.0 supported returning rowset
     from Packaged Procedures/Functions only). This feature is now
     supported against all Oracle databases (Oracle8i, Oracle8 and Oracle7).

4.7 ADOX Support

    The following ADOX objects, collections, properties, and methods are not
    supported by OraOLEDB:

    Catalog:    Create, GetObjectOwner, and SetObjectOwner methods.
    Columns:    Autoincrement, Default, Description column properties.
    Groups:     Not supported.
    Indexes:    Not supported.
    Keys:       Not supported.
    Procedures: Command property; Append and Delete methods.
    Tables:     All table properties.
    Users:      Not supported.
    Views:      Command property; Append and Delete methods.


5. TIPS, LIMITATIONS AND KNOWN ISSUES
=====================================
5.1  To improve performance, do not use ADO method AppendChunk on
     LONG/LONG RAW columns. Instead, insert or update the entire
     LONG/LONG RAW column using the ADO AddNew or Update method.

5.2  During a Local or Global Transaction, do not execute SQLs
     COMMIT, ROLLBACK or SAVEPOINT using the Command interface as
     they may affect the data consistency in the Rowsets. The same
     holds for executing DDLs (CREATE TABLE, ALTER VIEW, etc.)
     in this explicit transaction mode, as DDLs in Oracle perform
     an implicit Commit to the database. Execute DDLs only in the
     Auto-Commit mode.

5.3  Use /*+ ... */ as the optimizer hint syntax with the OraOLEDB
     driver. The hint syntax, --+ ... is currently not supported.

5.4  The Trusted Oracle datatype MLSLABEL is not supported by the
     OraOLEDB driver.

5.5  The Provider does not currently support Oracle8i Object datatypes.

5.6  For overloaded PL/SQL stored procedures and functions, the
     PROCEDURE_PARAMETERS Schema Rowset returns the parameter information
     for only the first overloaded stored procedure/function. This is
     because the OLE DB specification currently does not have any provision
     for overloaded procedures/functions.

5.7  The Command object currently errors out when updating LOBs on more
     than one row at a time.
     For example:
     UPDATE SomeTable SET LobCol = ? WHERE ...
     will error out if the UPDATE statement affects more than one row in

     the table. This restriction is limited to LOBs (BLOB/CLOB) and not
     LONGs (LONG/LONG RAW).

5.8  As most LOB write (INSERT and UPDATE) operations involve multiple
     write operations within the provider, it is recommended that the
     transaction be enabled for such operations. Enabling transaction
     will allow consumers to rollback the entire write operation in the
     event of some failure. This is recommended when writing LOBs
     from the Command or the Recordset object.

5.9  OraOLEDB currently supports the Unicode feature against Oracle8i
     and Oracle8 databases but not against Oracle7.

5.10 To get full Unicode support, the database character set should be
     UTF8. If not, there is a possibility of a data loss.

5.11 To enable creating rowsets using queries containing Oracle Database

     Links, the connection string attribute, DistribTx, should be disabled.
     Such rowsets are currently limited to being read-only.

5.12 To enable Autonomous Transaction support, the connection string
     attribute, DistribTx, should be disabled. Using this feature, consumers
     can execute Stored Procedures having COMMITs and/or ROLLBACKs.

     Note that Commit/Rollback in a stored procedure should be performed

     with caution. As OraOLEDB provides transactional capability on
     rowsets, whose data is cached locally on the client-side, performing
     an explicit commit/rollback in a stored procedure, with an open rowset,
     could cause the rowset to be out of sync with the database. In these
     cases, all commits and rollbacks (aborts) should be performed from the
     client-side (con.Commit or con.Abort). The exception is if the user

     is making use of Autonomous Transactions in the stored procedure.
     By using this, the transaction in the stored procedure is isolated
     from the main one; thus allowing for localized commits/aborts.
     Autonomous Transactions have been introduced only in Oracle8i (8.1.5)
     and are not available in the earlier releases of the RDBMS.

     For more information on Autonomous Transactions, refer to Oracle8i
     Application Developer's Guide - Fundamentals and PL/SQL User's Guide
     and Reference.

5.13 LOB parameters to Stored Procedures can be IN, OUT and IN/OUT
     against Oracle8i (8.1.x) databases but are limited to only OUT
     against Oracle8 (8.0.x) databases.

5.14 OraOLEDB currently expects the case of the objects specified in
     the Schema Rowset Restriction to be exactly the same as in the
     database. That is, it does not support passing "emp" to access
     the table "EMP". This issue will be resolved in the upcoming
     releases.

     For example:

     Dim restrictions As Variant
     ...
     ' Schemarowset contains table EMP owned by SCOTT
     restrictions = Array(Empty, "SCOTT", "EMP", Empty)
     Set objRst = objCon.OpenSchema(adSchemaTables, restrictions)
     ...
     ' Schemarowset created with no rows
     restrictions = Array(Empty, "scott", "emp", Empty)
     Set objRst = objCon.OpenSchema(adSchemaTables, restrictions)
     ...