Binary Datatypes

BINARY_FLOAT is a single-precision floating point datatype (4 bytes), which is mapped to OLE DB DBTYPE_R4.

BINARY_DOUBLE is a double-precision floating point datatype (8 bytes), which is mapped to OLE DB DBTYPE_R8.

TIMESTAMP Datatypes

This section discusses the Timestamp datatypes and then provides the following:

Sample data illustrating insert and retrieval operations using each of the Timestamp datatypes.

A Visual Basic code example using the Timestamp datatypes.

Timestamp datatypes are mapped to the OLE DB DBTYPE_DBTIMESTAMP. The OLE DB DBTYPE_DBTIMESTAMP datatype does not have TIMEZONE information

The Timestamp datatypes include:

TIMESTAMP

TIMESTAMPWITHTIMEZONE

TIMESTAMPWITHLOCALTIMEZONE

Data Insertion

For data insertion into a TIMESTAMPWITHTIMEZONE or TIMESTAMPWITHLOCALTIMEZONE column, the time zone setting of the client is used.

OLE DB Timestamp datatype cannot provide the Time Zone information. For insert operations, the default Time Zone from the client session is added to the TIMESTAMPWITHTIMEZONE column data.

Data Retrieval

For data retrieval, TIMEZONE is dropped for TIMESTAMPWITHTIMEZONE columns, but TIMEZONE is used for TIMESTAMPWITHLOCALTIMEZONE columns.

The OLE DB Timestamp datatype cannot store Time Zone information.

Factional Second

Fractional second is not supported for TIMESTAMP datatypes binding with Command objects. Note that using ALTERSESSION to change time zone information does not change the time zone information in the new and existing Recordsets. Recordsets use the client time zone setting from the Regional Options of the Operating System. The maximum fractional_seconds_precision of the TIMESTAMP is 9 and the default precision is 6.

ADO Consumers

For the Timestamp datatypes, ADO consumers must specify the CursorLocation as adUseServer and use Recordset for DML operations.

Examples of Timestamp Insert and Retrieval

The following scenarios assume that the default precision of 6 is used.

The following scenario assumes that the Time Zone of the client session is -04:00, currently on US EDT (Eastern daylight time). For an insert operation, the data in the TIMESTAMPWITHLOCALTIMEZONE column does not include Time Zone displacement, but its TIMESTAMP data is normalized to the database time zone -07:00, which is the same as US PDT (Pacific daylight time).

For a query, data is returned in the Time Zone of the client session. The Time Zone displacement is the difference (in hours and minutes) between the local time and the Coordinated Universal Time (UTC).

INTERVAL Datatypes

For the INTERVALYEARTOMONTH column, the maximum year_precision is 9, the default is 2. For INTERVALDAYTOSECOND column, the maximum day_precision is 9, the default is 2; the maximum fractional_seconds_precision is 9, the default is 6.

Data Source

A data source object in OraOLEDB is responsible for establishing the first connection to the Oracle database. To establish the initial connection, the consumer must use the CoCreateInstance function to create an instance of the data source object. This function requires important information about the provider: class ID of the provider and executable context. The class ID of OraOLEDB is CLSID_OraOLEDB.

OraOLEDB is an in-process server. When calling CoCreateInstance, use the CLSCTX_INPROC_SERVER macro. For example:

After the successful creation of an instance of a data source object, the consumer application can initialize the data source and create sessions.

OraOLEDB supports connections to Oracle databases release 7.3.4 and higher. To connect to a specific database, the consumer is required to set the following properties of the DBPROPSET_DBINIT property set:

DBPROP_AUTH_USERNAME with the user ID, such as scott

DBPROP_AUTH_PASSWORD with the password, such as tiger

DBPROP_INIT_DATASOURCE with the net service name, such as myOraDb

The consumer could also populate DBPROP_INIT_PROMPT with DBPROMPT_PROMPT which causes the provider to display a logon box for the user to enter the connect information.

