Oracle Data Provider for .NET Developer''''s Guide

xxviii Volume 1 1 Introducing Oracle Data Provider for .NET Overview of Oracle Data Provider for .NET ODP.NET.... Oracle Data Provider for .NET Developer’s Guide is intended for develope

10g Release 1 (10.1)

Part No B10117-01

December 2003

Oracle Data Provider for NET Developer’s Guide, 10g Release 1 (10.1)

Part No B10117-01

Copyright © 2002, 2003 Oracle Corporation All rights reserved.

Primary Author: Janis Greenberg

Contributing Authors: Riaz Ahmed, Kiminari Akiyama, Steven Caminez, Naveen Doraiswamy, Neeraj Gupta, Sinclair Hsu, Alex Keh, Arnold Poon, Chithra Ramamurthy, Ashish Shah, Martha Woo

The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws Reverse engineering, disassembly or decompilation of the Programs, except to the extent required

to obtain interoperability with other independently created software or as specified by law, is prohibited The information contained in this document is subject to change without notice If you find any problems

in the documentation, please report them to us in writing Oracle Corporation does not warrant that this document is error-free Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.

If the Programs are delivered to the U.S Government or anyone licensing or using the programs on behalf of the U.S Government, the following notice is applicable:

Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement

Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987) Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs

Oracle is a registered trademark, and Oracle9i, Oracle8i, Oracle8, Oracle Store, SQL*Plus, and PL/SQL

are trademarks or registered trademarks of Oracle Corporation Other names may be trademarks of their respective owners

Send Us Your Comments xv

Preface xvii

Audience xviii

Organization xviii

Related Documentation xix

Conventions xx

Documentation Accessibility xxv

What's New in Oracle Data Provider for NET? xxvii

New Features in Oracle Data Provider for NET Release 10.1 xxviii

New Features in Oracle Data Provider for NET Release 9.2.0.4 xxviii

Volume 1

1 Introducing Oracle Data Provider for NET

Overview of Oracle Data Provider for NET (ODP.NET) 1-2

ODP.NET Assembly 1-2 Oracle.DataAccess.Client Classes and Enumerations 1-2 Oracle.DataAccess.Types Classes and Structures 1-6

Using ODP.NET in a Simple Application 1-8

2 Installing and Configuring

System Requirements 2-2

Installing Oracle Data Provider for NET 2-3

File Locations 2-3

3 Features of Oracle Data Provider for NET

Connecting to the Oracle Database 3-2Connection String Attributes 3-2Connection Pooling 3-3Operating System Authentication 3-5Privileged Connections 3-5Password Expiration 3-6Proxy Authentication 3-7Transparent Application Failover (TAF) Callback Support 3-7

ODP.NET Types Overview 3-9

Obtaining Data From an OracleDataReader 3-11Typed OracleDataReader Accessors 3-11.NET Type Accessors 3-11ODP.NET Type Accessors 3-13Obtaining LONG and LONG RAW Data 3-14Obtaining LOB Data 3-15Methods Supported or Not Supported for InitialLOBFetchSize 3-15LOB Data Fetching Considerations 3-16Performance 3-17Controlling the Number of Rows Fetched in One Server Round-Trip 3-17Use of FetchSize 3-17Fine-Tuning FetchSize 3-18Using the RowSize Property 3-18

OracleCommand Object 3-19Transaction 3-19Parameter Binding 3-19Datatypes BINARY_FLOAT and BINARY_DOUBLE 3-20OracleDbType Enumeration Type 3-21Inference of DbType, OracleDbType, and NET Types 3-22

PL/SQL REF CURSOR and OracleRefCursor 3-32Obtaining an OracleRefCursor 3-33Obtaining a REF CURSOR 3-33Populating an OracleDataReader from a REF CURSOR 3-33Populating the DataSet From a REF CURSOR 3-34Populating an OracleRefCursor From a REF CURSOR 3-34Updating a DataSet Obtained From a REF CURSOR 3-34Behavior of ExecuteScalar Method for REF CURSOR 3-35

LOB Support 3-35Updating LOBs Using a DataSet 3-37Updating LOBs Using OracleCommand and OracleParameter 3-37Updating LOBs Using ODP.NET LOB Objects 3-38Temporary LOBs 3-38

Globalization Support 3-39Globalization Settings 3-39Client Globalization Settings 3-39Session Globalization Settings 3-40Thread-Based Globalization Settings 3-41Globalization-Sensitive Operations 3-42Operations Dependent on Client Computer's Globalization Settings 3-42Operations Dependent on Thread Globalization Settings 3-42Operations Sensitive to Session Globalization Parameters 3-42

Guaranteeing Uniqueness in Updating DataSet to Database 3-43What Constitutes Uniqueness in DataRows? 3-44Configuring PrimaryKey and Constraints Properties 3-45Updating Without PrimaryKey and Constraints Configuration 3-46

OracleDataAdapter Safe Type Mapping 3-46Potential Data Loss 3-47SafeMapping Property 3-48Using Safe Type Mapping 3-48

OracleDataAdapter Requery Property 3-49

Debug Tracing 3-50Registry Settings for Tracing Calls 3-50TraceFileName 3-50TraceLevel 3-51TraceOption 3-51

ODP.NET XML Support 3-51Supported XML Features 3-52OracleXmlType and Connection Dependency 3-53Updating XMLType Data in the Database Server 3-54Updating with DataSet, OracleDataAdapter, and OracleCommandBuilder 3-54Updating with OracleCommand and OracleParameter 3-55Updating XML Data in OracleXmlType 3-56Special Characters in XML 3-56Retrieving Query Result Set as XML 3-57Handling Date and Time Format 3-57Special Characters in Column Data 3-58Special Characters In Table or View Name 3-59Case-Sensitivity in Column Name to XML Element Name Mapping 3-60Column Name to XML Element Name Mapping 3-60Object-Relational Data 3-62NULL values 3-63Data Manipulation Using XML 3-63Handling of Date and Time Format 3-63Saving Changes Using XML 3-64Special Characters in Column Data 3-64Special Characters in Table or View Name 3-65Case-Sensitivity in XML Element Name to Column Name Mapping 3-65XML Element Name to Column Name Mapping 3-66Object-Relational Data 3-68Multiple Tables 3-68Commits 3-68

Oracle Data Provider Classes 4-4OracleCommand Class 4-5OracleCommand Members 4-7OracleCommand Constructors 4-10OracleCommand Static Methods 4-12OracleCommand Properties 4-12OracleCommand Public Methods 4-28OracleCommandBuilder Class 4-41OracleCommandBuilder Members 4-44OracleCommandBuilder Constructors 4-46OracleCommandBuilder Static Methods 4-47OracleCommandBuilder Properties 4-48OracleCommandBuilder Public Methods 4-49OracleCommandBuilder Events 4-53OracleCommandBuilder Event Delegates 4-53OracleConnection Class 4-54OracleConnection Members 4-55OracleConnection Constructors 4-58OracleConnection Static Methods 4-60OracleConnection Properties 4-60OracleConnection Public Methods 4-70OracleConnection Events 4-81OracleConnection Event Delegates 4-84OracleDataAdapter Class 4-86OracleDataAdapter Members 4-88OracleDataAdapter Constructors 4-91OracleDataAdapter Static Methods 4-94OracleDataAdapter Properties 4-95OracleDataAdapter Public Methods 4-101OracleDataAdapter Events 4-107OracleDataAdapter Event Delegates 4-111

OracleDataReader Class 4-113OracleDataReader Members 4-116OracleDataReader Static Methods 4-120OracleDataReader Properties 4-120OracleDataReader Public Methods 4-129OracleError Class 4-182OracleError Members 4-183OracleError Static Methods 4-184OracleError Properties 4-184OracleError Methods 4-188OracleErrorCollection Class 4-190OracleErrorCollection Members 4-191OracleErrorCollection Static Methods 4-192OracleErrorCollection Properties 4-192OracleErrorCollection Public Methods 4-193OracleException Class 4-194OracleException Members 4-195OracleException Static Methods 4-197OracleException Properties 4-197OracleException Methods 4-201OracleFailoverEventArgs Class 4-204OracleFailoverEventArgs Members 4-205OracleFailoverEventArgs Static Methods 4-206OracleFailoverEventArgs Properties 4-207OracleFailoverEventArgs Public Methods 4-208OracleFailoverEventHandler Delegate 4-209OracleGlobalization Class 4-212OracleGlobalization Members 4-213OracleGlobalization Static Methods 4-215OracleGlobalization Properties 4-222OracleGlobalization Public Methods 4-234OracleInfoMessageEventArgs Class 4-237OracleInfoMessageEventArgs Members 4-238OracleInfoMessageEventArgs Static Methods 4-239

OracleInfoMessageEventHandler Delegate 4-243OracleParameter Class 4-244OracleParameter Members 4-245OracleParameter Constructors 4-247OracleParameter Static Methods 4-261OracleParameter Properties 4-261OracleParameter Public Methods 4-278OracleParameterCollection Class 4-281OracleParameterCollection Members 4-282OracleParameterCollection Static Methods 4-284OracleParameterCollection Properties 4-284OracleParameterCollection Public Methods 4-287OracleRowUpdatedEventHandler Delegate 4-309OracleRowUpdatedEventArgs Class 4-310OracleRowUpdatedEventArgs Members 4-311OracleRowUpdatedEventArgs Constructor 4-312OracleRowUpdatedEventArgs Static Methods 4-313OracleRowUpdatedEventArgs Properties 4-313OracleRowUpdatedEventArgs Public Methods 4-315OracleRowUpdatingEventArgs Class 4-316OracleRowUpdatingEventArgs Members 4-317OracleRowUpdatingEventArgs Constructor 4-318OracleRowUpdatingEventArgs Static Methods 4-319OracleRowUpdatingEventArgs Properties 4-319OracleRowUpdatingEventArgs Public Methods 4-320OracleRowUpdatingEventHandler Delegate 4-322OracleTransaction Class 4-323OracleTransaction Members 4-325OracleTransaction Static Methods 4-326OracleTransaction Properties 4-326OracleTransaction Public Methods 4-328

OracleXmlQueryProperties Class 4-336OracleXmlQueryProperties Members 4-338OracleXmlQueryProperties Constructor 4-339OracleXmlQueryProperties Properties 4-340OracleXmlQueryProperties Public Methods 4-344OracleXmlSaveProperties Class 4-345OracleXmlSaveProperties Members 4-348OracleXmlSaveProperties Constructor 4-350OracleXmlSaveProperties Properties 4-350OracleXmlSaveProperties Public Methods 4-355

Oracle Data Provider Enumerations 4-356FailoverEvent Enumeration 4-357FailoverReturnCode Enumeration 4-358FailoverType Enumeration 4-359OracleCollectionType Enumeration 4-360OracleDbType Enumeration 4-361OracleParameterStatus Enumeration 4-363OracleXmlCommandType Enumeration 4-364

Volume 2

5 Oracle.DataAccess.Types Namespace (ODP.NET Types)

Overview of ODP.NET Types 5-2

ODP.NET Type Structures 5-3OracleBinary Structure 5-4OracleBinary Members 5-5OracleBinary Constructor 5-8OracleBinary Static Fields 5-8OracleBinary Static Methods 5-9OracleBinary Static Operators 5-15OracleBinary Static Type Conversion Operators 5-22OracleBinary Properties 5-23OracleBinary Instance Methods 5-26OracleDate Structure 5-31OracleDate Members 5-32

OracleDate Static Methods 5-42OracleDate Static Operators 5-50OracleDate Static Type Conversions 5-55OracleDate Properties 5-60OracleDate Methods 5-65OracleDecimal Structure 5-71OracleDecimal Members 5-72OracleDecimal Constructors 5-79OracleDecimal Static Fields 5-86OracleDecimal Static (Comparison) Methods 5-90OracleDecimal Static (Manipulation) Methods 5-96OracleDecimal Static (Logarithmic) Methods 5-113OracleDecimal Static (Trigonometric) Methods 5-120OracleDecimal Static (Comparison) Operators 5-127OracleDecimal Static Operators (Conversion from NET Type to OracleDecimal) 5-137OracleDecimal Static Operators (Conversion from OracleDecimal to NET) 5-142OracleDecimal Properties 5-147OracleDecimal Instance Methods 5-152OracleIntervalDS Structure 5-161OracleIntervalDS Members 5-162OracleIntervalDS Constructors 5-166OracleIntervalDS Static Fields 5-172OracleIntervalDS Static Methods 5-174OracleIntervalDS Static Operators 5-182OracleIntervalDS Type Conversions 5-192OracleIntervalDS Properties 5-195OracleIntervalDS Methods 5-200OracleIntervalYM Structure 5-205OracleIntervalYM Members 5-206OracleIntervalYM Constructors 5-210OracleIntervalYM Static Fields 5-214OracleIntervalYM Static Methods 5-216

OracleIntervalYM Type Conversions 5-233OracleIntervalYM Properties 5-236OracleIntervalYM Methods 5-240OracleString Structure 5-244OracleString Members 5-245OracleString Constructors 5-249OracleString Static Fields 5-254OracleString Static Methods 5-255OracleString Static Operators 5-262OracleString Type Conversions 5-268OracleString Properties 5-270OracleString Methods 5-273OracleTimeStamp Structure 5-279OracleTimeStamp Members 5-280OracleTimeStamp Constructors 5-285OracleTimeStamp Static Fields 5-293OracleTimeStamp Static Methods 5-294OracleTimeStamp Static Operators 5-303OracleTimeStamp Static Type Conversions 5-315OracleTimeStamp Properties 5-321OracleTimeStamp Methods 5-328OracleTimeStampLTZ Structure 5-343OracleTimeStampLTZ Members 5-344OracleTimeStampLTZ Constructors 5-350OracleTimeStampLTZ Static Fields 5-358OracleTimeStampLTZ Static Methods 5-360OracleTimeStampLTZ Static Type Operators 5-370OracleTimeStampLTZ Static Type Conversions 5-382OracleTimeStampLTZ Properties 5-388OracleTimeStampLTZ Methods 5-395OracleTimeStampTZ Structure 5-410OracleTimeStampTZ Members 5-411OracleTimeStampTZ Constructors 5-417OracleTimeStampTZ Static Fields 5-432OracleTimeStampTZ Static Methods 5-434

OracleTimeStampTZ Properties 5-462OracleTimeStampTZ Methods 5-469

ODP.NET Type Exceptions 5-486OracleTypeException Class 5-487OracleTypeException Members 5-487OracleTypeException Constructors 5-489OracleTypeException Static Methods 5-491OracleTypeException Properties 5-491OracleTypeException Methods 5-492OracleNullValueException Class 5-494OracleNullValueException Members 5-495OracleNullValueException Constructors 5-496OracleNullValueException Static Methods 5-497OracleNullValueException Properties 5-498OracleNullValueException Methods 5-498OracleTruncateException Class 5-500OracleTruncateException Members 5-501OracleTruncateException Constructors 5-502OracleTruncateException Static Methods 5-503OracleTruncateException Properties 5-504OracleTruncateException Methods 5-504

ODP.NET Type Objects 5-506OracleBFile Class 5-507OracleBFile Members 5-508OracleBFile Constructors 5-511OracleBFile Static Fields 5-513OracleBFile Static Methods 5-514OracleBFile Instance Properties 5-515OracleBFile Instance Methods 5-523OracleBlob Class 5-543OracleBlob Members 5-544OracleBlob Constructors 5-547

OracleBlob Static Methods 5-550OracleBlob Instance Properties 5-551OracleBlob Instance Methods 5-557OracleClob Class 5-580OracleClob Members 5-581OracleClob Constructors 5-585OracleClob Static Fields 5-587OracleClob Static Methods 5-588OracleClob Instance Properties 5-588OracleClob Instance Methods 5-595OracleRefCursor Class 5-624OracleRefCursor Members 5-625OracleRefCursor Static Methods 5-626OracleRefCursor Properties 5-627OracleRefCursor Instance Methods 5-628OracleXmlStream Class 5-630OracleXmlStream Members 5-631OracleXmlStream Constructor 5-633OracleXmlStream Static Methods 5-633OracleXmlStream Instance Properties 5-634OracleXmlStream Instance Methods 5-638OracleXmlType Class 5-646OracleXmlType Members 5-647OracleXmlType Constructors 5-649OracleXmlType Static Methods 5-653OracleXmlType Instance Properties 5-653OracleXmlType Instance Methods 5-659

Glossary

Index

Oracle Data Provider for NET Developer’s Guide, 10g Release 1 (10.1)

Part No B10117-01

Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this publication Your input is an important part of the information used for revision

■ Did you find any errors?

■ Is the information clearly presented?

■ Do you need more information? If so, where?

■ Are the examples correct? Do you need more examples?

■ What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the title and part number of the documentation and the chapter, section, and page number (if available) You can send comments to us in the following ways:

■ Electronic mail: ntdoc_us@oracle.com

■ FAX: 650) 506-7365 Attn: Oracle Database for Windows Documentation

■ Postal service:

Oracle Corporation

Oracle Database for Windows Documentation Manager

500 Oracle Parkway, Mailstop 1op6

This document is your primary source of introductory, installation, postinstallation configuration, and usage information for Oracle Data Provider for NET

Oracle Data Provider for NET is an implementation of the Microsoft ADO.NET interface

This document describes the features of Oracle Database for Windows that apply to the Windows NT Server, Windows 2000, Windows XP, and Windows Server 2003 operating systems

This preface contains these topics:

Oracle Data Provider for NET Developer’s Guide is intended for developers who are

developing applications to access an Oracle database using Oracle Data Provider for NET This documentation is also valuable to systems analysts, project managers, and others interested in the development of database applications

To use this document, you must be familiar with Microsoft NET Framework classes and ADO.NET and have a working knowledge of application programing using Microsoft C#, Visual Basic, or C++

Users should also be familiar with the use of Structured Query Language (SQL) to access information in relational database systems

Organization

This document contains:

Chapter 1, "Introducing Oracle Data Provider for NET"

Provides an overview of Oracle Data Provider for NET

Chapter 2, "Installing and Configuring"

Describes how to install Oracle Data Provider for NET and provides system requirements

Read this chapter before installing or using Oracle Data Provider for NET.

Chapter 3, "Features of Oracle Data Provider for NET"

Describes provider-specific features of Oracle Data Provider for NET, including Oracle XML Database

Chapter 4, "Oracle.DataAccess.Client Namespace"

Describes the classes and public methods Oracle Data Provider for NET exposes for ADO.NET programmers

Chapter 5, "Oracle.DataAccess.Types Namespace (ODP.NET Types)"

Describes the type structures and objects provided by Oracle Data Provider for NET

Related Documentation

For more information, see these Oracle resources:

■ Oracle Database Installation Guide for Windows

■ Oracle Database Release Notes for Windows

■ Oracle Database Platform Guide for Windows

■ Oracle Database Administrator's Guide

■ Oracle Database Application Developer's Guide - Large Objects

■ Oracle Database New Features

■ Oracle Database Concepts

■ Oracle Database Reference

■ Oracle Database SQL Reference

■ Oracle Net Services Administrator's Guide

■ Oracle Net Services Reference Guide

■ Oracle Services for Microsoft Transaction Server Developer's Guide

■ Oracle Real Application Clusters Quick Start

■ Oracle Database Globalization Support Guide

■ Oracle XML DB Developer's Guide

■ Oracle XML Developer's Kit Programmer's Guide For information about Oracle error messages, see Oracle Database Error Messages

Oracle error message documentation is available only in HTML If you only have access to the Oracle Documentation CD, you can browse the error messages by range Once you find the specific range, use your browser's "find in page" feature to locate the specific message When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation

Many of the examples in this book use the sample schemas of the seed database,

which is installed by default when you install Oracle Refer to Oracle Database Sample Schemas for information on how these schemas were created and how you

can use them yourself

Printed documentation is available for sale in the Oracle Store athttp://oraclestore.oracle.com/

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN) You must register online before using OTN; registration is free and can be done at

■ Conventions in Code Examples

■ Conventions for Windows Operating Systems

The following table describes those conventions and provides examples of their use.

Bold Bold typeface indicates terms that are

defined in the text or terms that appear in

Oracle Database Concepts

Ensure that the recovery catalog and target

database do not reside on the same disk.

You can specify this clause only for a NUMBER column

You can back up the database by using the BACKUP command

Query the TABLE_NAME column in the USER_TABLES data dictionary view

Use the DBMS_STATS.GENERATE_STATSprocedure

Note: Some programmatic elements use a mixture of UPPERCASE and lowercase

Enter these elements as shown

Enter sqlplus to open SQL*Plus

The password is specified in the orapwd file.Back up the datafiles and control files in the /disk1/oracle/dbs directory

The department_id, department_name, and location_id columns are in the hr.departments table

Set the QUERY_REWRITE_ENABLED initialization parameter to true

You can specify the parallel_clause.

Run Uold_release.SQL where old_

release refers to the release you installed

prior to upgrading

Conventions in Code Examples

Code examples illustrate SQL, PL/SQL, SQL*Plus, or other command-line statements They are displayed in a monospace (fixed-width) font and separated from normal text as shown in this example:

SELECT username FROM dba_users WHERE username = 'MIGRATE';

The following table describes typographic conventions used in code examples and provides examples of their use

[ ] Brackets enclose one or more optional

items Do not enter the brackets

DECIMAL (digits [ , precision ])

{ } Braces enclose two or more items, one of

which is required Do not enter the braces

{ENABLE | DISABLE}

| A vertical bar represents a choice of two

or more options within brackets or braces

Enter one of the options Do not enter the vertical bar

{ENABLE | DISABLE}

[COMPRESS | NOCOMPRESS]

Horizontal ellipsis points indicate either:

■ That we have omitted parts of the code that are not directly related to the example

■ That you can repeat a portion of the code

CREATE TABLE AS subquery;SELECT col1, col2, , coln FROM employees;

SQL> SELECT NAME FROM V$DATAFILE;

NAME -/fsl/dbs/tbs_01.dbf

/fs1/dbs/tbs_02.dbf

/fsl/dbs/tbs_09.dbf

9 rows selected

Other notation You must enter symbols other than

brackets, braces, vertical bars, and ellipsis points as shown

acctbal NUMBER(11,2);

acct CONSTANT NUMBER(4) := 3;

Conventions for Windows Operating Systems

The following table describes conventions for Windows operating systems and provides examples of their use

variables for which you must supply particular values

DB_NAME = database_name

UPPERCASE Uppercase typeface indicates elements

supplied by the system We show these terms in uppercase in order to distinguish them from terms you define Unless terms appear in brackets, enter them in the order and with the spelling shown

However, because these terms are not case sensitive, you can enter them in lowercase

SELECT last_name, employee_id FROM employees;

SELECT * FROM USER_TABLES;

DROP TABLE hr.employees;

lowercase Lowercase typeface indicates

programmatic elements that you supply

For example, lowercase indicates names

of tables, columns, or files

Note: Some programmatic elements use a mixture of UPPERCASE and lowercase

Enter these elements as shown

SELECT last_name, employee_id FROM employees;

sqlplus hr/hrCREATE USER mjones IDENTIFIED BY ty3MU9;

Choose Start > How to start a program To start the Database Configuration Assistant,

choose Start > Programs > Oracle - HOME_ NAME > Configuration and Migration Tools > Database Configuration Assistant

File and directory

names

File and directory names are not case sensitive The following special characters are not allowed: left angle bracket (<), right angle bracket (>), colon (:), double quotation marks ("), slash (/), pipe (|), and dash (-) The special character backslash (\) is treated as an element separator, even when it appears in quotes

If the file name begins with \\, then Windows assumes it uses the Universal Naming Convention

c:\winnt"\"system32 is the same as C:\WINNT\SYSTEM32

C:\> Represents the Windows command

prompt of the current hard disk drive

The escape character in a command prompt is the caret (^) Your prompt reflects the subdirectory in which you are

working Referred to as the command

prompt in this manual.

C:\oracle\oradata>

Special characters The backslash (\) special character is

sometimes required as an escape character for the double quotation mark (") special character at the Windows command prompt Parentheses and the single quotation mark (') do not require

an escape character Refer to your Windows operating system documentation for more information on escape and special characters

C:\>exp scott/tiger TABLES=emp QUERY=\"WHERE job='SALESMAN' and sal<1600\"

C:\>imp SYSTEM/password FROMUSER=scott TABLES=(emp, dept)

HOME_NAME Represents the Oracle home name The

home name can be up to 16 alphanumeric characters The only special character allowed in the home name is the underscore

C:\> net start OracleHOME_NAMETNSListener

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community To that end, our documentation includes features that make information available to users of assistive technology This documentation is available in HTML format, and contains markup to facilitate access by the disabled community Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers For additional information, visit the Oracle Accessibility Program Web site at

This release complies with Optimal Flexible Architecture (OFA) guidelines

All subdirectories are not under a top

level ORACLE_HOME directory There is a top level directory called ORACLE_BASE

that by default is C:\oracle If you install the latest Oracle release on a computer with no other Oracle software installed, then the default setting for the first Oracle home directory is

C:\oracle\orann , where nn is the

latest release number The Oracle home directory is located directly under

ORACLE_BASE.All directory path examples in this guide follow OFA conventions

Refer to Oracle Database Platform Guide for

Windows for additional information about

OFA compliances and for information about installing Oracle products in non-OFA compliant directories

HOME\rdbms\admin directory

Accessibility of Code Examples in Documentation JAWS, a Windows screen reader, may not always correctly read the code examples in this document The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites

This section describes new features in Oracle Data Provider for NET 10g Release 1

(10.1) and provides pointers to additional information New features information from previous releases is also retained to help those users migrating to the current release

The following sections describe the new features in Oracle Data Provider for NET:

■ New Features in Oracle Data Provider for NET Release 10.1

■ New Features in Oracle Data Provider for NET Release 9.2.0.4

New Features in Oracle Data Provider for NET Release 10.1

Oracle Data Provider for NET release 10.1 includes the following:

■ Support for Oracle GridsODP.NET is grid-enabled, allowing developers to take advantage of Oracle database grid support without having to make changes to their application code

■ Support for BINARY_FLOAT and BINARY_DOUBLE datatypes in the databaseODP.NET supports the new database native types BINARY_FLOAT and BINARY_DOUBLE

■ Support for Multiple HomesODP.NET can be installed in Multiple Oracle Homes

In order to make multiple homes available, some of the ODP.NET files include a version number, and the use of a HOMEID is required.

■ Support for schema-based XMLType in the databaseODP.NET supports the native schema-based XMLType

New Features in Oracle Data Provider for NET Release 9.2.0.4

Oracle Data Provider for NET release 9.2.0.4, which was released on Oracle Technology Network (OTN) included the following:

■ XML support in ODP.NET

With XML support, ODP.NET can now:

■ Store XML data natively in the database server as the Oracle database native type, XMLType

■ Access relational and object-relational data as XML data from an Oracle database instance into Microsoft NET environment, process the XML using Microsoft NET framework

■ Save changes to the database server using XML data

See Also: "Datatypes BINARY_FLOAT and BINARY_DOUBLE"

on page 3-20

See Also: "ODP.NET XML Support" on page 3-51

Index-By Tables) binding

An application can bind an OracleParameter, as a PL/SQL Associative Array, to a PL/SQL stored procedure using OracleParameter properties

■ Support for InitialLOBFetchSize property on OracleCommand and OracleDataReader objects

See Also: "PL/SQL Associative Array" on page 3-26

See Also: "Obtaining LOB Data" on page 3-15

1 Introducing Oracle Data Provider for NET

This chapter introduces Oracle Data Provider for NET (ODP.NET), an

implementation of a data provider for the Oracle database

This chapter contains these topics:

■ Overview of Oracle Data Provider for NET (ODP.NET)

■ ODP.NET Assembly

■ Using ODP.NET in a Simple Application

Overview of Oracle Data Provider for NET (ODP.NET)

Overview of Oracle Data Provider for NET (ODP.NET)

Oracle Data Provider for NET (ODP.NET) is an implementation of a data provider for the Oracle database

ODP.NET uses Oracle native APIs to offer fast and reliable access to Oracle data and features from any NET application ODP.NET also uses and inherits classes and interfaces available in the Microsoft NET Framework Class Library

For programmers using Oracle Provider for OLE DB, ADO (ActiveX Data Objects) provides an automation layer that exposes an easy programming model ADO.NET provides a similar programming model, but without the automation layer, for better performance More importantly, the ADO.NET model allows native providers such

as ODP.NET to expose Oracle-specific features and datatypes

ODP.NET Assembly

Oracle.DataAccess.dllassembly provides two namespaces:

■ The Oracle.DataAccess.Client namespace contains ODP.NET classes and enumerations

■ The Oracle.DataAccess.Types namespace contains the Oracle Data Provider for NET Types (ODP.NET Types)

Oracle.DataAccess.Client Classes and Enumerations

This namespace is the Oracle Data Provider for NET (ODP.NET)

Table 1–1 lists the client classes:

Table 1–1 Oracle.DataAccess.Client Classes

command, a stored procedure, or a table name

provides automatic SQL generation for the OracleDataAdapter when updates are made to the database

connection to an Oracle database

OracleDataAdapter Class An OracleDataAdapter object represents

a data provider object that communicates with the DataSet

forward-only, read-only, in-memory result set

reported by an Oracle database

represents a collection of OracleErrors

exception that is thrown when Oracle Data Provider for NET encounters an error

provides event data for the OracleConnection.Failover event

delegate represents the signature of the method that handles the

OracleConnection.Failover event

to obtain and set the Oracle globalization settings of the session, thread, and local computer (read-only)

delegate represents the signature of the method that handles the

OracleConnection.InfoMessage event

object provides event data for the OracleConnection.InfoMessage event

parameter for an OracleCommand

represents a collection of OracleParameters

Table 1–1 Oracle.DataAccess.Client Classes(Cont.)

ODP.NET Assembly

provides event data for the OracleDataAdapter.RowUpdated event

delegate represents the signature of the method that handles the

OracleDataAdapter.RowUpdated event

object provides event data for the OracleDataAdapter.RowUpdating event

delegate represents the signature of the method that handles the

OracleDataAdapter.RowUpdatingevent

a local transaction

represents the XML properties used by the OracleCommand class when the

XmlCommandType property is Query

represents the XML properties used by the OracleCommand class when the

XmlCommandType property is Insert, Update, or Delete

Table 1–1 Oracle.DataAccess.Client Classes(Cont.)

Table 1–2 lists the client enumerations:

Table 1–2 Oracle.DataAccess.Client Enumerations

used to explicitly specify the state of the failover

are passed back by the application to the ODP.NET provider to request a retry in case

of a failover error or to continue in case of a successful failover

to indicate the type of failover event that was raised

to explicitly specify the OracleDbType of

an OracleParameter

enumeration type indicates whether a NULLvalue is fetched from a column, whether truncation has occurred during the fetch, or whether a NULL value is to be inserted into a database column

specifies the values that are allowed for the OracleXmlCommandType property of the OracleCommand class

ODP.NET Assembly

Oracle.DataAccess.Types Classes and Structures

The Oracle.DataAccess.Types namespace provides classes and structures for Oracle native types that can be used with Oracle Data Provider for NET

Table 1–3 lists the types structures:

Table 1–3 Oracle.DataAccess.Types Structures

OracleBinary Structure The OracleBinary structure represents a

variable-length stream of binary data

datatype

OracleDecimal Structure The OracleDecimal structure represents an Oracle

NUMBER in the database or any Oracle numeric value

OracleIntervalDS Structure The OracleIntervalDS structure represents the Oracle

INTERVAL DAY TO SECOND datatype

OracleIntervalYM Structure The OracleIntervalYM structure represents the Oracle

INTERVALYEARTOMONTH datatype

variable-length stream of characters

OracleTimeStamp Structure The OracleTimeStamp structure represents the Oracle

TimeStamp datatype

OracleTimeStampLTZ Structure The OracleTimeStampLTZ structure represents the

Oracle TIMESTAMP WITH LOCAL TIME ZONE data type

OracleTimeStampTZ Structure The OracleTimeStampTZ structure represents the

Oracle TIMESTAMPWITHTIMEZONE data type

Type Exceptions are thrown only by ODP.NET type structures Table 1–4 lists the type exceptions:

Table 1–5 lists the types classes:

Table 1–4 Oracle.DataAccess.Types Exceptions

OracleTypeException Class The OracleTypeException object is the base

exception class for handling exceptions that occur in the ODP.NET Type classes

OracleNullValueException Class The OracleNullValueException represents an

exception that is thrown when trying to access an ODP.NET Type structure that is null

OracleTruncateException Class The OracleTruncateException class represents an

exception that is thrown when truncation in an ODP.NET Type class occurs

Table 1–5 Oracle.DataAccess.Types Classes

BFILE data It provides methods for performing operations on BFiles

to BLOB data It provides methods for performing operations on BLOBs

data It provides methods for performing operations on CLOBs

Oracle REF CURSOR

OracleXmlStream Class An OracleXmlStream object represents a sequential

read-only stream of XML data stored in an OracleXmlType object

XmlType instance

Using ODP.NET in a Simple Application

Using ODP.NET in a Simple Application

The following is a very simple C# application that connects to an Oracle database and displays its version number before disconnecting

using System;

using Oracle.DataAccess.Client;

class Example {

OracleConnection con;

void Connect() {

con = new OracleConnection();

con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle"; con.Open();

Console.WriteLine("Connected to Oracle" + con.ServerVersion);

} void Close() {

con.Close();

con.Dispose();

} static void Main() {

Example example = new Example();

example.Connect();

example.Close();

} }

Note: Additional samples are provided in the ORACLE_

BASE \ORACLE_HOME\ODP.NET\Samples directory

2 Installing and Configuring

This chapter describes installation and configuration requirements for Oracle Data Provider for NET

This chapter contains these topics:

■ System Requirements

■ Installing Oracle Data Provider for NET

■ File Locations

System Requirements

System Requirements

Oracle Data Provider for NET requires the following:

■ Microsoft NET Framework 1.0 or higher

■ Windows NT, Windows XP, Windows 2000, or Windows Server 2003

■ Access to Oracle8i Database release 3 (8.1.7) or higher

■ Oracle Client release 10.1 or higher and Net Services (included with ODP.NET Software)

■ Applications using OracleXmlStream and OracleXmlType classes with

schema-based XMLType require Oracle Database 10g.

■ For database releases 8.1.7 and 9.0.1 only: To provide XML support, the following OracleCommand methods, require Oracle XML Developer's Kit (Oracle XDK) release 9.2 or higher to be installed on the database Oracle XDK can be downloaded from Oracle Technology Network (OTN)