Oracle Database Extensions for .NET

Installation Guide and Release Notes

For whitepapers, walkthroughs, demos and more information, visit the Oracle Database Extensions for .NET Tech Center at http://www.oracle.com/technology/tech/dotnet/ode/index.html

Release 10.2.0.2.20

July 2006

Copyright (c) Oracle Corporation 2006

This file contains important information about the Oracle Database Extensions for .NET which is a database option for Oracle Database 10g Release 2 on Windows. The following topics are covered.

Support and Product Feedback

Oracle is very interested to hear your comments related to this feature, including feature requests and bug reports. Please visit the Oracle Technology Network (OTN) community forums to tell us what you think!

http://forums.oracle.com/forums/forum.jspa?forumID=254 (Registration with OTN required)

Installation and Configuration

Prerequisite:

Oracle Database Extensions for .NET 10.2.0.1.0 must have been installed and configured on the Oracle Server machine in the same Oracle Home where Oracle Database Extensions for .NET 10.2.0.2.20 will be installed. This is included in the Oracle Database 10g install.

Installation Instructions:

Stop the service Oracle<ORACLE_HOME>ClrAgent from Services Control Panel. Use Task Manager to make sure that extproc.exe process is not running.
Run setup.exe to start the Oracle Installer
Choose to install Oracle Database Extensions for .NET (For .NET 1.x) or Oracle Database Extensions for .NET (For .NET 2.0) depending on your version of .NET
Choose to install this into the same Oracle home as the Oracle Database
After installation completes, run <Oracle Home>\rdbms\admin\DBMSClr.plb as SYSDBA using SQL*Plus. For example, from SQL*Plus:
1. connect sys/password as sysdba
2. @DBMSClr.plb
Start the service Oracle<ORACLE_HOME>ClrAgent from Services Control Panel.

Documentation

Visual Studio .NET Help Integration

The Oracle Database Extensions for .NET Developers Guide has been integrated with Visual Studio .NET help and is included as part of the Oracle Developer Tools for Visual Studio .NET version 10.2 or later.

Online Documentation

The documentation may also be read online at the Oracle Technology Network (OTN).
http://download.oracle.com/docs/cd/B19306_01/win.102/b14306/toc.htm
http://download.oracle.com/docs/cd/B19306_01/win.102/b14306.pdf

Information and Known Issues

Running .NET stored procedure in a machine having multiple .NET runtime versions

If multiple .NET runtime versions exists on the server machine then Oracle Database Extensions for .NET uses the latest .NET runtime available in the machine. Oracle Database Extensions for .NET can be configured to load a particular .NET runtime by setting a registry value. Create the following registry entry - HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_<HOMENAME>\ODE where HOMENAME is the appropriate Oracle Home

Create a string value .NETFramework in this registry key and set it to the appropriate .NET runtime version.

For example, if the server machine is having .NET framework version 1.1 and 2.0 and the .NET stored procedures are built with .NET framework 1.1, then this registry value may be set to v1.1.4322 to instruct Oracle Database Extensions for .NET to load .NET framework version 1.1.4322.

Following are typical .NET runtime version values for various .NET versions -
1.0 : v1.0.3705
1.1 : v1.1.4322
2.0 : v2.0.50727

Debug Tracing

ODE.NET provides debug tracing support, which allows logging of all the ODE.NET activities into a trace file. Different levels of tracing are available.

The following registry settings should be configured under HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_<HOMENAME>\ODE where HOMENAME is the appropriate Oracle Home.

TraceFileName :
Any valid path name and file name. TraceFileName specifies the file name that is to be used for logging trace information. If TraceOption is set to 0, the name is used as is. However, if TraceOption is 1, the Thread ID is appended to the file name provided.

TraceLevel:
TraceLevel specifies the level of tracing in ODE.NET.
The valid values for TraceLevel are:
0 = None
1 = Entry and exit information

TraceOption
TraceOption specifies whether to log trace information in single or multiple files for different threads. If a single trace file is specified, the file name specified in TraceFileName is used. If the multiple trace files option is requested, a Thread ID is appended to the file name provided to create a trace file for each thread.

The valid values for TraceOption are:
0 = Single trace file
1 = Multiple trace files

.NET runtime version compatibility

.NET stored procedures built with Visual Studio .NET 2003 should use ODP.NET 1.x (e.g. 1.102.2.20) and .NET stored procedures built with Visual Studio 2005 should use ODP.NET 2.x (e.g. 2.102.2.20).

While debugging .NET Procedure/Function, utilizing the "Run" Option on Oracle Explorer causes hang

When attaching to the extproc.exe and debugging a .NET stored procedure (see documentation), avoid using the "Run" context menu option for the procedure or function in Oracle Explorer (part of the Oracle Developer Tools for Visual Studio .NET). This will result in a hang of Visual Studio and a loss of work. Alternately, either call the procedure or function from the Query Window via SQL, or open a new Visual Studio .NET instance and use the "Run" menu option from there.

Manually Starting Extproc Agent

Rather than relying on the provided service, the multi-threaded Extproc agent (extproc.exe) can also be started and shutdown using the agtctl.exe utility using the syntax

agtctl startup extproc CLRExtProc

agtctl shutdown immediate CLRExtProc

Individual agtctl.exe commands will then be needed to be used to set max_dispatchers, max_threads and max_sessions parameters. Please refer to the Oracle Database Heterogeneous Connectivity Administrator's Guide for further information.

Use of DBLink is not supported with context connection

DB links may not be used with the context connection (context connection is the connection inherited from the caller of the stored procedure or function).

Re-deploying assemblies referenced by a .NET stored procedure or function

The multi-threaded extproc agent (extproc.exe) needs to be stopped to re-deploy assemblies referenced by a .NET stored procedure or function. This is typically achieved by stopping and restarting the Oracle<HomeName>ClrAgnt service.

XML Save Functionality

XML Save functionality is not supported in this release.

Statement Caching Functionality with context connection

Statement Caching functionality is disabled with in stored procedures using the context connection.