Using DBPROMPT_NOPROMPT disables display of the logon box. In this case, incomplete logon information causes the provider to return a logon error. However, if this property is set to DBPROMPT_COMPLETE or DBPROMPT_COMPLETEREQUIRED, the logon box will only be displayed if the logon information is incomplete.

Connecting to an Oracle Database

To connect to an Oracle database using OraOLEDB, the OLE DB connection string must be as follows:

When connecting to a remote database, DataSource must be set to the appropriate net service name which is the alias in the tnsnames.ora file. For more information, refer to Oracle Net Services Administrator's Guide.

OraOLEDB-specific Connection String Attributes

OraOLEDB offers provider-specific Connection String attributes, which are set in the same way as the Provider and User ID are set. The provider-specific connection string attributes are:

UseSessionFormat - specifies whether to use the default NLS session formats or let OraOLEDB override some of these formats for the duration of the session. Valid values are 0 (FALSE) and 1 (TRUE). The default is FALSE which lets OraOLEDB override some of the default NLS session formats. If the value is TRUE, OraOLEDB uses the default NLS session formats.

Note that this connection attribute does not appear under the \\HKEY_LOCAL_ MACHINE\SOFTWARE\ORACLE\HOMEID\OLEDB registry key.

Default Attribute Values

The default values for these attributes are located under the \\HKEY_LOCAL_ MACHINE\SOFTWARE\ORACLE\HOMEID\OLEDB registry key.

The registry default values are read by OraOLEDB from the registry when the provider is loaded into memory. If Oracle-specific connection string attributes are not provided at connection time, the default registry values are used. However, if the attributes are provided, these new values override the default registry values.

These attributes can be set by setting the DBPROP_INIT_PROVIDERSTRING property, provided in the DBPROPSET_DBINIT property set. For example:

"FetchSize=100;CacheType=Memory;OSAuthent=0;PLSQLRSet=1;"

Distributed Transactions

The DistribTX attribute specifies whether sessions are enabled to enlist in distributed transactions. Valid values are 0 (disabled) and 1 (enabled). The default is 1 which indicates that sessions are enabled for distributed transaction enlistments.

Applications using Microsoft Transaction Server must have DistribTX set to 1, the default.

Operating System Authentication

The OSAuthent attribute specifies whether operating system authentication will be used when connecting to an Oracle database. Valid values are 0 (disabled) and 1 (enabled). The default is 0 which indicates that operating system authentication is not used.

Operating system authentication is the feature by which Oracle uses the security mechanisms of the operating system to authorize users. For more information on this subject and how to set it up on Windows clients, refer to the information on authenticating database users on Windows in Oracle Database Platform Guide for Windows.

After the Windows client has been set up properly for operating system authentication, this feature may be enabled by OraOLEDB clients by setting any of the following:

DBPROP_AUTH_USERNAME to "/"

DBPROP_INIT_PROVIDERSTRING to "OSAuthent=1;"

OSAuthent in the registry to "1"

Password Expiration

Oracle9i provides a Password Expiration feature which allows database administrators to force users to change their passwords regularly. The PwdChgDlg attribute enables or disables the displaying of the password change dialog, whenever a logon fails due to an expired password. When enabled, the provider displays the dialog to change the password. When disabled, the logon fails with an error message. The valid values are 0 (disabled) and 1 (enabled). The default is 1 (enabled). For more information on the Password Expiration feature, see Oracle Database Administrator's Guide.

Example: Connecting to an Oracle Database Using ADO

The following are examples illustrating how to connect to an Oracle database using OraOLEDB and ADO.

Note:

If the Data Source, User ID, and Password are provided with the Open method, ADO ignores those ConnectionString attributes.

OraOLEDB Sessions

An OraOLEDB session object represents a single connection to an Oracle database. The session object exposes the interfaces that allow data access and manipulation.

The first session created on the initialized data source inherits the initial connection established by IDBInitialize::Initialize(). Subsequent sessions that are created establish their own independent connections to the particular Oracle Database specified by the data source properties.

