ODAC 12c Release 3 (12.1.0.2.1) Installation Instructions, Setup, and Notes

December 2014

Download includes the following products:

  1. a) Oracle Developer Tools for Visual Studio (12.1.0.2.0)
  2. b) Oracle Data Provider for .NET 4 (12.1.0.2.0)
  3. c) Oracle Data Provider for .NET 2 (12.1.0.2.0)
  4. d) Oracle Providers for ASP.NET 4 (12.1.0.2.0)
  5. e) Oracle Providers for ASP.NET 2 (12.1.0.2.0)
  6. f) Oracle Database Extensions for .NET 4 (12.1.0.2.0)
  7. g) Oracle Database Extensions for .NET 2 (12.1.0.2.0)
  8. h) Oracle Services for MTS (12.1.0.2.0)
  9. i) Oracle Provider for OLE DB (12.1.0.2.0)
  10. j) Oracle ODBC Driver (12.1.0.2.0)
  11. k) Oracle SQL*Plus (12.1.0.2.0)
  12. l) Oracle Instant Client (12.1.0.2.0)
  13. m) Oracle Universal Installer (12.1.0.2.0)

System Requirements

The following items are required for ODAC:

  • Windows operating system
    • 32-bit: Windows 8.1 and Windows 8 (Pro and Enterprise editions), Windows 7 (Professional, Enterprise, Ultimate editions), Windows Server 2008
    • x64: Windows 8.1 and Windows 8 (Pro and Enterprise editions), Windows 7 (Professional, Enterprise, Ultimate editions), Windows Server 2012 R2 and Windows Server 2012 (Standard, Datacenter, Essentials, and Foundation editions), Windows Server 2008 R2 and Windows Server 2008 (all editions, except HPC)
  • Access to an Oracle Database Server (Oracle 10g Release 2 or later)

Additional Notes on Requirements:

  • ODP.NET requires Microsoft .NET Framework.
    • ODP.NET, Managed Driver requires .NET Framework 4 or later up to .NET Framework 4.5.2
    • ODP.NET, Unmanaged Driver requires .NET Framework 3.5 SP 1 or later up to .NET Framework 4.5.2
  • Oracle Developer Tools for Visual Studio requires Microsoft Visual Studio 2010, Visual Studio 2012, or Visual Studio 2013

    Note: Visual Studio Express Editions are not supported with the Oracle Developer Tools. However, ODP.NET is supported with Visual Studio Express Edition.

  • If you use distributed transactions with ODP.NET, Unmanaged Driver, then Oracle Services for Microsoft Transaction Server (OraMTS) must be installed. If you use distributed transactions with ODP.NET, Managed Driver, then only the OraMTS recovery service needs to be configured. The recovery service can be configured by installing OraMTS or running the OraMTS recovery service utility, oramtsctl.exe. Consult the OraMTS documentation for instructions on creating the recovery service with the utility.

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.
  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 another ODAC beta is installed, uninstall it before installing this ODAC release.

Deinstallation Instructions

The instructions below apply to deinstalling ODAC using 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 from the tree control. Click the "Remove" button.
  4. Confirm deinstallation of the Oracle Home(s) by clicking the "Yes" button.

Connection Setup Quick Start

Automatic Setup -- New in ODAC 12c

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.

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.

Install Changes to Machine.config for ODP.NET, Managed Driver

If installing ODP.NET, Managed Driver, OUI automatically copies TNS_ADMIN and LDAP_ADMIN entries into the .NET maching.config file if present in pre-existing Oracle Homes and machine-wide configuration is selected .

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\12.1.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:

    2. 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:

    2. 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_OraClient12c_home1

Machine-Wide Configuration - New in ODAC 12c Release 3

ODAC now offers machine-wide and non-machine-wide configuration for managed and unmanaged ODP.NET. The machine-wide configuration includes placing the provider assembly into the GAC and updating the machine.config with configuration section handler and DbProviderFactory information. If non-machine-wide configuration is selected, none of these changes are made. By default, ODAC install uses machine-wide configuration for a new Oracle Home install and re-installs. ODAC install defaults to the same configuration setting chosen for that Oracle Home from the previous installation.

If you plan to install ODAC 12c Release 3 and the NuGet install for ODP.NET 12.1.0.2 on the same machine, ODP.NET should be configured non-machine-wide.

Users can reconfigure ODP.NET from machine-wide configuration to non-machine-wide configuration by re-installing ODP.NET to the same Oracle Home where ODP.NET of the same version is already installed. For example, if you have already configured ODP.NET machine-wide, you can re-configure it by re- installing ODP.NET onto the same Oracle Home AND selecting the non-machine-wide configuration option.

For applications that depend on a version of ODP.NET that was not configured machine-wide, it's important to note that A) ODP.NET asssembly/assemblies that the application depends on will need to be copied over to the application directory and B) proper app.config settings will be required to use Provider Factory and/or Provider-specific configuration. See Chapter 2 of the ODP.NET Developer's Guide for more details.

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 11g Release 2 client and Oracle 12c Release 1 client), by installing the Oracle 12.1 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). Uninstall all the products in the existing Oracle Home before installing the new ODAC version.

    5. 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 12c 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 will not have access to any of the Oracle Data Source aliases from your previous installation. To be able to use 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. Starting with Oracle Database 12c Release 1 (12.1), 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 Windows built-in account or a standard Windows User Account (not an Administrator account). To learn more about the Oracle Home User, consult the Oracle Database Platform Guide 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.

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.