ODAC 19c Release 1 (19.3.0.0.0) Installation Instructions, Setup, and Notes

December 2019

Download includes the following products:

  1. b) Oracle Data Provider for .NET 4 (19.3.0.1.0)
  2. c) Oracle Data Provider for .NET 2 (19.3.0.1.0)
  3. d) Oracle Providers for ASP.NET 4 (19.3.0.1.0)
  4. e) Oracle Providers for ASP.NET 2 (19.3.0.1.0)
  5. g) Oracle Services for MTS (19.3.0.1.0)
  6. h) Oracle Provider for OLE DB (19.3.0.1.0)
  7. i) Oracle OLAP Provider for OLE DB (19.3.0.1.0)
  8. l) Oracle Call Interface (19.3.0.1.0)
  9. m) Oracle C++ Call Interface (19.3.0.1.0)
  10. n) Oracle Instant Client (19.3.0.1.0)
  11. o) Oracle Universal Installer (19.3.0.1.0)

System Requirements

The following items are required for ODAC:

  • Windows x64 operating system
    • Windows 10 (Pro, Enterprise, and Education editions), Windows 8.1 (Pro and Enterprise editions), Windows Server 2019 (Standard, Datacenter, and Essentials Editions), Windows Server 2016 (Standard, Datacenter, and Essentials Editions), Windows Server 2012 R2 (Standard, Datacenter, Essentials, and Foundation editions)
  • Access to an Oracle Database 11g Release 2 (11.2.0.4) or later

Additional Notes on Requirements:

  • ODP.NET requires Microsoft .NET Framework or .NET Core.
    • ODP.NET Core requires .NET Core 2.1 or later. 
    • ODP.NET, Managed Driver requires .NET Framework 4 or later up to .NET Framework 4.8
    • ODP.NET, Unmanaged Driver requires .NET Framework 3.5 SP 1 or later up to .NET Framework 4.8
  • If you use distributed transactions with ODP.NET, read the ODP.NET Developer's Guide for more information on how to configure an application to use distributed transactions.

Installation Instructions

The instructions below apply to installing ODAC using Oracle Universal Installer. Xcopy installation instructions are included with the download itself.

  1. Download the ODAC zip file into a temporary directory. Note: Do not download this file into the "Tmp" directory.
  2. Unzip its contents to the directory.
  3. Run Oracle Universal Installer (OUI) by launching the setup.exe that was unzipped in the same directory. You will need administrator privileges.
  4. OUI will lead you through ODAC installation on your machine. After the installation, you may delete the zip file and the unzipped folders and files.

Note: If an ODAC beta is installed, uninstall it before installing this ODAC release.

Deinstallation Instructiotns

When deinstalling, use the installation type (i.e. Oracle Universal Installer, xcopy, NuGet, and MSI) that you originally installed the Oracle Home with. You should not deinstall from an Oracle Home created by another installation type. Oracle highly recommends deinstallations be executed with the same version that installed ODAC and for ODAC to be deinstalled first ahead of other Oracle components installed on the Oracle Home.

The instructions below apply to deinstalling ODAC using the Oracle Universal Installer. Xcopy deinstallation instructions are included with the download itself.

  1. Navigate to the Windows Start Menu and select "Universal Installer": (All Programs --> Oracle - <Oracle Home Name> --> Oracle Installation Products --> Universal Installer). If User Account Control is requested, grant the privilege.
  2. Click the "Deinstall Products" button.
  3. Choose the Oracle Home(s) to deinstall (i.e. Oracle Data Access Components for Oracle Client) from the tree control. Click the "Remove" button. If you are deinstalling other DB components and ODAC components from the same home, you will run a deinstaller twice. During the first run, deinstall only ODAC components using ODAC OUI. Select all the ODAC components individually to remove. Do not select the top level component, "Oracle Data Access Components for Oracle Client". This removes ODAC from the machine. During the second run, deinstall the rest of the Oracle Home using the deinstall instructions specific to how that home was installed.
  4. Confirm deinstallation of the Oracle Home(s) by clicking the "Yes" button.