Each session object also defines a transaction space for a data source. All command and rowset objects created from a particular session object are part of the transaction of that session.

After all references to the session object are released, the session object is removed from memory and the connection is dropped.

Transactions

OraOLEDB supports local and distributed transactions which provide explicit commit and abort.

OraOLEDB does not support nested transactions. In addition, a local transaction cannot be started if the session is currently enlisted in a distributed transaction. This also applies to distributed transactions if the session is currently enlisted in a local transaction.

Local Transactions

OraOLEDB supports the ITransactionLocal interface for explicit transactions. By default, OraOLEDB is in an autocommit mode, meaning that each unit of work done on the database is automatically or implicitly committed. With the use of ITransactionLocal interface, consumers may explicitly start a transaction for a particular session, allowing a unit of work to be explicitly committed or aborted by the consumer.

OraOLEDB supports the Read Committed (Cursor Stability) isolation level. In this level, the changes made by other transactions are not visible until those transactions are committed.

Distributed Transactions

OraOLEDB consumers must install Oracle Services for Microsoft Transaction Server (MTS) release 9.0.1 or later to be able to participate in Microsoft Transaction Server (or COM+) transactions or to enlist in a distributed transaction coordinated by Microsoft Distributed Transaction Coordinator (MS DTC). For setup and configuration information on Oracle Services for MTS, see Oracle Services for Microsoft Transaction Server Developer's Guide.

OraOLEDB ignores IsoLevel, IsoFlags, and pOtherOptions parameters when ITransactionJoin::JoinTransaction() is called. These options must be provided when the consumer acquires a transaction object from MS DTC with the ITransactionDispenser::BeginTransaction() method call.

However, if IsoFlags is nonzero, XACT_E_NOISORETAIN is returned.

Commands

OraOLEDB supports ANSI SQL as supported by Oracle and the ODBC SQL syntax.

Stored Procedures

When executing an Oracle PL/SQLstored procedure using a command, use Oracle native syntax or the ODBC procedure call escape sequence in the command text:

Oracle native syntax: BEGIN credit_account(123, 40); END;

ODBC syntax: {CALL credit_account(123, 40)}

Preparing Commands

OraOLEDB validates and fetches the metadata only for SELECT SQL statements.

Command Parameters

When using Oracle ANSI SQL, parameters in the command text are preceded by a colon. In ODBC SQL, parameters are indicated by a question mark ("?").

OraOLEDB Custom Properties for Commands

OraOLEDB custom properties for Commands are grouped under the custom property set ORAPROPSET_COMMANDS. It provides these properties:

Table 2-1 Custom Properties for Commands

For Visual Basic Users

For C++ Users

PLSQLRSet

ORAPROP_PLSQLRSet

NDatatype

ORAPROP_NDatatype

SPPrmsLOB

ORAPROP_SPPrmsLOB

PLSQLRSet

This property is similar to the PLSQLRSet Connection string attribute.

The property specifies whether OraOLEDB must return a rowset from the PL/SQL stored procedure. If the stored procedure, provided by the consumer, returns a rowset, PLSQLRSet must be set to TRUE (enabled). This property should be set to FALSE after the command has been executed. By default, the property is set to FALSE (disabled).

Consumers should use the property over the attribute, as the property can be set at the command object rather than at the session. By setting it at the command object, the consumer is able to set the property only for the command object executing stored procedures which are returning rowsets. With the attribute, the consumer needed to set it even if only one of many stored procedures being executed by the ADO application returned a rowset. The use of this property should provide a performance boost to applications making use of the attribute previously.

Example: Setting the Custom Property PLSQLRSet

