Oracle Data Access Components (ODAC) 19.17 Xcopy

Installation Guide

November 2022

This document provides information regarding the contents on the zip file and the steps required to setup ODAC xcopy installation and associated components.

General Information

  1.  The files of this zip file are NOT to be installed on top of an existing Oracle Universal Installer (OUI) based Oracle Home installation.
  2.  After unzipping the files, products must be installed and configured by executing the install.bat.

Installation Instructions

  1. Download the ODAC (xcopy version) zip file to a directory for staging.

  2. Unzip the file to expand the contents. The following components will be available in the created directories:
    a) ODPM - Oracle Data Provider for .NET, Managed Driver for .NET Framework 4
    b) ODP.NET4 - Oracle Data Provider for .NET, Unmanaged Driver for .NET Framework 4
    c) ODP.NET20 - Oracle Data Provider for .NET, Unmanaged Driver for .NET Framework 2.x and 3.5
    d) INSTANTCLIENT - Oracle Instant Client
    e) ORAMTS - Oracle Services for MTS
    f) ASP.NET - Oracle Providers for ASP.NET 2.0
    g) ASP.NET4 - Oracle Providers for ASP.NET 4
    h) OLEDB - Oracle Provider for OLEDB
    i) OLEDBOLAP - Oracle Provider for OLEDB for OLAP

    The install.bat will also be extracted to the same location as the ODAC zip file, which is used to install and configure.

  3. If installing into an existing xcopy home, uninstall the existing xcopy version by following the instructions in the "Uninstallation Instructions" section of this document.

  4. Execute install.bat batch file to install and configure ODAC from a Windows command line.

    Note: Depending on the install settings, administrative level privileges may be required. Oracle recommends running the batch file under the "Run as Administrator" context.

    The installation batch file uses the following parameters:

    install.bat <COMPONENT_NAME> <ORACLE_HOME_PATH> <ORACLE_HOME_NAME> [<INSTALL_DEPENDENTS>] [<MACHINE_WIDE_CONFIGURATION>] [<TNS_ADMIN_LOCATION>]

    • COMPONENT_NAME: (Required) ODAC component to install and configure. Values: ODPM (Managed ODP.NET), ODP.NET4 (Unmanaged ODP.NET), ORAMTS (Oracle Services for MTS), etc., or ALL (all components).
    • ORACLE_HOME_PATH: (Required) Directory to install ODAC into. Be mindful if installing to a protected Windows directory, such as C:\Users\<USER NAME>. These directories may have permission restrictions for who can run and which apps can be run.
    • ORACLE_HOME_NAME: (Required) Unique Oracle Home name.
    • INSTALL_DEPENDENTS: (Optional) When set to true, the script installs any dependencies the components require. Default value is true.
    • MACHINE_WIDE_CONFIGURATION: (Optional) When set to true, the script will configure ODP.NET for machine-wide default use. It makes global changes to the machine's .NET setup, including placing the provider assembly into the Global Assembly Cache (GAC) and updating the machine.config with configuration section handler and DbProviderFactory information. This parameter only works for ODPM (Managed Driver for .NET Framework 4) and ODP.NET4 (Unmanaged Driver for .NET Framework 4). Default is false.
    • TNS_ADMIN_LOCATION: (Optional) Directory that ODAC finds tnsnames.ora and/or sqlnet.ora configuration files. This setting is made in the Windows Registry.

    ORACLE_HOME_PATH and TNS_ADMIN_LOCATION directory location values that contain spaces should be enclosed in quotes (e.g. "C:\odac home\network\admin")

    Note: Preceding optional parameters in the argument list become required parameters if succeeded by optional parameters that have values set. For example, if you set the TNS_ADMIN_LOCATION parameter, you must then provide values, even when using default values, to INSTALL_DEPENDENTS and MACHINE_WIDE_CONFIGURATION parameters. You may use the following format for additional help documentation:

    install.bat -h

    To install all unmanaged ODP.NET for .NET Framework 4.0 products, here's a sample install command you can execute:

    install.bat odp.net4 c:\oracle myhome true true c:\credentials

    In this example, the 64-bit ODAC Windows Registry entries would be created under HKLM\Software\Oracle\KEY_myhome. Note that ODP.NET registry entries are simply created under HKLM\Software\Oracle\ODP.NET\ not under HKLM\Software\Oracle\KEY_<Oracle Home Name>. If multiple products are installed to the same destination directory, make sure that the Oracle Home Name that is specified as an argument to install.bat is the same for all those products. For 32-bit ODAC on 64-bit Windows, the Windows Registry entries are created under HKLM\Software\WOW6432Node\Oracle.

    By default, when install.bat is executed for a given product, the product and its dependencies will be installed and configured WITHOUT a check to see if there is a newer version of the product or its dependencies already installed. Below is the product dependency information:

    a) Unmanaged ODP.NET depends on
       - Oracle Instant Client
    b) Oracle Services for MTS depends on
       - Oracle Instant Client
    c) Oracle Providers for ASP.NET 2 depends on
       - Oracle Instant Client
       - Oracle Data Provider for .NET 2 (unmanaged driver)
    d) Oracle Providers for ASP.NET 4 depends on
       - Oracle Data Provider for .NET 4 (managed driver)
    e) Oracle Provider for OLEDB depends on
       - Oracle Instant Client
    f) Oracle Provider for OLEDB for OLAP depends on
       - Oracle Instant Client

  5. All Oracle Client software besides ODP.NET requires the Oracle Home directory and its bin subdirectory to be included in the Windows Path. Add these to the path if you are using any ODAC components that rely on Oracle Client. Unmanaged ODP.NET does not require the Oracle Home directory and its bin subdirectory to be included in the Windows Path unless the application or its dependencies use the SetDllDirectory() API.

  6. Note that configure.bat sets the value of the NLS_LANG registry key at HKLM\Software\Oracle\KEY_<Oracle Home Name> to AMERICAN_AMERICA.WE8MSWIN1252 by default. Please modify configure.bat or change this value in the registry after the install if necessary.

  7. If OraMTS is installed, the Oracle<OracleHomeName>MTSRecoveryService is created with the LocalService account as the logon account. The credentials can be changed using the "services" administration tool. The default port used is 2030. Please read the OraMTS documentation for details. Note that after the install or the configuration, the service will not be started, since it requires the install directory and its bin directory to be included in the system PATH.

  8. Applications using components from ODAC can use EZ CONNECT to connect to Oracle without depending on tnsnames.ora. Otherwise, configure or copy over tnsnames.ora from another machine and set TNS_ADMIN or ORACLE_HOME environment variable appropriately.