To deinstall ODAC silently, execute the following on the command line:

  1. <Oracle Home Path>\oui\bin\setup.exe -silent -deinstall DEINSTALL_LIST={"oracle.odac.client","19.3.0.0.0"} ORACLE_HOME=<Oracle Home Path>

    The above command deinstalls and unconfigures the ODAC components. However, this approach of uninstalling ODAC will leave some Oracle Client binaries and any user generated files in the Oracle Home. To completely remove all the files and folders within the Oracle Home, one can run the following Windows command in addition to the first command:

  2. rmdir <Oracle Home Path>\ /s

    Note: The Oracle Home files will not be recoverable once they are deleted. Please back up anything important from the Oracle Home before executing the above command. If you wish to run this same command silently, you can execute the following instead:

  3. rmdir <Oracle Home Path>\ /s /q

Connection Setup Quick Start

Automatic Setup
When installing ODAC in a new Oracle Home, OUI automatically copies the Oracle local naming (tnsnames.ora), profile (sqlnet.ora), and directory (ldap.ora) parameter files and settings from an existing Oracle Home into the newly installed ODAC home, as long as they share the same bitness (i.e. They are both 32-bit installations or they are both 64-bit installations.)

Alternatively, existing *.ora files can be copied over from another existing Oracle Home, besides the last active one, to the new ODAC Oracle Home. OUI provides location information for these files from up to three other existing Oracle Homes if they exist. The *.ora files can be customized if the new Oracle Home uses a different configuration from the previous Oracle Home from which the files were copied over.

If installing into an existing ODAC or RDBMS Oracle Home, no new *.ora files will be copied or created.

If installing onto a machine without any previous Oracle Homes present, OUI will ask the user for the database connection alias information. OUI will then automatically create the tnsnames.ora file. If no alias information is provided, no tnsnames.ora file will be created. Even if the user doesn't have all the database connection information readily available, Oracle recommends inserting placeholder values during the install process, then modifying the tnsnames.ora file later with actual values to replace the placeholders later.

Manual Setup
Two of the most common methods for connecting an Oracle client to a database are EZCONNECT and TNSNAMES. EZCONNECT is the easiest to setup. TNSNAMES is much more maintainable in the long term. If you are new to Oracle, we recommend you use EZCONNECT. You only have to choose one or the other to connect.

These quick start instructions assume you have a valid username and password for the database server.

Note: In the setup instructions below, ORACLE_HOME represents the directory where the Oracle client Home was installed on your machine. A typical directory for an OUI Oracle client Home is:
C:\app\client\<user>\product\19.0.0\client_1

You will need to know where this directory is before proceeding.

EZCONNECT Setup

1. Copy the sqlnet.ora file located in the following directory:
ORACLE_HOME\Network\Admin\Sample\
to this directory:
ORACLE_HOME\Network\Admin\
This file tells the Oracle client by what methods (e.g. EZCONNECT) Oracle client can connect to the Oracle database server.