Dim objRes As NEW ADODB.Recordset
Dim objCon As NEW ADODB.Connection
Dim objCmd As NEW ADODB.Command
....
objCmd.ActiveConnection = objCon
objCmd.CommandType = adCmdText
' Enabling the PLSQLRSet property indicates to the provider
' that the command returns one or more rowsets
objCmd.Properties("PLSQLRSet") = TRUE
' Assume Employees.GetEmpRecords() has a REF CURSOR as
' one of the arguments
objCmd.CommandText = "{ CALL Employees.GetEmpRecords(?,?) }"
' Execute the SQL
set objRes = objCmd.Execute
' It is a good idea to disable the property after execute as the
' same command object may be used for a different SQL statement
objCmd.Properties("PLSQLRSet") = FALSE

NDatatype

This property allows the consumers to specify whether any of the parameters bound to the command are of Oracle's N datatypes (NCHAR, NVARCHAR or NCLOB). This information is required by OraOLEDB to detect and bind the parameters appropriately. This property should not be set for commands executing SELECT statements. However, this property must be set for all other SQLs such as INSERT, UPDATE, and DELETE.

The use of this property should be limited to SQLs containing parameters of N datatype as setting it incurs a processing overhead of at least one round-trip to the database. By default, this property is set to FALSE.

Note:

OraOLEDB does not support parameters of N datatypes in the WHERE clause of SQL statements.

Note:

Consumers are required to use the ODBC procedure call escape sequence to call stored procedures or functions having N datatype parameters.

Example: Setting the Custom Property NDatatype

Dim objCon As NEW ADODB.Connection
Dim objCmd As NEW ADODB.Command
Dim prEmpno As NEW ADODB.Parameter
Dim prEname As NEW ADODB.Parameter
...
objCmd.ActiveConnection = objCon
objCmd.CommandType = adCmdText
' Create and append the parameters to the command object
Set prEmpno = objCmd.CreateParameter("prEmpno", adSmallInt, adParamInput, ,8521)
' prEname is bound to a NVARCHAR column in the EMP table
Set prEname = objCmd.CreateParameter("prEname", adBSTR, adParamInput, , "Joe")
objCmd.Parameters.Append prEmpno
objCmd.Parameters.Append prEname
' Enabling the NDatatype property indicates to the provider
' that one or more of the bound parameters is of N datatype
objCmd.Properties("NDatatype") = TRUE
' Assume column ENAME in table EMP is of NVARCHAR type
objCmd.CommandText = "INSERT INTO EMP (EMPNO, ENAME) VALUES (?, ?)"
' Execute the SQL
objCmd.Execute
' It is a good idea to disable the property after execute as the same command
' object may be used for a different SQL statement
objCmd.Properties("NDatatype") = FALSE

SPPrmsLOB

This property allows the consumer to specify whether one or more of the parameters bound to the stored procedures are of Oracle's LOB datatype (CLOB, BLOB, or NCLOB). OraOLEDB requires this property to be set to TRUE, in order to fetch the parameter list of the stored procedure prior to execution. The use of this property limits the processing overhead to stored procedures having one or more LOB datatype parameters. This property should be set to FALSE after the command has been executed. By default, the property is set to FALSE.

Note:

Consumers are required to use the ODBC procedure call escape sequence to call stored procedures or functions having LOB datatype parameters.

Example: Setting the Custom Property SPPrmsLOB

Dim objCon As NEW ADODB.Connection
Dim objCmd As NEW ADODB.Command
Dim prCLOB As NEW ADODB.Parameter
...
objCmd.ActiveConnection = objCon
objCmd.CommandType = adCmdText
' Create and append the parameters to the command object
Set prCLOB = objCmd.CreateParameter("prCLOB", adLongVarchar, adParamOutput, _
10000)
objCmd.Parameters.Append prCLOB
' Enabling the SPPrmsLOB property indicates to the provider
' that one or more of the bound parameters is of LOB datatype
objCmd.Properties("SPPrmsLOB") = TRUE
' Assume the Stored Procedure requires a CLOB parameter
objCmd.CommandText = "{ call storedproc(?) }"
'Execute the SQL
objCmd.Execute
' It is a good idea to disable the property after execute as the
' same command object may be used for a different SQL statement
objCmd.Properties("SPPrmsLOB") = FALSE