Power BI Setup

You can use this ODP.NET xcopy install to setup connectivity between Microsoft Power BI and Oracle Autonomous Database. Complete instructions are in the tutorial links.

Uninstallation Instructions

  1. Execute uninstall.bat from the Oracle Home installation directory to unconfigure and uninstall ODAC products.

    Note: Depending on the install settings, administrative level privileges may be required. Oracle recommends running the batch file under the "Run as Administrator" context.

    The uninstallation batch file uses the following parameters:

    uninstall.bat <COMPONENT_NAME> <ORACLE_HOME_NAME> [<MACHINE_WIDE_UNCONFIGURATION>]

    or

    uninstall.bat <COMPONENT_NAME> <ORACLE_HOME_PATH> [<MACHINE_WIDE_UNCONFIGURATION>]

    For example:

    uninstall.bat all myhome

    or

    uninstall.bat all c:\oracle

    Each component can be unconfigured and uninstalled individually. As an example, executing the following uninstalls only unmanaged ODP.NET:

    uninstall.bat odp.net4 myhome

    or

    uninstall.bat odp.net4 c:\oracle

    where "myhome" is the Oracle Home Name that was used at install time and "c:\oracle" is the installation directory. The above example will only uninstall unmanaged ODP.NET, but not its dependencies.

    MACHINE_WIDE_UNCONFIGURATION is optional and has a default value of false. If you installed ODP.NET with machine-wide configuration enabled, deinstall with MACHINE_WIDE_UNCONFIGURATION set to true.

  2. Remove the install directory and that directory's bin subdirectory from the system PATH environment variable.

Notes

  1. The install and uninstall scripts log all operations to the destination directory's install.log and uninstall.log.

  2. Oracle Services for MTS Known Issue: Oracle Services for MTS account/password name invalid when configuring ODAC xcopy on Windows configured for a Western European (non-English) language.

    Problem Statement: When executing install.bat, the following error occurs:

    Configuring Oracle Services for MTS
    ***********************************
    [SC] CreateService, failure (s) 1057:
    "The account name is invalid or does not exist, or the password is invalid for the account name..."

    Workaround: Execute the command below, substituting <OracleHomeName> and <OracleHomePath> with your deployment's specific values. Replace "NT AUTHORITY\LOCAL SERVICE" with the localized name in the West European language the Windows system uses.

    sc.exe create Oracle<OracleHomeName>MTSRecoveryService binpath= "<OracleHomePath>\bin\omtsreco.exe Oracle<OracleHomeName>MTSRecoveryService" start= auto obj= "NT AUTHORITY\LOCAL SERVICE" DisplayName= Oracle<OracleHomeName>MTSRecoveryService

    For example, if your <OracleHomeName> is "Ora" and <OracleHomePath> is "c:\Ora", execute below:
    sc.exe create OracleOraMTSRecoveryService binpath= "c:\Ora\bin\omtsreco.exe OracleOraMTSRecoveryService" start= auto obj= "NT AUTHORITY\LOCAL SERVICE" DisplayName= OracleOraMTSRecoveryService

    Sample successful execution.
    D:\odac\xcopy>sc.exe create OracleOraMTSRecoveryService binpath= "c:\Ora\bin\omtsreco.exe OracleOraMTSRecoveryService" start= auto obj= "NT AUTHORITY\LOCAL SERVICE" DisplayName= OracleOraMTSRecoveryService
    [SC] CreateService SUCCESS

  3. Additional ODAC component known issues are documented on the ODAC product documentation.

Copyright (c) Oracle Corporation 2022