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

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
xi
OracleDate Constructors .................................................................................................... 5-35
OracleDate Static Fields...................................................................................................... 5-41
OracleDate Static Methods ............................................................................................... 5-42

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

OracleIntervalYM Static Methods................................................................................... 5-216
OracleIntervalYM Static Operators ................................................................................ 5-224
xii
OracleIntervalYM Type Conversions............................................................................. 5-233
OracleIntervalYM Properties ........................................................................................... 5-236
OracleIntervalYM Methods ............................................................................................. 5-240
OracleString Structure.............................................................................................................. 5-244
OracleString Members ...................................................................................................... 5-245
OracleString Constructors................................................................................................ 5-249
OracleString Static Fields.................................................................................................. 5-254
OracleString Static Methods ............................................................................................ 5-255
OracleString Static Operators .......................................................................................... 5-262
OracleString Type Conversions....................................................................................... 5-268
OracleString Properties..................................................................................................... 5-270
OracleString Methods ....................................................................................................... 5-273
OracleTimeStamp Structure.................................................................................................... 5-279
OracleTimeStamp Members ............................................................................................ 5-280
OracleTimeStamp Constructors ...................................................................................... 5-285
OracleTimeStamp Static Fields........................................................................................ 5-293
OracleTimeStamp Static Methods................................................................................... 5-294
OracleTimeStamp Static Operators................................................................................. 5-303
OracleTimeStamp Static Type Conversions .................................................................. 5-315
OracleTimeStamp Properties........................................................................................... 5-321
OracleTimeStamp Methods ............................................................................................. 5-328
OracleTimeStampLTZ Structure ............................................................................................ 5-343
OracleTimeStampLTZ Members..................................................................................... 5-344
OracleTimeStampLTZ Constructors............................................................................... 5-350
OracleTimeStampLTZ Static Fields ................................................................................ 5-358
OracleTimeStampLTZ Static Methods ........................................................................... 5-360
OracleTimeStampLTZ Static Type Operators ............................................................... 5-370

OracleTimeStampLTZ Static Type Conversions........................................................... 5-382
OracleTimeStampLTZ Properties ................................................................................... 5-388
OracleTimeStampLTZ Methods...................................................................................... 5-395
OracleTimeStampTZ Structure............................................................................................... 5-410
OracleTimeStampTZ Members ....................................................................................... 5-411
OracleTimeStampTZ Constructors ................................................................................. 5-417
OracleTimeStampTZ Static Fields................................................................................... 5-432
OracleTimeStampTZ Static Methods.............................................................................. 5-434
xiii
OracleTimeStampTZ Static Operators ........................................................................... 5-443
OracleTimeStampTZ Static Type Conversions............................................................. 5-454
OracleTimeStampTZ Properties...................................................................................... 5-462
OracleTimeStampTZ Methods ........................................................................................ 5-469
ODP.NET Type Exceptions ........................................................................................................... 5-486
OracleTypeException Class..................................................................................................... 5-487
OracleTypeException Members ...................................................................................... 5-487
OracleTypeException Constructors................................................................................ 5-489
OracleTypeException Static Methods ............................................................................ 5-491
OracleTypeException Properties..................................................................................... 5-491
OracleTypeException Methods ....................................................................................... 5-492
OracleNullValueException Class ........................................................................................... 5-494
OracleNullValueException Members............................................................................. 5-495
OracleNullValueException Constructors ...................................................................... 5-496
OracleNullValueException Static Methods................................................................... 5-497
OracleNullValueException Properties ........................................................................... 5-498
OracleNullValueException Methods.............................................................................. 5-498
OracleTruncateException Class.............................................................................................. 5-500
OracleTruncateException Members .............................................................................. 5-501
OracleTruncateException Constructors ......................................................................... 5-502
OracleTruncateException Static Methods...................................................................... 5-503

OracleTruncateException Properties.............................................................................. 5-504
OracleTruncateException Methods ................................................................................ 5-504
ODP.NET Type Objects ................................................................................................................. 5-506
OracleBFile Class ...................................................................................................................... 5-507
OracleBFile Members........................................................................................................ 5-508
OracleBFile Constructors.................................................................................................. 5-511
OracleBFile Static Fields ................................................................................................... 5-513
OracleBFile Static Methods .............................................................................................. 5-514
OracleBFile Instance Properties....................................................................................... 5-515
OracleBFile Instance Methods ......................................................................................... 5-523
OracleBlob Class ....................................................................................................................... 5-543
OracleBlob Members......................................................................................................... 5-544
OracleBlob Constructors .................................................................................................. 5-547
OracleBlob Static Fields.................................................................................................... 5-549
xiv
OracleBlob Static Methods .............................................................................................. 5-550
OracleBlob Instance Properties........................................................................................ 5-551
OracleBlob Instance Methods .......................................................................................... 5-557
OracleClob Class....................................................................................................................... 5-580
OracleClob Members ........................................................................................................ 5-581
OracleClob Constructors .................................................................................................. 5-585
OracleClob Static Fields.................................................................................................... 5-587
OracleClob Static Methods............................................................................................... 5-588
OracleClob Instance Properties ....................................................................................... 5-588
OracleClob Instance Methods.......................................................................................... 5-595
OracleRefCursor Class ............................................................................................................. 5-624
OracleRefCursor Members............................................................................................... 5-625
OracleRefCursor Static Methods ..................................................................................... 5-626
OracleRefCursor Properties ............................................................................................. 5-627
OracleRefCursor Instance Methods................................................................................ 5-628