Stored Procedures and Functions Returning Rowsets

Oracle Provider for OLE DB allows consumers to execute a PL/SQL stored procedure with an argument of REFCURSOR type or a stored function returning a REFCURSOR.

OraOLEDB returns a rowset for the REFCURSOR bind variable. Because there is no predefined datatype for REFCURSOR in the OLE DB specification, the consumer must not bind this parameter.

If the PL/SQL stored procedure has one or more arguments of REFCURSOR type, OraOLEDB binds these arguments appropriately and returns a rowset for each argument of REFCURSOR type.

If the PL/SQL stored function returns a REFCURSOR or has an argument of REFCURSOR type, OraOLEDB binds these appropriately and returns a rowset for each REFCURSOR type.

To use this feature, stored procedures or functions must be called in the ODBC procedure call escape sequence.

The stored procedure or function being called could be either standalone or packaged. However, the REFCURSOR being returned must be explicitly defined in a package in the database.

Multiple Rowsets

OraOLEDB supports returning more than one rowset from a stored procedure. Consumers can use this feature to access all the REFCURSORs being returned by a stored procedure.

Example: Stored Procedure Returning Multiple RowsetsPL/SQL Package

CREATE OR REPLACE PACKAGE Employees AS
TYPE empcur IS REF CURSOR;
PROCEDURE GetEmpRecords(p_cursor OUT empcur,
q_cursor OUT empcur,
indeptno IN NUMBER,
p_errorcode OUT NUMBER);
FUNCTION GetDept(inempno IN NUMBER,
p_errorcode OUT NUMBER)
RETURN empcur;
END Employees;
CREATE OR REPLACE PACKAGE BODY Employees AS
PROCEDURE GetEmpRecords(p_cursor OUT empcur,
q_cursor OUT empcur,
indeptno IN NUMBER,
p_errorcode OUT NUMBER) IS
BEGIN
p_errorcode := 0;
OPEN p_cursor FOR
SELECT *
FROM emp
WHERE deptno = indeptno
ORDER BY empno;
OPEN q_cursor FOR
SELECT empno
FROM emp
WHERE deptno = indeptno
ORDER BY empno;
EXCEPTION
WHEN OTHERS THEN
p_errorcode:= SQLCODE;
END GetEmpRecords;
FUNCTION GetDept(inempno IN NUMBER,
p_errorcode OUT NUMBER)
RETURN empcur IS
p_cursor empcur;
BEGIN
p_errorcode := 0;
OPEN p_cursor FOR
SELECT deptno
FROM emp
WHERE empno = inempno;
RETURN (p_cursor);
EXCEPTION
WHEN OTHERS THEN
p_errorcode:= SQLCODE;
END GetDept;
END Employees;

By default, ADO creates a non-updatable rowset from a command object. An updatable rowset can be created by setting the Updatability and IRowsetChange properties on the command object. The Updatability property can be set to the following values:

Table 2-2 Possible Values for Updatability Property

Value

Description

1

update

2

delete

3

update and delete

4

insert

5

insert and update

6

insert and delete

7

insert, delete, and update

The following ADO code sample sets the Updatability property on a command object to allow insert, delete, and update operations on the rowset object.

Updatability

OraOLEDB supports both immediate and deferred update mode. However, insert and update operations cannot be deferred when the operation changes a non-scalar column, such as LONG, BLOB, or CLOB. When non-scalar column values are changed in a deferred update mode, the entire row is transmitted to the database as though the operation was in an immediate update mode. In addition, these operations cannot be undone with the Undo method (ADO) or IRowsetUpdate::Undo(). But if they are in a transaction, they can be rolled back with RollbackTrans method (ADO) or ITransactionLocal::Abort().

