Oracle® Data Provider for .NET Developer's Guide 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. iii Contents 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 iv 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-2 Connection String Attributes 3-2 Connection Pooling . 3-3 Operating System Authentication . 3-5 Privileged Connections 3-5 Password Expiration 3-6 Proxy Authentication 3-7 Transparent Application Failover (TAF) Callback Support . 3-7 ODP.NET Types Overview 3-9 Obtaining Data From an OracleDataReader . 3-11 Typed OracleDataReader Accessors 3-11 .NET Type Accessors 3-11 ODP.NET Type Accessors 3-13 Obtaining LONG and LONG RAW Data 3-14 Obtaining LOB Data . 3-15 Methods Supported or Not Supported for InitialLOBFetchSize 3-15 LOB Data Fetching Considerations . 3-16 Performance 3-17 Controlling the Number of Rows Fetched in One Server Round-Trip . 3-17 Use of FetchSize . 3-17 Fine-Tuning FetchSize 3-18 Using the RowSize Property 3-18 OracleCommand Object 3-19 Transaction 3-19 Parameter Binding 3-19 Datatypes BINARY_FLOAT and BINARY_DOUBLE . 3-20 OracleDbType Enumeration Type 3-21 Inference of DbType, OracleDbType, and .NET Types . 3-22 v PL/SQL Associative Array 3-26 Array Binding 3-29 PL/SQL REF CURSOR and OracleRefCursor . 3-32 Obtaining an OracleRefCursor . 3-33 Obtaining a REF CURSOR 3-33 Populating an OracleDataReader from a REF CURSOR 3-33 Populating the DataSet From a REF CURSOR . 3-34 Populating an OracleRefCursor From a REF CURSOR 3-34 Updating a DataSet Obtained From a REF CURSOR . 3-34 Behavior of ExecuteScalar Method for REF CURSOR 3-35 LOB Support 3-35 Updating LOBs Using a DataSet 3-37 Updating LOBs Using OracleCommand and OracleParameter 3-37 Updating LOBs Using ODP.NET LOB Objects 3-38 Temporary LOBs 3-38 Globalization Support . 3-39 Globalization Settings 3-39 Client Globalization Settings . 3-39 Session Globalization Settings 3-40 Thread-Based Globalization Settings . 3-41 Globalization-Sensitive Operations . 3-42 Operations Dependent on Client Computer's Globalization Settings . 3-42 Operations Dependent on Thread Globalization Settings 3-42 Operations Sensitive to Session Globalization Parameters . 3-42 Guaranteeing Uniqueness in Updating DataSet to Database . 3-43 What Constitutes Uniqueness in DataRows? . 3-44 Configuring PrimaryKey and Constraints Properties 3-45 Updating Without PrimaryKey and Constraints Configuration . 3-46 OracleDataAdapter Safe Type Mapping 3-46 Potential Data Loss . 3-47 SafeMapping Property . 3-48 Using Safe Type Mapping . 3-48 vi OracleDataAdapter Requery Property 3-49 Debug Tracing . 3-50 Registry Settings for Tracing Calls . 3-50 TraceFileName . 3-50 TraceLevel . 3-51 TraceOption 3-51 ODP.NET XML Support 3-51 Supported XML Features . 3-52 OracleXmlType and Connection Dependency . 3-53 Updating XMLType Data in the Database Server . 3-54 Updating with DataSet, OracleDataAdapter, and OracleCommandBuilder . 3-54 Updating with OracleCommand and OracleParameter 3-55 Updating XML Data in OracleXmlType 3-56 Special Characters in XML 3-56 Retrieving Query Result Set as XML . 3-57 Handling Date and Time Format . 3-57 Special Characters in Column Data 3-58 Special Characters In Table or View Name . 3-59 Case-Sensitivity in Column Name to XML Element Name Mapping . 3-60 Column Name to XML Element Name Mapping . 3-60 Object-Relational Data 3-62 NULL values 3-63 Data Manipulation Using XML 3-63 Handling of Date and Time Format 3-63 Saving Changes Using XML 3-64 Special Characters in Column Data 3-64 Special Characters in Table or View Name 3-65 Case-Sensitivity in XML Element Name to Column Name Mapping . 3-65 XML Element Name to Column Name Mapping . 3-66 Object-Relational Data 3-68 Multiple Tables 3-68 Commits 3-68 vii 4 Oracle.DataAccess.Client Namespace Overview of Oracle Data Provider Classes 4-2 Oracle Data Provider Classes . 4-4 OracleCommand Class 4-5 OracleCommand Members 4-7 OracleCommand Constructors 4-10 OracleCommand Static Methods 4-12 OracleCommand Properties 4-12 OracleCommand Public Methods . 4-28 OracleCommandBuilder Class . 4-41 OracleCommandBuilder Members . 4-44 OracleCommandBuilder Constructors 4-46 OracleCommandBuilder Static Methods . 4-47 OracleCommandBuilder Properties . 4-48 OracleCommandBuilder Public Methods 4-49 OracleCommandBuilder Events . 4-53 OracleCommandBuilder Event Delegates . 4-53 OracleConnection Class . 4-54 OracleConnection Members . 4-55 OracleConnection Constructors . 4-58 OracleConnection Static Methods . 4-60 OracleConnection Properties . 4-60 OracleConnection Public Methods . 4-70 OracleConnection Events . 4-81 OracleConnection Event Delegates 4-84 OracleDataAdapter Class . 4-86 OracleDataAdapter Members . 4-88 OracleDataAdapter Constructors 4-91 OracleDataAdapter Static Methods 4-94 OracleDataAdapter Properties 4-95 OracleDataAdapter Public Methods 4-101 OracleDataAdapter Events 4-107 OracleDataAdapter Event Delegates 4-111 viii OracleDataReader Class 4-113 OracleDataReader Members 4-116 OracleDataReader Static Methods 4-120 OracleDataReader Properties 4-120 OracleDataReader Public Methods . 4-129 OracleError Class 4-182 OracleError Members . 4-183 OracleError Static Methods 4-184 OracleError Properties 4-184 OracleError Methods 4-188 OracleErrorCollection Class 4-190 OracleErrorCollection Members . 4-191 OracleErrorCollection Static Methods 4-192 OracleErrorCollection Properties 4-192 OracleErrorCollection Public Methods 4-193 OracleException Class . 4-194 OracleException Members . 4-195 OracleException Static Methods 4-197 OracleException Properties 4-197 OracleException Methods 4-201 OracleFailoverEventArgs Class 4-204 OracleFailoverEventArgs Members 4-205 OracleFailoverEventArgs Static Methods 4-206 OracleFailoverEventArgs Properties 4-207 OracleFailoverEventArgs Public Methods 4-208 OracleFailoverEventHandler Delegate 4-209 OracleGlobalization Class . 4-212 OracleGlobalization Members . 4-213 OracleGlobalization Static Methods . 4-215 OracleGlobalization Properties . 4-222 OracleGlobalization Public Methods 4-234 OracleInfoMessageEventArgs Class 4-237 OracleInfoMessageEventArgs Members 4-238 OracleInfoMessageEventArgs Static Methods 4-239 ix OracleInfoMessageEventArgs Properties 4-240 OracleInfoMessageEventArgs Public Methods 4-241 OracleInfoMessageEventHandler Delegate 4-243 OracleParameter Class . 4-244 OracleParameter Members 4-245 OracleParameter Constructors 4-247 OracleParameter Static Methods . 4-261 OracleParameter Properties . 4-261 OracleParameter Public Methods . 4-278 OracleParameterCollection Class . 4-281 OracleParameterCollection Members 4-282 OracleParameterCollection Static Methods . 4-284 OracleParameterCollection Properties . 4-284 OracleParameterCollection Public Methods . 4-287 OracleRowUpdatedEventHandler Delegate 4-309 OracleRowUpdatedEventArgs Class 4-310 OracleRowUpdatedEventArgs Members 4-311 OracleRowUpdatedEventArgs Constructor . 4-312 OracleRowUpdatedEventArgs Static Methods 4-313 OracleRowUpdatedEventArgs Properties 4-313 OracleRowUpdatedEventArgs Public Methods . 4-315 OracleRowUpdatingEventArgs Class . 4-316 OracleRowUpdatingEventArgs Members . 4-317 OracleRowUpdatingEventArgs Constructor 4-318 OracleRowUpdatingEventArgs Static Methods . 4-319 OracleRowUpdatingEventArgs Properties . 4-319 OracleRowUpdatingEventArgs Public Methods . 4-320 OracleRowUpdatingEventHandler Delegate . 4-322 OracleTransaction Class 4-323 OracleTransaction Members 4-325 OracleTransaction Static Methods 4-326 OracleTransaction Properties 4-326 OracleTransaction Public Methods . 4-328 x OracleXmlQueryProperties Class . 4-336 OracleXmlQueryProperties Members 4-338 OracleXmlQueryProperties Constructor 4-339 OracleXmlQueryProperties Properties . 4-340 OracleXmlQueryProperties Public Methods . 4-344 OracleXmlSaveProperties Class 4-345 OracleXmlSaveProperties Members . 4-348 OracleXmlSaveProperties Constructor . 4-350 OracleXmlSaveProperties Properties 4-350 OracleXmlSaveProperties Public Methods 4-355 Oracle Data Provider Enumerations . 4-356 FailoverEvent Enumeration 4-357 FailoverReturnCode Enumeration . 4-358 FailoverType Enumeration . 4-359 OracleCollectionType Enumeration 4-360 OracleDbType Enumeration . 4-361 OracleParameterStatus Enumeration 4-363 OracleXmlCommandType 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-3 OracleBinary Structure . 5-4 OracleBinary Members . 5-5 OracleBinary Constructor . 5-8 OracleBinary Static Fields . 5-8 OracleBinary Static Methods . 5-9 OracleBinary Static Operators . 5-15 OracleBinary Static Type Conversion Operators 5-22 OracleBinary Properties 5-23 OracleBinary Instance Methods 5-26 OracleDate Structure 5-31 OracleDate Members . 5-32 [...]... (ODP.NET), an implementation of a data provider for the Oracle database This chapter contains these topics: I Overview of Oracle Data Provider for NET (ODP.NET) I ODP.NET Assembly I Using ODP.NET in a Simple Application Introducing Oracle Data Provider for NET 1-1 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)... Oracle Data Provider for NET xviii Glossary Defines terms used in this document Related Documentation For more information, see these Oracle resources: I Oracle Database Installation Guide for Windows I Oracle Database Release Notes for Windows I Oracle Database Platform Guide for Windows I Oracle Database Administrator's Guide I Oracle Database Application Developer's Guide - Large Objects I Oracle Database... features in Oracle Data Provider for NET: I New Features in Oracle Data Provider for NET Release 10.1 I New Features in Oracle Data Provider for NET Release 9.2.0.4 xxvii New Features in Oracle Data Provider for NET Release 10.1 Oracle Data Provider for NET release 10.1 includes the following: I Support for Oracle Grids ODP.NET is grid-enabled, allowing developers to take advantage of Oracle database... 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. .. generation for the OracleDataAdapter when updates are made to the database OracleConnection Class 1-2 Description An OracleConnection object represents a connection to an Oracle database Oracle Data Provider for NET Developer’s Guide ODP.NET Assembly Table 1–1 Oracle. DataAccess.Client Classes(Cont.) Class Description OracleDataAdapter Class An OracleDataAdapter object represents a data provider object... Database New Features I Oracle Database Concepts I Oracle Database Reference I Oracle Database SQL Reference I Oracle Net Services Administrator's Guide I Oracle Net Services Reference Guide I Oracle Services for Microsoft Transaction Server Developer's Guide I Oracle Real Application Clusters Quick Start I Oracle Database Globalization Support Guide I Oracle XML DB Developer's Guide I Oracle XML Developer's... 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... OracleParameter object represents a parameter for an OracleCommand OracleParameterCollection Class An OracleParameterCollection object represents a collection of OracleParameters Introducing Oracle Data Provider for NET 1-3 ODP.NET Assembly Table 1–1 Oracle. DataAccess.Client Classes(Cont.) Class OracleRowUpdatedEventArgs Class The OracleRowUpdatedEventArgs object provides event data for the OracleDataAdapter.RowUpdated... 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 Class OracleCommand Class An OracleCommand object represents a SQL command, a stored procedure, or a table name OracleCommandBuilder Class An OracleCommandBuilder... Support for schema-based XMLType in the database ODP.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: I XML support in ODP.NET With XML support, ODP.NET can now: I I I Store XML data natively in the database server as the Oracle . resources: ■ Oracle Database Installation Guide for Windows ■ Oracle Database Release Notes for Windows ■ Oracle Database Platform Guide for Windows ■ Oracle Database. 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