2. The Oracle client must then specify a valid user name, password, and data source to connect to the database server. To specify a data source, you can use the EZCONNECT format. In the ODP.NET data source attribute, use the following format to define how the client connects to the database server:
[//]host[:port][/service_name]

  • host = the database server machine's host name
  • port = the database server machine's port on which it listens for incoming connection requests
  • service_name = the database's global name

For example, some syntactically valid connection strings follow: 


"user id=hr;password=hr;data source=//sales-server:1521/sales.us.acme.com" 
   		"user id=hr;password=hr;data source=//sales-server/sales.us.acme.com" 
   		"user id=hr;password=hr;data source=sales-server/sales.us.acme.com"

If the port number is not specified, 1521 is used by default.

TNSNAMES Setup

An Oracle Net service name allows the Oracle client to use a simple alias to connect to the database server. The alias definition contains all the information needed to create a connection to the database server. Alias information is stored in the tnsnames.ora file typically located in the ORACLE_HOME\Network\Admin directory. This alias is used as the data source value in your connection string. ODAC installations do not create a tnsnames.ora file so you need to create one. The following instructions assume you will have to create a new tnsnames.ora file.

1. Copy the tnsnames.ora file located in the following directory:
ORACLE_HOME\Network\Admin\Sample\
to this directory:
ORACLE_HOME\Network\Admin\ 


<data source alias> = 
	 (DESCRIPTION = 
	 (ADDRESS = (PROTOCOL = TCP)(HOST = <hostname or IP>)(PORT = <port>)) 
	 (CONNECT_DATA = 
	 (SERVER = DEDICATED) 
	 (SERVICE_NAME = <database service name>)))
  • data source alias = the shortcut name given to identify the connect descriptor. In the ODP.NET connection string, developers set the "Data Source" attribute to the data source alias.
  • hostname or IP = the database server machine's host name or IP address
  • port = the database server machine's port on which it listens for incoming connection requests. In general, this value is set to port "1521".
  • database service name = the database's global name

The data source alias, hostname/IP, port, and database service name in the tnsnames.ora should be modified appropriately. If the TNS entries in the ORACLE_HOME\network\admin\tnsnames.ora file are not recognized by the Oracle client, create a ORACLE_HOME\oracle.key file using any text editor and type in the following line:

SOFTWARE\ORACLE\<home key>

where <home key> is the registry key for the ODAC Oracle Home. For example, if the default Oracle Home location was used during the install, the proper entry for the oracle.key file would be the following: SOFTWARE\ORACLE\KEY_OraClient19c_home1 

Machine-Wide Configuration

Machine-wide configuration is no longer supported beginning with ODAC 18c. Administrators can still place ODP.NET in the GAC and add the configuration section handler and DbProviderFactory information to machine.config manually if they wish to override ODP.NET settings for individual applications.

Common Install and Setup Issues

  1. Consult the release notes first for any known issues or limitations.
  2. Check if the Oracle data access components were properly downloaded by comparing the download size to the one listed on the download page.
  3. If you have more than one Oracle Home installed on the same machine (e.g. Oracle 19c client and Oracle 18c client), by installing the Oracle 19.3 client, OUI will establish this client as the Oracle Home all your existing applications will use. For more information on using Multiple Oracle Homes with ODP.NET, Unamanged Driver, consult the ODP.NET documentation.
  4. It is highly recommended ODAC be installed into a new Oracle Home. Installing ODAC on top of an existing Oracle home may break existing Oracle applications. If you do install on top of an existing Oracle Home, make sure to stop all the Windows services using that Oracle Home (e.g. OracleMTSRecoveryService) and it is an Oracle Client Home.

    ODAC does not support installing into an existing Oracle Server Home. ODAC can be installed into an existing Oracle Client Home if they share the first two major versions for 12.2 releases and earlier (i.e. ODAC 12.2 cannot be installed into an ODAC 12.1 home) or if they share the major version for Oracle 18 and later (i.e. Oracle 18 cannot be installed into an Oracle 19 home). When installing into an existing Oracle Client Home, the same installer technology must be used. OUI ODAC can only be installed into an OUI ODAC home; MSI ODAC into an MSI ODAC home; and xcopy ODAC into and xcopy ODAC home.

    Check whether oci.dll in the existing ORACLE_HOME directory has been removed during the uninstall process. If oci.dll was not removed, follow these steps to remove the DLL.
    a) Rename oci.dll to oci.dll.delete.
    b) Reboot your machine.
    c) Delete oci.dll.delete, which should no longer be in use after rebooting.
    d) Install the new ODAC.

  5. If installing ODAC over an existing Oracle 19c Home, already installed ODAC components will not be installed by default. You must manually select the ODAC components to be installed during the install process (i.e. check the checkbox next to the ODAC components to be installed). This is recommended for all ODAC components you wish to use, especially ODP.NET.
  6. This installation provides policy configuration files that can redirect existing 10.2 and 11.1 ODP.NET applications to the current ODP.NET version. The policy files are located in the ORACLE_HOME\odp.net\PublisherPolicy\2.x and ORACLE_HOME\odp.net\PublisherPolicy\4 directories. The installation of ODP.NET will NOT place ODP.NET policy DLLs into the GAC, which means existing applications will continue to use the same ODP.NET version they were using before.
  7. Installing ODP.NET into a new Oracle Home means that you may not have access to any of the Oracle Data Source aliases from a previous installation. To ensure you are using these existing data source attributes, copy the tnsnames.ora file in the ORACLE_HOME\network\admin directory from your previous Oracle Home installation to the same directory in your new installation. Or you may create the connection aliases manually by following the Connection Setup Quick Start earlier.
  8. Oracle Database supports the use of Oracle Home User, specified at the time of Oracle Database installation. Oracle Home User is used to run the Windows services for the Oracle Home. Oracle Home User can be a virtual account, a standard Windows User Account (not an Administrator account), or a Windows built-in account. To learn more about the Oracle Home User, consult the Administrator's Reference for Microsoft Windows.
  9. If Oracle Developer Tools (ODT) for Visual Studio 12.1.0.2.0 (part of ODAC 12c Release 3) or later is installed on a machine and the machine is to be downgraded to ODT 12.1.0.1.2 (part of ODAC 12c Release 2) or earlier, the newer ODT version must be deinstalled before installing the older ODT version. Not doing so prevents certain ODT features, such as PL/SQL Debugging, from working.
  10. ODP.NET deinstallation prior to ODAC 12c Release 3 can cause entries with .NET 2.x assembly references to be entered in the .NET 4.0 machine.config. This can cause side-by-side execution errors unless config section entry for "oracle.unmanageddataaccess.client" that references 2.x version of Oracle.DataAccess.Client is manually removed from the .NET 4.0 machine.config. It is also advised that a DbProviderFactories entry that references 2.x version of Oracle.DataAccess.Client be removed manually as well.