Rowsets created using queries with joins are updatable by OraOLEDB only with the Client Cursor Engine enabled. C/C++ OLE DB consumers must enable this service to make these rowsets updatable. ADO consumers must specify the CursorLocation as adUseClient to make these rowsets updatable.

Server Data on Insert Property

If DBPROP_SERVERDATAONINSERT (Server Data on Insert) is set to TRUE using OraOLEDB, the consumer can obtain defaults, sequences, and triggered column values from newly inserted and updated rows, if the insert and update operations are made through the rowset.

Having DBPROP_SERVERDATAONINSERT set to TRUE may degrade performance for both insert and update executions using a rowset because OraOLEDB fetches row data from the database for the newly inserted and updated row. However, if DBPROP_SERVERDATAONINSERT is set to its default value of FALSE, only the explicitly provided values for insert and update operations get returned when column values are requested for those rows.

If the base table from which the rowset was created does not contain any defaults, sequences, or triggers, it is highly recommended that DBPROP_SERVERDATAONINSERT retain its default value of FALSE.

The DBPROP_SERVERDATAONINSERT property does not affect the performance of insert and update executions using the command object.

To Search for Rows with IRowsetFind::FindNext

When a search is done with a NULL value, only the DBCOMPAREOPS_EQ and DBCOMPAREOPS_NE compare operations are supported. Otherwise, DB_E_NOTSUPPORTED is returned.

OraOLEDB-specific Connection String Attributes for Rowsets

OraOLEDB-specific connection string attributes which affect the performance of the rowset are:

CacheType - specifies the type of caching used by the provider to store rowset data. OraOLEDB provides two caching mechanisms:

Memory - The provider stores all the rowset data in-memory. This caching mechanism provides better performance at the expense of higher memory utilization. The default is Memory.

File - The provider stores all the rowset data on disk. This caching mechanism limits the memory consumption at the expense of performance.

ChunkSize - This attribute specifies the size, in bytes, of the data in LONG and LONG RAW columns fetched and stored in the provider cache. Providing a high value for this attribute improves performance, but requires more memory to store the data in the rowset. Valid values are 1 to 65535. The default is 100.

FetchSize - specifies the number of rows the provider will fetch at a time (fetch array). It must be set appropriately depending on the data size and the response time of the network. If the value is set too high, this could result in more wait time during the execution of the query. If the value is set too low, this could result in many more round trips to the database. Valid values are 1 to 429,496,296. The default is 100.

The default attributes values are set in the registry. For more information, see "Default Attribute Values". The following ADO code example overrides the default attribute values:

Tips for ADO Programmers

Setting the ADO Rowset property LockType to adLockPessimistic is not supported by Oracle Provider for OLE DB. If LockType is set to adLockPessimistic, OraOLEDB behaves similar to when set as adLockOptimistic. This behavior occurs because OraOLEDB does not perform explicit locks on the rows being modified. However, when the new data is submitted to the database, it only performs the update if the rowset data was not already updated by another user, which means that dirty writes are not allowed. LockType values adLockReadOnly, adLockBatchOptimistic, and adLockOptimistic are supported by OraOLEDB.

Setting ADO Rowset property CursorType to adOpenKeyset or adOpenDynamic is not supported by Oracle Provider for OLE DB. OraOLEDB does not support either of the two as Oracle supports Statement Level Read Consistency, which ensures that the data returned by a query contains only committed data as of the time the query was executed. CursorType values adOpenStatic and adOpenForwardOnly are supported by OraOLEDB.

Schema Rowsets

The schema rowsets available through Oracle Provider for OLE DB are:

DBSCHEMA_COLUMNS

DBSCHEMA_INDEXES

DBSCHEMA_SCHEMATA

DBSCHEMA_VIEWS

DBSCHEMA_TABLES

DBSCHEMA_PROVIDER_TYPES (forward scroll only)

DBSCHEMA_FOREIGN_KEYS

DBSCHEMA_PRIMARY_KEYS

DBSCHEMA_PROCEDURES