OracleXmlStream Class............................................................................................................ 5-630
OracleXmlStream Members............................................................................................. 5-631
OracleXmlStream Constructor......................................................................................... 5-633
OracleXmlStream Static Methods ................................................................................... 5-633
OracleXmlStream Instance Properties............................................................................ 5-634
OracleXmlStream Instance Methods .............................................................................. 5-638
OracleXmlType Class............................................................................................................... 5-646
OracleXmlType Members................................................................................................. 5-647
OracleXmlType Constructors .......................................................................................... 5-649
OracleXmlType Static Methods....................................................................................... 5-653
OracleXmlType Instance Properties ............................................................................... 5-653
OracleXmlType Instance Methods.................................................................................. 5-659
Glossary
Index
xv
Send Us Your Comments
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:
■
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
Redwood Shores, CA 94065
USA
If you would like a reply, please give your name, address, telephone number, and electronic mail
address (optional).
If you have problems with the software, please contact your local Oracle Support Services.
xvi
xvii
Preface
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:
■
Audience

■
Organization
■
Related Documentation
■
Conventions
■
Documentation Accessibility
xviii
Audience
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.
xix
Glossary
Defines terms used in this document.
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.
xx
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 at
/>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
/>If you already have a username and password for OTN, then you can go directly to

the documentation section of the OTN Web site at
/>For additional information, see:
/>Conventions
This section describes the conventions used in the text and code examples of this
documentation set. It describes:
■
Conventions in Text
■
Conventions in Code Examples
■
Conventions for Windows Operating Systems
xxi
Conventions in Text
We use various conventions in text to help you more quickly identify special terms.
The following table describes those conventions and provides examples of their use.
Convention Meaning Example
Bold Bold typeface indicates terms that are
defined in the text or terms that appear in
a glossary, or both.
When you specify this clause, you create an
index-organized table.
Italics Italic typeface indicates book titles or
emphasis.
Oracle Database Concepts
Ensure that the recovery catalog and target
database do not reside on the same disk.
UPPERCASE
monospace
(fixed-width)
font

Uppercase monospace typeface indicates
elements supplied by the system. Such
elements include parameters, privileges,
datatypes, RMAN keywords, SQL
keywords, SQL*Plus or utility commands,
packages and methods, as well as
system-supplied column names, database
objects and structures, usernames, and
roles.
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_STATS
procedure.
lowercase
monospace
(fixed-width)
font
Lowercase monospace typeface indicates
executables, filenames, directory names,
and sample user-supplied elements. Such
elements include computer and database
names, net service names, and connect
identifiers, as well as user-supplied
database objects and structures, column
names, packages and classes, usernames
and roles, program units, and parameter

values.
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.
Connect as oe user.
The JRepUtil class implements these
methods.
lowercase
italic
monospace
(fixed-width)
font
Lowercase italic monospace font
represents placeholders or variables.
You can specify the parallel_clause.
Run Uold_release.SQL where old_
release refers to the release you installed
prior to upgrading.
xxii
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.
Convention Meaning Example
[ ]
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;
.
.
.
Vertical ellipsis points indicate that we
have omitted several lines of code not
directly related to the example.
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;
xxiii
Conventions for Windows Operating Systems
The following table describes conventions for Windows operating systems and
provides examples of their use.
Italics
Italicized text indicates placeholders or

variables for which you must supply
particular values.
CONNECT SYSTEM/system_password
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/hr
CREATE USER mjones IDENTIFIED BY ty3MU9;

Convention Meaning Example
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
Convention Meaning Example
xxiv
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
Convention Meaning Example
xxv
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
/>ORACLE_HOME
and ORACLE_
BASE
In releases prior to Oracle8i release 8.1.3,
when you installed Oracle components,
all subdirectories were located under a
top level ORACLE_HOME directory. For
Windows NT, the default location was
C:\orant.
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.
Go to the ORACLE_BASE\ORACLE_
HOME\rdbms\admin directory.
Convention Meaning Example