Viewing the ODP.NET Documentation

The PDF and HTML documentation can be viewed from the ORACLE_HOME\ODACDoc\DocumentationLibrary\welcome.html page. To view this page, go to Start Menu --> Oracle - <Oracle Home> --> Application Development --> Oracle Data Access Components Documentation.

Additionally, the Oracle documentation is installed as part of Visual Studio Dynamic Help.

Support and Bug Reports

For any bugs and issues, you may participate in one of the OTN discussion forums for ODAC.

Known Issues - Unmanaged ODP.NET

  1. If SenderId is specified in OracleAQMessage object while enqueuing, the sender id of dequeued message will have "@ODP.NE" appended in the end. [Bug 7315542]
  2. An "ORA-00942: table or view does not exist" error may be thrown from Dequeue or DequeueArray method invocations when OracleAQDequeueOptions.DeliveryMode is specified as OracleAQMessageDeliveryMode.Buffered and OracleAQDequeueOptions.Correlation is specified and there are no messages available in the queue. [Bug 7343633]

Known Issues - Entity Framework 6 for Managed and Unmanaged ODP.NET

  1. Interval Day to Second and Interval Year to Month column values cannot be compared to literals in a WHERE clause of a LINQ to Entities or an Entity SQL query.
  2. LINQ to Entities and Entity SQL (ESQL) queries that require the usage of SQL APPLY in the generated queries will cause SQL syntax error(s) if the Oracle Database being used does not support APPLY. In such cases, the inner exception message will indicate that APPLY is not supported by the database.
  3. ODP.NET does not currently support wildcards that accept character ranges for the LIKE operator in Entity SQL (i.e. [] and [^]). [Bug 11683837]
  4. Executing LINQ or ESQL query against tables with one or more column names that are close to or equal to the maximum length of identifiers (30 bytes) may encounter "ORA-00972: identifier is too long" error, due to the usage of alias identifier(s) in the generated SQL that exceed the limit.
  5. An "ORA-00932: inconsistent datatypes: expected - got NCLOB" error will be encountered when trying to bind a string that is equal to or greater than 2,000 characters in length to an XMLType column or parameter. [Bug 12630958]
  6. An "ORA-00932 : inconsistent datatypes" error can be encountered if a string of 2,000 or more characters, or a byte array with 4,000 bytes or more in length, is bound in a WHERE clause of a LINQ/ESQL query. The same error can be encountered if an entity property that maps to a BLOB, CLOB, NCLOB, LONG, LONG RAW, XMLTYPE column is used in a WHERE clause of a LINQ/ESQL query.
  7. An "Arithmetic operation resulted in an overflow" exception can be encountered when fetching numeric values that have more precision than what the .NET type can support. In such cases, the LINQ or ESQL query can "cast" the value to a particular .NET or EDM type to limit the precision and avoid the exception. This approach can be useful if the LINQ/ESQL query has computed/calculated columns which will store up to 38 precision in Oracle, which cannot be represented as .NET decimal unless the value is casted.
  8. Oracle Database treats NULLs and empty strings the same. When executing string related operations on NULLS or empty strings, the result will be NULL. When comparing strings with NULLs, use the equals operator (i.e. "x == NULL") in the LINQ query, which will in turn use the "IS NULL" condition in the generated SQL that will appropriately detect NULL-ness.
  9. If an exception message of "The store provider factory type 'Oracle.ManagedDataAccess.Client.OracleClientFactory' does not implement the IServiceProvider interface." is encountered when executing an Entity Framework application with ODP.NET, the machine.config requires and entry for ODP.NET under the section. To resolve this issue by adding an entry in the machine.config, reinstall ODAC.
  10. Creating a second instance of the context that derives from DbContext within an application and executing methods within the scope of that context that result in an interaction with the database may result in unexpected recreation of the database objects if the DropCreateDatabaseAlways database initializer is used.