DBSCHEMA_PROCEDURE_PARAMETERS

Date Formats

The date format for the Oracle session cannot be set using ALTER SESSION SET NLS_DATE_FORMAT command. In Visual Basic, the date formats are controlled by the Regional Settings properties in the Windows Control Panel. For more information on Visual Basic date formats, refer to your Visual Basic documentation.

For Oracle Provider for OLE DB, if the Connection property UseSessionFormat is FALSE, which is a default value, NLS_DATE_FORMAT is fixed for the session to 'YYYY-MM-DD HH24:MI:SS' by the provider. If you pass the date to Oracle as a string, the date must be in the 'YYYY-MM-DD HH24:MI:SS' format. If UseSessionFormat is TRUE, NLS_DATE_FORMAT is not fixed by Oracle Provider for OLE DB and the default session NLS_DATE_FORMAT is used. For example:

SELECT * FROM EMP WHERE HIREDATE > '1981-06-15 17:32:12'

To use a different format, you need to use the SQL function, TO_DATE(), to specify the format for dates passed as strings. For example:

SELECT * FROM EMP WHERE HIREDATE > TO_DATE('15-JUN-81', 'DD-MON-YY')

However, for dates passed as parameters, the date format is controlled by ADO, which is controlled by the Regional Settings in the Windows Control Panel. In this case, TO_DATE() should not be used. For example:

Case of Object Names

The names of all objects (tables, columns, views, and so forth) in Oracle are case-sensitive. This allows the two objects EMP and emp to exist in the same namespace in the database.

The query, SELECT ename FROM emp, executes correctly even though the table name is EMP (all uppercase) in the database. However, if you want to specify object names in mixed case, you can do so by enclosing the name in double quotes. For example:

SELECT ename FROM "Emp"

will execute successfully if the table name in the database is Emp. Double quotes preserve the case of the object names in Oracle.

LOB Support

The ISequentialStream interface is supported for all LONG, LONG RAW, and LOB (BLOB, CLOB, NCLOB, and BFILE) columns. The consumer can use this interface to read and write to all the LOB columns, except BFILE which is read-only. To have read and write access to these columns, the SELECT SQL statement used to create the rowset should not contain a join.

Note:

Although most of the LOB columns in an Oracle database support up to 4 GB of data storage, ADO limits the maximum column size to 2 GB.

Columns having the BFILE datatype are not updatable in the Rowset interface. However, these columns can be updated using the Command interface, if the update is limited to modifying the directory and name of the external file pointed to by the BFILE column. For example:

Unicode Support

OraOLEDB supports the Unicode character set. Using this feature, consumers can use OraOLEDB to access data in multiple languages on the same client computer. It can be especially useful in creating global Internet applications supporting as many languages as the Unicode standard entails. For example, you can write a single Active Server Page (ASP) that accesses an Oracle9i database to dynamically generate contents in Japanese, Arabic, English, and Thai, and so on.

Types of Unicode Encoding

The Oracle databases store the Unicode data in the UTF8 encoding scheme, which is an ASCII compatible multibyte encoding of Unicode. Microsoft Windows 2000 and NT 4.0 use the UCS2 encoding, which is a 2-byte fixed width encoding scheme. OraOLEDB transparently converts the data between the two encoding schemes allowing the consumers to deal with only UCS2.

Note:

The Unicode support is transparent to ADO consumers. OLE DB consumers using C/C++ need to explicitly specify DBTYPE_WSTR in their datatype bindings when Unicode data in involved.

How Oracle Unicode Support Works

OraOLEDB works in two modes, Unicode mode and non-Unicode mode. When the client character set is not a superset of the server character set, OraOLEDB automatically enables the Unicode mode. In this mode, OraOLEDB stores the data in its cache in the UCS2 encoding scheme. The user should ensure that the database's character set is UTF8 in order to prevent any data loss.

If the client character set is a superset of the server's, the provider operates in the non-Unicode mode. This mode provides slightly better performance as it does not have to deal with larger character buffers required by the UCS2 encoding.