More Information: https://entityframework.codeplex.com/workitem/2362

Known Workarounds:

  • Use a different database initializer,
  • Use an operating system authenticated user for the connection, or
  • Include "Persist Security Info=true" in the connection string (Warning: Turning on "Persist Security Info" will cause the password to remain as part of the connection string).

Known Issues - Oracle Providers for ASP.NET

  1. If the HKEY_LOCAL_MACHINE\Software\Oracle\NLS_LANG Registry entry is set to "NA", ORA-12705 errors will be encountered when using Oracle Providers for ASP.NET. To eliminate this problem, remove the HKEY_LOCAL_MACHINE\Software\Oracle\NLS_LANG Registry entry.

Known Issues - Oracle OLE DB for OLAP

  1. The "Initial Catalog" setting in the connection string (if set) will need to be in the same case as the user/schema name created in the database.

Known Issues - Oracle Provider for OLE DB

  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.
  2. Use /*+ ... */ as the optimizer hint syntax with the OraOLEDB driver. The hint syntax, --+ ... is currently not supported.
  3. The Provider does not support LongVarChar, LongVarWChar, LongVarBinary, and BSTR IN/OUT and OUT parameter types with OLE DB .NET Data Provider because of a Microsoft's OLE DB .NET Data Provider known limitation.
  4. The Trusted Oracle datatype MLSLABEL is not supported by the OraOLEDB driver.
  5. The provider does not currently support Object datatypes.
  6. 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).
  7. 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 transactions 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.
  8. 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.
  9. 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.
  10. 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. For more information on Autonomous Transactions, refer to Oracle "Advanced Application Developer's Guide" and "PL/SQL Language Reference".
  11. 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.
  12. 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". 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)
    ...

  13. In VB 6, Microsoft ActiveX Data Objects and Microsoft ActiveX Data Objects Recordset libraries must be included as Project References.
  14. 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.