The detection of the client's and the server's character set is performed during logon.

Note:

OraOLEDB no longer requires the client character set to be set to UTF8 to enable the Unicode mode. The provider still supports such setups but no longer requires it.

Unicode Support Setup

In order to prevent any data loss, the database character set should be UTF8. Other than this, there is no other setup required for the Unicode support.

Database Setup

You must ensure that the Oracle database is configured to store the data in the UTF8 character set. The character set configuration is typically specified during database creation. To check the character set setting of your database, execute the following query in SQL*Plus:

If the character set of your database is not UTF8, you need to create a new database with the UTF8 character set and import your data into it. See Oracle Database Administrator's Guide for more information.

Errors

OLE and COM objects report errors through the HRESULT return code of the object member functions. An OLE/COM HRESULT is a bit-packed structure. OLE provides macros that dereference structure members. OraOLEDB exposes IErrorLookup to retrieve information about an error.

All objects support extended error information. For this, the consumer must instantiate the OLE DB Extended Error object followed by calling the method GetErrorDescription() to get the error text.

// Instantiate OraOLEDBErrorLookup and obtain a pointer to its
// IErrorLookup interface
CoCreateInstance(CLSID_OraOLEDBErrorLookup, NULL, CLSCTX_INPROC_SERVER,
IID_IErrorLookup, (void **)&pIErrorLookup)
//Call the method GetErrorDescription() to get the full error text
pIErrorLookup->GetErrorDescription()

The OraOLEDB provider returns the entire error stack in one text block.

Using OraOLEDB Custom Properties

ADO allows OraOLEDB provider-specific properties to be set at the object level. The OraOLEDB-specific properties SPPrmsLOB and NDatatype can only be set at the ADO command object level, as shown in the following example:

However, the OLE DB .NET Data Provider cannot expose OLE DB provider-specific properties at the object level. Therefore, the SPPrmsLOB and NDatatype properties can only be set as connection string attributes when OraOLEDB is used by OLE DB .NET Data Provider:

Both SPPrmsLOB and NDatatype connection string attributes are set to False by default if they are not specified.

Setting either of these connection string attributes to True incurs additional processing overhead when executing commands with parameters. For this reason, before setting either attribute to True, see "OraOLEDB Custom Properties for Commands".

Updating Oracle with DataTable Changes

In order for the OleDbDataAdapter.Update() method to properly update Oracle with changes made in the DataTable, the DataTable must contain a primary key of a database table. If the database table does not contain a primary key, the ROWID must be selected explicitly when populating the DataTable, so that the ROWID can be used to uniquely identify a row when updating a row in the database.

Do not select the ROWID from database tables that contains a primary key. If the ROWID is selected along with a primary key, the ROWID will be the only column marked as the primary key.

See Also:

For further information on using the OLE DB .NET Data Provider

Microsoft .NET Documentation

Microsoft .NET Framework Class Library

Using OraOLEDB with Visual Basic

The following simple example illustrates how to use Oracle Provider for OLE DB with ADO in Visual Basic 6.0 to connect to an Oracle database and execute PL/SQL stored procedures and functions.

Setting Up the Oracle Database

This example assumes that the Oracle database has the demonstration table EMP under the user account scott. The scott account is included in the Oracle starter database. If the account does not exist on your database, create the account before running the sample program. If your database does not contain the emp table, you can use the demobld.sql script to create the demonstration tables.

This example also uses exampledb as the database network alias when connecting to the Oracle database. You must change this network alias to match your system.

Step 1 Build the Sample Tables:

Start SQL*Plus.

Connect as username scott with the password tiger.

Run the demobld.sql script:

SQL> @ORACLE_BASE\ORACLE_HOME\sqlplus\demo\demobld.sql;

After the emp table has been created in the scott account, you need to create the PL/SQL package that contains the stored procedure and function that are run in the Visual Basic example.