Oracle Data Provider for .NET Developer's Guide


Oracle® Data Provider for .NET Developer's Guide 10g Release 1 (10.1.0.3) Part No. B14164-01 October 2004 Oracle Data Provider for .NET Developer’s Guide 10g Release 1 (10.1.0.3) Part No. B14164-01 Copyright © 2002, 2004, Oracle. 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; 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. This document is not warranted to be 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. If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth 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 we disclaim liability for any damages caused by such use of the Programs. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party. iii Contents Send Us Your Comments ...................................................................................................................... xiii Preface ............................................................................................................................................................... xv Audience..................................................................................................................................................... xv Documentation Accessibility................................................................................................................... xv Structure ..................................................................................................................................................... xvi Related Documents .................................................................................................................................. xvii Conventions ............................................................................................................................................. xviii What’s New in Oracle Data Provider for .NET? ...................................................................... xxiii New Features in Oracle Data Provider for .NET Release 10.1.0.3 ................................................... xxiii New Features in Oracle Data Provider for .NET Release 10.1 ......................................................... xxiv New Features in Oracle Data Provider for .NET Release 9.2.0.4 ..................................................... xxiv Volume 1 1 Introducing Oracle Data Provider for .NET Overview of Oracle Data Provider for .NET (ODP.NET) ................................................................. 1-1 ODP.NET Assembly................................................................................................................................. 1-1 Oracle.DataAccess.Client Namespace ............................................................................................ 1-1 Oracle.DataAccess.Client Classes............................................................................................. 1-1 Oracle.DataAccess.Client Enumerations................................................................................. 1-3 Oracle.DataAccess.Types Namespace ............................................................................................ 1-4 Oracle.DataAccess.Types Structures........................................................................................ 1-4 Oracle.DataAccess.Types Exceptions....................................................................................... 1-4 Oracle.DataAccess.Types Classes............................................................................................. 1-4 Using ODP.NET in a Simple Application .......................................................................................... 1-5 2 Installing and Configuring Oracle Data Provider for .NET System Requirements.............................................................................................................................. 2-1 Installing Oracle Data Provider for .NET............................................................................................ 2-2 File Locations ............................................................................................................................................ 2-2 iv 3 Features of Oracle Data Provider for .NET Connecting to the Oracle Database....................................................................................................... 3-1 Connection String Attributes............................................................................................................ 3-1 Connection Pooling ........................................................................................................................... 3-3 Using Connection Pooling......................................................................................................... 3-4 Operating System Authentication .................................................................................................. 3-5 Privileged Connections ..................................................................................................................... 3-5 Password Expiration.......................................................................................................................... 3-6 Proxy Authentication ........................................................................................................................ 3-7 Transparent Application Failover (TAF) Callback Support ........................................................ 3-8 TAF Notification ......................................................................................................................... 3-8 When Failover Occurs ................................................................................................................ 3-8 Registering an Event Handler for Failover ............................................................................. 3-9 OracleCommand Object....................................................................................................................... 3-10 Transaction....................................................................................................................................... 3-10 Parameter Binding .......................................................................................................................... 3-10 Datatypes BINARY_FLOAT and BINARY_DOUBLE........................................................ 3-11 OracleDbType Enumeration Type ........................................................................................ 3-11 Inference of DbType, OracleDbType, and .NET Types .................................................... 3-12 PL/SQL Associative Array..................................................................................................... 3-15 Array Binding........................................................................................................................... 3-18 Statement Caching .......................................................................................................................... 3-21 Statement Caching Connection String Attributes ............................................................... 3-21 Statement Caching Methods and Properties........................................................................ 3-21 Connections and Statement Caching .................................................................................... 3-22 Pooling and Statement Caching............................................................................................. 3-22 ODP.NET Types Overview.................................................................................................................. 3-22 Obtaining Data From an OracleDataReader.................................................................................... 3-23 Typed OracleDataReader Accessors ............................................................................................ 3-23 .NET Type Accessors............................................................................................................... 3-23 ODP.NET Type Accessors ...................................................................................................... 3-26 Obtaining LONG and LONG RAW Data.................................................................................... 3-27 Obtaining LOB Data ....................................................................................................................... 3-27 Methods Supported or Not Supported for InitialLOBFetchSize ...................................... 3-28 LOB Data Fetching Considerations....................................................................................... 3-28 Performance.............................................................................................................................. 3-29 Controlling the Number of Rows Fetched in One Server Round-Trip ................................... 3-29 Use of FetchSize........................................................................................................................ 3-29 Fine-Tuning FetchSize............................................................................................................. 3-29 Using the RowSize Property .................................................................................................. 3-30 PL/SQL REF CURSOR and OracleRefCursor.................................................................................. 3-30 Obtaining an OracleRefCursor...................................................................................................... 3-31 Obtaining a REF CURSOR............................................................................................................. 3-31 Populating an OracleDataReader from a REF CURSOR........................................................... 3-31 Populating the DataSet From a REF CURSOR ........................................................................... 3-31 Populating an OracleRefCursor From a REF CURSOR............................................................. 3-32 v Updating a DataSet Obtained From a REF CURSOR ................................................................ 3-32 Behavior of ExecuteScalar Method for REF CURSOR............................................................... 3-32 LOB Support........................................................................................................................................... 3-32 Large Character and Large Binary Datatypes............................................................................. 3-33 Oracle Data Provider for .NET LOB Objects............................................................................... 3-33 Updating LOBs Using a DataSet................................................................................................... 3-34 Updating LOBs Using OracleCommand and OracleParameter .............................................. 3-34 Updating LOBs Using ODP.NET LOB Objects........................................................................... 3-34 Temporary LOBs ............................................................................................................................. 3-35 ODP.NET XML Support....................................................................................................................... 3-35 Supported XML Features............................................................................................................... 3-36 OracleXmlType and Connection Dependency ........................................................................... 3-37 Updating XMLType Data in the Database Server...................................................................... 3-37 Updating with DataSet, OracleDataAdapter, and OracleCommandBuilder.................. 3-37 Updating with OracleCommand and OracleParameter .................................................... 3-38 Updating XML Data in OracleXmlType...................................................................................... 3-39 Special Characters in XML............................................................................................................. 3-39 Retrieving Query Result Set as XML............................................................................................ 3-39 Handling Date and Time Format .......................................................................................... 3-39 Special Characters in Column Data....................................................................................... 3-40 Special Characters In Table or View Name.......................................................................... 3-41 Case-Sensitivity in Column Name to XML Element Name Mapping ............................. 3-41 Column Name to XML Element Name Mapping ............................................................... 3-42 Object-Relational Data............................................................................................................. 3-43 NULL values............................................................................................................................. 3-44 Data Manipulation Using XML..................................................................................................... 3-44 Handling of Date and Time Format...................................................................................... 3-44 Saving Changes Using XML................................................................................................... 3-44 Special Characters in Column Data....................................................................................... 3-45 Special Characters in Table or View Name ......................................................................... 3-45 Case-Sensitivity in XML Element Name to Column Name Mapping ............................. 3-46 XML Element Name to Column Name Mapping ............................................................... 3-46 Object-Relational Data............................................................................................................. 3-48 Multiple Tables......................................................................................................................... 3-48 Commits .................................................................................................................................... 3-48 OracleDataAdapter Safe Type Mapping .......................................................................................... 3-49 Potential Data Loss ......................................................................................................................... 3-49 SafeMapping Property ................................................................................................................... 3-50 Using Safe Type Mapping ..................................................................................................... 3-50 OracleDataAdapter Requery Property.............................................................................................. 3-51 Guaranteeing Uniqueness in Updating DataSet to Database...................................................... 3-51 What Constitutes Uniqueness in DataRows?.............................................................................. 3-52 Configuring PrimaryKey and Constraints Properties............................................................... 3-52 Updating Without PrimaryKey and Constraints Configuration ............................................. 3-53 vi Globalization Support.......................................................................................................................... 3-53 Globalization Settings..................................................................................................................... 3-53 Client Globalization Settings.................................................................................................. 3-54 Session Globalization Settings .............................................................................................. 3-54 Thread-Based Globalization Settings.................................................................................... 3-55 Globalization-Sensitive Operations.............................................................................................. 3-56 Operations Dependent on Client Computer's Globalization Settings ............................. 3-56 Operations Dependent on Thread Globalization Settings................................................. 3-56 Operations Sensitive to Session Globalization Parameters ............................................... 3-57 Debug Tracing........................................................................................................................................ 3-57 Registry Settings for Tracing Calls ............................................................................................... 3-57 TraceFileName.......................................................................................................................... 3-57 TraceLevel ................................................................................................................................. 3-57 TraceOption .............................................................................................................................. 3-58 4 Oracle Data Provider for .NET Classes OracleCommand Class............................................................................................................................ 4-2 OracleCommand Members............................................................................................................... 4-4 OracleCommand Constructors ........................................................................................................ 4-7 OracleCommand Static Methods..................................................................................................... 4-9 OracleCommand Properties .......................................................................................................... 4-10 OracleCommand Public Methods ................................................................................................ 4-24 OracleCommandBuilder Class ........................................................................................................... 4-38 OracleCommandBuilder Members .............................................................................................. 4-40 OracleCommandBuilder Constructors ........................................................................................ 4-42 OracleCommandBuilder Static Methods..................................................................................... 4-44 OracleCommandBuilder Properties............................................................................................. 4-47 OracleCommandBuilder Public Methods ................................................................................... 4-49 OracleCommandBuilder Events ................................................................................................... 4-52 OracleCommandBuilder Event Delegates................................................................................... 4-53 OracleConnection Class....................................................................................................................... 4-54 OracleConnection Members ......................................................................................................... 4-56 OracleConnection Constructors ................................................................................................... 4-59 OracleConnection Static Methods ................................................................................................ 4-61 OracleConnection Properties......................................................................................................... 4-62 OracleConnection Public Methods............................................................................................... 4-71 OracleConnection Events............................................................................................................... 4-83 OracleConnection Event Delegates .............................................................................................. 4-85 OracleDataAdapter Class .................................................................................................................... 4-86 OracleDataAdapter Members ....................................................................................................... 4-88 OracleDataAdapter Constructors ................................................................................................ 4-90 OracleDataAdapter Static Methods.............................................................................................. 4-93 OracleDataAdapter Properties...................................................................................................... 4-94 OracleDataAdapter Public Methods ............................................................................................ 4-99 OracleDataAdapter Events.......................................................................................................... 4-104 OracleDataAdapter Event Delegates ......................................................................................... 4-108 vii OracleDataReader Class..................................................................................................................... 4-109 OracleDataReader Members........................................................................................................ 4-112 OracleDataReader Static Methods.............................................................................................. 4-115 OracleDataReader Properties...................................................................................................... 4-116 OracleDataReader Public Methods ............................................................................................ 4-123 OracleError Class................................................................................................................................. 4-162 OracleError Members ................................................................................................................... 4-164 OracleError Static Methods ......................................................................................................... 4-165 OracleError Properties.................................................................................................................. 4-166 OracleError Methods .................................................................................................................... 4-169 OracleErrorCollection Class.............................................................................................................. 4-170 OracleErrorCollection Members ................................................................................................. 4-172 OracleErrorCollection Static Methods ....................................................................................... 4-173 OracleErrorCollection Properties................................................................................................ 4-174 OracleErrorCollection Public Methods...................................................................................... 4-175 OracleException Class ....................................................................................................................... 4-176 OracleException Members........................................................................................................... 4-178 OracleException Static Methods ................................................................................................. 4-180 OracleException Properties ......................................................................................................... 4-181 OracleException Methods............................................................................................................ 4-184 OracleInfoMessageEventArgs Class ............................................................................................... 4-186 OracleInfoMessageEventArgs Members ................................................................................... 4-188 OracleInfoMessageEventArgs Static Methods ......................................................................... 4-189 OracleInfoMessageEventArgs Properties.................................................................................. 4-190 OracleInfoMessageEventArgs Public Methods........................................................................ 4-192 OracleInfoMessageEventHandler Delegate................................................................................... 4-193 OracleParameter Class........................................................................................................................ 4-194 OracleParameter Members .......................................................................................................... 4-196 OracleParameter Constructors.................................................................................................... 4-198 OracleParameter Static Methods................................................................................................. 4-209 OracleParameter Properties......................................................................................................... 4-210 OracleParameter Public Methods ............................................................................................... 4-223 OracleParameterCollection Class..................................................................................................... 4-225 OracleParameterCollection Members ........................................................................................ 4-227 OracleParameterCollection Static Methods............................................................................... 4-229 OracleParameterCollection Properties....................................................................................... 4-230 OracleParameterCollection Public Methods ............................................................................. 4-233 OracleRowUpdatedEventHandler Delegate.................................................................................. 4-250 OracleRowUpdatedEventArgs Class............................................................................................... 4-251 OracleRowUpdatedEventArgs Members.................................................................................. 4-252 OracleRowUpdatedEventArgs Constructor ............................................................................. 4-254 OracleRowUpdatedEventArgs Static Methods ........................................................................ 4-255 OracleRowUpdatedEventArgs Properties ................................................................................ 4-256 OracleRowUpdatedEventArgs Public Methods....................................................................... 4-257 OracleRowUpdatingEventArgs Class ............................................................................................. 4-258 OracleRowUpdatingEventArgs Members ................................................................................ 4-259 OracleRowUpdatingEventArgs Constructor............................................................................ 4-261 viii OracleRowUpdatingEventArgs Static Methods....................................................................... 4-262 OracleRowUpdatingEventArgs Properties............................................................................... 4-263 OracleRowUpdatingEventArgs Public Methods ..................................................................... 4-264 OracleRowUpdatingEventHandler Delegate ................................................................................ 4-265 OracleTransaction Class..................................................................................................................... 4-266 OracleTransaction Members........................................................................................................ 4-269 OracleTransaction Static Methods.............................................................................................. 4-270 OracleTransaction Properties ...................................................................................................... 4-271 OracleTransaction Public Methods ............................................................................................ 4-273 OracleCollectionType Enumeration .............................................................................................. 4-281 OracleDbType Enumeration ............................................................................................................. 4-282 OracleParameterStatus Enumeration .............................................................................................. 4-284 5 Oracle Data Provider for .NET XML-Related Classes OracleXmlCommandType Enumeration ............................................................................................. 5-2 OracleXmlQueryProperties Class ......................................................................................................... 5-3 OracleXmlQueryProperties Members............................................................................................. 5-6 OracleXmlQueryProperties Constructor ........................................................................................ 5-7 OracleXmlQueryProperties Properties ........................................................................................... 5-8 OracleXmlQueryProperties Public Methods .............................................................................. 5-11 OracleXmlSaveProperties Class ......................................................................................................... 5-12 OracleXmlSaveProperties Members............................................................................................. 5-15 OracleXmlSaveProperties Constructor ........................................................................................ 5-16 OracleXmlSaveProperties Properties ........................................................................................... 5-17 OracleXmlSaveProperties Public Methods ................................................................................. 5-21 OracleXmlStream Class........................................................................................................................ 5-22 OracleXmlStream Members........................................................................................................... 5-23 OracleXmlStream Constructor ...................................................................................................... 5-25 OracleXmlStream Static Methods................................................................................................. 5-26 OracleXmlStream Instance Properties ......................................................................................... 5-27 OracleXmlStream Instance Methods............................................................................................ 5-31 OracleXmlType Class............................................................................................................................ 5-36 OracleXmlType Members .............................................................................................................. 5-37 OracleXmlType Constructors........................................................................................................ 5-39 OracleXmlType Static Methods .................................................................................................... 5-42 OracleXmlType Instance Properties............................................................................................. 5-43 OracleXmlType Instance Methods ............................................................................................... 5-48 6 Oracle Data Provider for .NET Globalization Classes OracleGlobalization Class...................................................................................................................... 6-2 OracleGlobalization Members.......................................................................................................... 6-4 OracleGlobalization Static Methods................................................................................................ 6-6 OracleGlobalization Properties..................................................................................................... 6-12 OracleGlobalization Public Methods ........................................................................................... 6-22 ix 7 Oracle Data Provider for .NET Failover Classes OracleFailoverEventArgs Class............................................................................................................. 7-2 OracleFailoverEventArgs Members ................................................................................................ 7-4 OracleFailoverEventArgs Static Methods ...................................................................................... 7-5 OracleFailoverEventArgs Properties............................................................................................... 7-6 OracleFailoverEventArgs Public Methods..................................................................................... 7-7 OracleFailoverEventHandler Delegate ................................................................................................ 7-8 FailoverEvent Enumeration................................................................................................................. 7-10 FailoverReturnCode Enumeration..................................................................................................... 7-11 FailoverType Enumeration .................................................................................................................. 7-12 Volume 2 8 Oracle Data Provider for .NET Types Classes OracleBFile Class...................................................................................................................................... 8-2 OracleBFile Members......................................................................................................................... 8-4 OracleBFile Constructors .................................................................................................................. 8-7 OracleBFile Static Fields.................................................................................................................... 8-9 OracleBFile Static Methods............................................................................................................ 8-10 OracleBFile Instance Properties .................................................................................................... 8-11 OracleBFile Instance Methods....................................................................................................... 8-17 OracleBlob Class ................................................................................................................................... 8-35 OracleBlob Members ...................................................................................................................... 8-37 OracleBlob Constructors ................................................................................................................ 8-40 OracleBlob Static Fields.................................................................................................................. 8-42 OracleBlob Static Methods............................................................................................................. 8-43 OracleBlob Instance Properties ..................................................................................................... 8-44 OracleBlob Instance Methods........................................................................................................ 8-49 OracleClob Class ................................................................................................................................... 8-69 OracleClob Members ...................................................................................................................... 8-71 OracleClob Constructors................................................................................................................ 8-74 OracleClob Static Fields ................................................................................................................. 8-76 OracleClob Static Methods ............................................................................................................ 8-77 OracleClob Instance Properties..................................................................................................... 8-78 OracleClob Instance Methods ....................................................................................................... 8-84 OracleRefCursor Class ....................................................................................................................... 8-109 OracleRefCursor Members .......................................................................................................... 8-111 OracleRefCursor Static Methods................................................................................................. 8-112 OracleRefCursor Properties......................................................................................................... 8-113 OracleRefCursor Instance Methods............................................................................................ 8-114 x Volume 3 9 Oracle Data Provider for .NET Types Structures OracleBinary Structure............................................................................................................................ 9-2 OracleBinary Members...................................................................................................................... 9-4 OracleBinary Constructor ................................................................................................................. 9-7 OracleBinary Static Fields ................................................................................................................. 9-8 OracleBinary Static Methods ............................................................................................................ 9-9 OracleBinary Static Operators....................................................................................................... 9-15 OracleBinary Static Type Conversion Operators ....................................................................... 9-21 OracleBinary Properties ................................................................................................................. 9-23 OracleBinary Instance Methods.................................................................................................... 9-26 OracleDate Structure ............................................................................................................................ 9-29 OracleDate Members ...................................................................................................................... 9-31 OracleDate Constructors................................................................................................................ 9-34 OracleDate Static Fields.................................................................................................................. 9-39 OracleDate Static Methods .......................................................................................................... 9-41 OracleDate Static Operators .......................................................................................................... 9-47 OracleDate Static Type Conversions............................................................................................ 9-52 OracleDate Properties..................................................................................................................... 9-56 OracleDate Methods ....................................................................................................................... 9-60 OracleDecimal Structure...................................................................................................................... 9-65 OracleDecimal Members................................................................................................................ 9-67 OracleDecimal Constructors.......................................................................................................... 9-72 OracleDecimal Static Fields ........................................................................................................... 9-78 OracleDecimal Static (Comparison) Methods............................................................................. 9-82 OracleDecimal Static (Manipulation) Methods .......................................................................... 9-87 OracleDecimal Static (Logarithmic) Methods........................................................................... 9-101 OracleDecimal Static (Trigonometric) Methods ....................................................................... 9-106 OracleDecimal Static (Comparison) Operators ........................................................................ 9-112 OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) ............ 9-120 OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) ...................... 9-124 OracleDecimal Properties ............................................................................................................ 9-129 OracleDecimal Instance Methods ............................................................................................... 9-133 OracleIntervalDS Structure............................................................................................................... 9-139 OracleIntervalDS Members ......................................................................................................... 9-141 OracleIntervalDS Constructors ................................................................................................... 9-144 OracleIntervalDS Static Fields..................................................................................................... 9-149 OracleIntervalDS Static Methods................................................................................................ 9-151 OracleIntervalDS Static Operators.............................................................................................. 9-157 OracleIntervalDS Type Conversions.......................................................................................... 9-165 OracleIntervalDS Properties........................................................................................................ 9-168 OracleIntervalDS Methods .......................................................................................................... 9-173 OracleIntervalYM Structure.............................................................................................................. 9-176 OracleIntervalYM Members ........................................................................................................ 9-178 OracleIntervalYM Constructors.................................................................................................. 9-181 OracleIntervalYM Static Fields .................................................................................................. 9-185 xi OracleIntervalYM Static Methods .............................................................................................. 9-187 OracleIntervalYM Static Operators ............................................................................................ 9-193 OracleIntervalYM Type Conversions......................................................................................... 9-200 OracleIntervalYM Properties....................................................................................................... 9-203 OracleIntervalYM Methods ......................................................................................................... 9-206 OracleString Structure........................................................................................................................ 9-209 OracleString Members.................................................................................................................. 9-211 OracleString Constructors............................................................................................................ 9-214 OracleString Static Fields ............................................................................................................. 9-219 OracleString Static Methods ........................................................................................................ 9-220 OracleString Static Operators...................................................................................................... 9-225 OracleString Type Conversions .................................................................................................. 9-230 OracleString Properties ................................................................................................................ 9-232 OracleString Methods................................................................................................................... 9-235 OracleTimeStamp Structure.............................................................................................................. 9-240 OracleTimeStamp Members ........................................................................................................ 9-242 OracleTimeStamp Constructors.................................................................................................. 9-246 OracleTimeStamp Static Fields ................................................................................................... 9-253 OracleTimeStamp Static Methods .............................................................................................. 9-255 OracleTimeStamp Static Operators ............................................................................................ 9-262 OracleTimeStamp Static Type Conversions.............................................................................. 9-271 OracleTimeStamp Properties....................................................................................................... 9-277 OracleTimeStamp Methods ......................................................................................................... 9-282 OracleTimeStampLTZ Structure ...................................................................................................... 9-293 OracleTimeStampLTZ Members ................................................................................................ 9-295 OracleTimeStampLTZ Constructors .......................................................................................... 9-299 OracleTimeStampLTZ Static Fields............................................................................................ 9-306 OracleTimeStampLTZ Static Methods....................................................................................... 9-308 OracleTimeStampLTZ Static Type Operators........................................................................... 9-316 OracleTimeStampLTZ Static Type Conversions ...................................................................... 9-325 OracleTimeStampLTZ Properties............................................................................................... 9-331 OracleTimeStampLTZ Methods ................................................................................................. 9-336 OracleTimeStampTZ Structure......................................................................................................... 9-348 OracleTimeStampTZ Members................................................................................................... 9-350 OracleTimeStampTZ Constructors............................................................................................. 9-354 OracleTimeStampTZ Static Fields .............................................................................................. 9-366 OracleTimeStampTZ Static Methods ......................................................................................... 9-368 OracleTimeStampTZ Static Operators ....................................................................................... 9-375 OracleTimeStampTZ Static Type Conversions......................................................................... 9-384 OracleTimeStampTZ Properties ................................................................................................. 9-390 OracleTimeStampTZ Methods.................................................................................................... 9-396 10 Oracle Data Provider for .NET Types Exceptions OracleTypeException Class ................................................................................................................. 10-2 OracleTypeException Members.................................................................................................... 10-3 OracleTypeException Constructors.............................................................................................. 10-5 OracleTypeException Static Methods .......................................................................................... 10-7 xii OracleTypeException Properties .................................................................................................. 10-8 OracleTypeException Methods................................................................................................... 10-10 OracleNullValueException Class ..................................................................................................... 10-11 OracleNullValueException Members ........................................................................................ 10-12 OracleNullValueException Constructors .................................................................................. 10-14 OracleNullValueException Static Methods............................................................................... 10-16 OracleNullValueException Properties....................................................................................... 10-17 OracleNullValueException Methods ......................................................................................... 10-18 OracleTruncateException Class ........................................................................................................ 10-19 OracleTruncateException Members .......................................................................................... 10-20 OracleTruncateException Constructors..................................................................................... 10-22 OracleTruncateException Static Methods ................................................................................. 10-24 OracleTruncateException Properties.......................................................................................... 10-25 OracleTruncateException Methods ............................................................................................ 10-26 Glossary Index xiii Send Us Your Comments Oracle Data Provider for .NET Developer’s Guide 10g Release 1 (10.1.0.3) Part No. B14164-01 Oracle 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-7357. Attn: Oracle Database for Windows Documentation ■ Postal service: Oracle Corporation Oracle Database for Windows Documentation Manager 500 Oracle Parkway, Mailstop 1op4 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. xiv xv 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 ■ Documentation Accessibility ■ Structure ■ Related Documents ■ Conventions Audience Oracle Data Provider for .NET Developer’s Guide is intended for programmers 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 programming 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. 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 xvi customers. For additional information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/ 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. Structure 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 Oracle Data Provider for .NET" 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 DB. Chapter 4, "Oracle Data Provider for .NET Classes" Describes the classes and public methods Oracle Data Provider for .NET exposes for ADO.NET programmers. Chapter 5, "Oracle Data Provider for .NET XML-Related Classes" Describes Oracle Data Provider for .NET XML-related classes and enumerations. Chapter 6, "Oracle Data Provider for .NET Globalization Classes" Describes the Oracle Data Provider for .NET globalization classes. Chapter 7, "Oracle Data Provider for .NET Failover Classes" Describes the Oracle Data Provider for .NET failover classes and enumerations. Chapter 8, "Oracle Data Provider for .NET Types Classes" Describes the large object and REF CURSOR objects provided by Oracle Data Provider for .NET. Chapter 9, "Oracle Data Provider for .NET Types Structures" Describes the types structures and objects provided by Oracle Data Provider for .NET. xvii Chapter 10, "Oracle Data Provider for .NET Types Exceptions" Describes the Oracle Data Provider for .NET Types exceptions. Glossary Defines terms used in this document. Related Documents 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 Call Interface Programmer's 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 ■ Oracle Database Security Guide Many of the examples in this book use the sample schemas, which are installed by default when you select the Basic Installation option with an Oracle Database installation. 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 http://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 http://otn.oracle.com/membership/ 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 http://otn.oracle.com/documentation/ xviii For additional information, see: http://msdn.microsoft.com/netframework and http://msdn.microsoft.com/library 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 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, Recovery Manager 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 executable programs, filenames, directory names, and sample user-supplied elements. Such elements include computer and database names, net service names and connect identifiers, 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 start 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 old_release.SQL where old_release refers to the release you installed prior to upgrading. xix 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. Conventions for Windows Operating Systems The following table describes conventions for Windows operating systems and provides examples of their use. Convention Meaning Example [ ] Anything enclosed in brackets is optional. DECIMAL (digits [ , precision ]) { } Braces are used for grouping items. {ENABLE | DISABLE} | A vertical bar represents a choice of two options. {ENABLE | DISABLE} [COMPRESS | NOCOMPRESS] ... Ellipsis points mean repetition in syntax descriptions. In addition, ellipsis points can mean an omission in code examples or text. CREATE TABLE ... AS subquery; SELECT col1, col2, ... , coln FROM employees; Other symbols You must use symbols other than brackets ([ ]), braces ({ }), vertical bars (|), and ellipsis points (...) exactly as shown. acctbal NUMBER(11,2); acct CONSTANT NUMBER(4) := 3; 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. Because these terms are not case sensitive, you can use them in either UPPERCASE or lowercase. SELECT last_name, employee_id FROM employees; SELECT * FROM USER_TABLES; DROP TABLE hr.employees; lowercase Lowercase typeface indicates user-defined programmatic elements, such as 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 > menu item How to start a program. To start the Database Configuration Assistant, choose Start > Programs > Oracle - HOME_NAME > Configuration and Migration Tools > Database Configuration Assistant. xx 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 filename 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 HR/HR TABLES=emp QUERY=\"WHERE job='REP'\" 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 xxi 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. The default for Windows NT 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\product\10.1.0. 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\product\10.1.0\db_n, where n is the latest Oracle home 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 Installation 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 xxii xxiii What’s New in Oracle Data Provider for .NET? This section describes new features in Oracle Data Provider for .NET 10g Release 1 (10.1.0.3) 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.0.3 ■ 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.0.3 Oracle Data Provider for .NET release 10.1.0.3 includes the following: ■ Statement Caching This feature provides and manages a cache of statements for each session. The developer can control which statements are cached and how many. This improves performance and scalability. ■ .NET Framework 1.1 Enhancements These enhancements expose new ADO.NET functionality that was introduced in Microsoft .NET Framework 1.1. ■ Support for Command Cancellation These two new features relate to command cancellation. The CommandTimeout feature cancels the execution of a command when a specified amount of time elapses after the execution, while the Cancel method can be called explicitly by the application to terminate the execution of a command. See Also: "Statement Caching" on page 3-21 See Also: ■ "EnlistDistributedTransaction" on page 4-76 ■ "HasRows" on page 4-118 xxiv ■ DerivedParameters Method This method populates the parameter collection for the OracleCommand that represents a stored procedure or function by querying the database for the parameter information. 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 Grids ODP.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 database ODP.NET supports the new database native types BINARY_FLOAT and BINARY_ DOUBLE ■ Support for Multiple Homes ODP.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 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: ■ 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: ■ "CommandTimeout" on page 4-15 ■ "Cancel" on page 4-24 See Also: "DeriveParameters" on page 4-44 See Also: "Datatypes BINARY_FLOAT and BINARY_DOUBLE" on page 3-11 See Also: "ODP.NET XML Support" on page 3-35 xxv ■ Support for PL/SQL Associative Array Binding ODP.NET supports PL/SQL Associative Array (formerly known as PL/SQL 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-15 See Also: "Obtaining LOB Data" on page 3-27 xxvi Introducing Oracle Data Provider for .NET 1-1 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) 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.dll assembly 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 Namespace The Oracle.DataAccess.Client contains ODP.NET classes and enumerations. Oracle.DataAccess.Client Classes Table 1–1 lists the client classes. ODP.NET Assembly 1-2 Oracle Data Provider for .NET Developer’s Guide Table 1–1 Oracle.DataAccess.Client Classes Class Description OracleCommand Class An OracleCommand object represents a SQL command, a stored procedure or function, or a table name OracleCommandBuilder Class An OracleCommandBuilder object provides automatic SQL generation for the OracleDataAdapter when updates are made to the database OracleConnection Class An OracleConnection object represents a connection to an Oracle database OracleDataAdapter Class An OracleDataAdapter object represents a data provider object that communicates with the DataSet OracleDataReader Class An OracleDataReader object represents a forward-only, read-only, in-memory result set OracleError Class The OracleError object represents an error reported by an Oracle database OracleErrorCollection Class An OracleErrorCollection object represents a collection of OracleErrors OracleException Class The OracleException object represents an exception that is thrown when Oracle Data Provider for .NET encounters an error OracleFailoverEventArgs Class The OracleFailoverEventArgs object provides event data for the OracleConnection.Failover event OracleFailoverEventHandler Delegate The OracleFailoverEventHandler delegate represents the signature of the method that handles the OracleConnection.Failover event OracleGlobalization Class The OracleGlobalization class is used to obtain and set the Oracle globalization settings of the session, thread, and local computer (read-only) OracleInfoMessageEventHandler Delegate The OracleInfoMessageEventHandler delegate represents the signature of the method that handles the OracleConnection.InfoMessage event OracleInfoMessageEventArgs Class The OracleInfoMessageEventArgs object provides event data for the OracleConnection.InfoMessage event OracleParameter Class An OracleParameter object represents a parameter for an OracleCommand OracleParameterCollection Class An OracleParameterCollection object represents a collection of OracleParameters OracleRowUpdatedEventArgs Class The OracleRowUpdatedEventArgs object provides event data for the OracleDataAdapter.RowUpdated event OracleRowUpdatedEventHandler Delegate The OracleRowUpdatedEventHandler delegate represents the signature of the method that handles the OracleDataAdapter.RowUpdated event ODP.NET Assembly Introducing Oracle Data Provider for .NET 1-3 Oracle.DataAccess.Client Enumerations Table 1–2 lists the client enumerations. OracleRowUpdatingEventArgs Class The OracleRowUpdatingEventArgs object provides event data for the OracleDataAdapter.RowUpdating event OracleRowUpdatingEventHandler Delegate The OracleRowUpdatingEventHandler delegate represents the signature of the method that handles the OracleDataAdapter.RowUpdating event OracleTransaction Class An OracleTransaction object represents a local transaction OracleXmlQueryProperties Class An OracleXmlQueryProperties object represents the XML properties used by the OracleCommand class when the XmlCommandType property is Query OracleXmlSaveProperties Class An OracleXmlSaveProperties object represents the XML properties used by the OracleCommand class when the XmlCommandType property is Insert, Update, or Delete Table 1–2 Oracle.DataAccess.Client Enumerations Enumeration Description FailoverEvent Enumeration FailoverEvent enumerated values are used to explicitly specify the state of the failover FailoverReturnCode Enumeration FailoverReturnCode enumerated values 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 FailoverType Enumeration FailoverType enumerated values are used to indicate the type of failover event that was raised OracleCollectionType Enumeration OracleCollectionType enumerated values specify whether the OracleParameter object represents a collection, and if so, specifies the collection type OracleDbType Enumeration OracleDbType enumerated values are used to explicitly specify the OracleDbType of an OracleParameter OracleParameterStatus Enumeration The OracleParameterStatus enumeration type indicates whether a NULL value 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 OracleXmlCommandType Enumeration The OracleXmlCommandType enumeration specifies the values that are allowed for the OracleXmlCommandType property of the OracleCommand class Table 1–1 (Cont.) Oracle.DataAccess.Client Classes Class Description ODP.NET Assembly 1-4 Oracle Data Provider for .NET Developer’s Guide Oracle.DataAccess.Types Namespace The Oracle.DataAccess.Types namespace provides classes, structures, and exceptions for Oracle native types that can be used with Oracle Data Provider for .NET. Oracle.DataAccess.Types Structures Table 1–3 lists the types structures. Oracle.DataAccess.Types Exceptions Types exceptions are thrown only by ODP.NET types structures. Table 1–4 lists the types exceptions. Oracle.DataAccess.Types Classes Table 1–5 lists the types classes. Table 1–3 Oracle.DataAccess.Types Structures Structure Description OracleBinary Structure The OracleBinary structure represents a variable-length stream of binary data OracleDate Structure The OracleDate structure represents the Oracle DATE 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 INTERVAL YEAR TO MONTH datatype OracleString Structure The OracleString structure represents a 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 TIMESTAMP WITH TIME ZONE data type Table 1–4 Oracle.DataAccess.Types Exceptions Exception Description 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 Using ODP.NET in a Simple Application Introducing Oracle Data Provider for .NET 1-5 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. // C# using System; using Oracle.DataAccess.Client; class Sample { static void Main() { // Connect to Oracle string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Display Version Number Console.WriteLine("Connected to Oracle " + con.ServerVersion); // Close and Dispose OracleConnection con.Close(); con.Dispose(); } } Table 1–5 Oracle.DataAccess.Types Classes Class Description OracleBFile Class An OracleBFile is an object that has a reference to BFILE data. It provides methods for performing operations on BFiles OracleBlob Class An OracleBlob object is an object that has a reference to BLOB data. It provides methods for performing operations on BLOBs OracleClob Class An OracleClob is an object that has a reference to CLOB data. It provides methods for performing operations on CLOBs OracleRefCursor Class An OracleRefCursor object represents an Oracle REF CURSOR OracleXmlStream Class An OracleXmlStream object represents a sequential read-only stream of XML data stored in an OracleXmlType object OracleXmlType Class An OracleXmlType object represents an Oracle XmlType instance Note: Additional samples are provided in the ORACLE_ BASE\ORACLE_HOME\ODP.NET\Samples directory. Using ODP.NET in a Simple Application 1-6 Oracle Data Provider for .NET Developer’s Guide Installing and Configuring Oracle Data Provider for .NET 2-1 2 Installing and Configuring Oracle Data Provider for .NET 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 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). Additional requirements: ■ Applications using Microsoft Enterprise Services transactions require Oracle Services for Microsoft Transaction Server release 10.1. ■ OracleXmlStream and OracleXmlType classes require Oracle9i Database release 2 (9.2) or higher. ■ 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). ■ ExecuteStream ■ ExecuteToStream ■ ExecuteXmlReader ■ ExecuteNonQuery Installing Oracle Data Provider for .NET 2-2 Oracle Data Provider for .NET Developer’s Guide Installing Oracle Data Provider for .NET When you install Oracle Data Provider for .NET, Oracle Universal Installer automatically registers ODP.NET with the Global Assembly Cache (GAC). Additionally, ODP.NET Dynamic Help is registered with Visual Studio .NET, providing context-sensitive online help that is seamlessly integrated with Visual Studio .NET Dynamic Help. With Dynamic Help, the user can access ODP.NET documentation within the Visual Studio .NET IDE by placing the cursor on an ODP.NET keyword and pressing the F1 function key. File Locations The Oracle.DataAccess.dll assembly is installed in the ORACLE_BASE\ORACLE_ HOME\bin directory. Documentation and the readme.txt are installed in the ORACLE_BASE\ORACLE_ HOME\ODP.NET\doc directory. Samples are provided in the ORACLE_BASE\ORACLE_HOME\ODP.NET\Samples directory. See Also: ■ http://msdn.microsoft.com/netframework ■ http://otn.oracle.com/tech/xml/xdkhome.html to download the Oracle XML Developer's Kit (XDK) See Also: Oracle Database Installation Guide for Windows for installation instructions Features of Oracle Data Provider for .NET 3-1 3 Features of Oracle Data Provider for .NET This chapter describes Oracle Data Provider for .NET provider-specific features and how to use them to develop .NET applications. This chapter contains these topics: ■ Connecting to the Oracle Database ■ OracleCommand Object ■ ODP.NET Types Overview ■ Obtaining Data From an OracleDataReader ■ PL/SQL REF CURSOR and OracleRefCursor ■ LOB Support ■ ODP.NET XML Support ■ OracleDataAdapter Safe Type Mapping ■ OracleDataAdapter Requery Property ■ Guaranteeing Uniqueness in Updating DataSet to Database ■ Globalization Support ■ Debug Tracing Connecting to the Oracle Database This section describes OracleConnection provider-specific features, including: ■ Connection String Attributes ■ Connection Pooling ■ Operating System Authentication ■ Privileged Connections ■ Password Expiration ■ Proxy Authentication ■ Transparent Application Failover (TAF) Callback Support Connection String Attributes Table 3–1 lists the supported connection string attributes. Connecting to the Oracle Database 3-2 Oracle Data Provider for .NET Developer’s Guide The following example uses connection string attributes to connect to an Oracle Database: // C# using System; using Oracle.DataAccess.Client; class ConnectionSample { static void Main() { OracleConnection con = new OracleConnection(); //using connection string attributes to connect to Oracle Database Table 3–1 Supported Connection String Attributes Connection String Attribute Default value Description Connection Lifetime 0 Maximum life time (in seconds) of the connection Connection Timeout 15 Maximum time (in seconds) to wait for a free connection from the pool Data Source empty string Oracle Net Service Name that identifies the database to connect to DBA Privilege empty string Administrative privileges: SYSDBA or SYSOPER Decr Pool Size 1 Controls the number of connections that are closed when an excessive amount of established connections are unused Enlist True Enables or disables serviced components to automatically enlist in distributed transactions Incr Pool Size 5 Controls the number of connections that are established when all the connections in the pool are used Max Pool Size 100 Maximum number of connections in a pool Min Pool Size 1 Minimum number of connections in a pool Password empty string Password for the user specified by User Id Persist Security Info False Enables or disables the retrieval of password in the connection string Pooling True Enables or disables connection pooling Proxy User Id empty string User name of the proxy user Proxy Password empty string Password of the proxy user Statement Cache Purge False Purges the Statement Cache when the connection goes back to the pool Statement Cache Size 0 Enables Statement Caching and sets the cache size, that is, the maximum number of statements that can be cached User Id empty string Oracle user name Validate Connection False Enables or disables validation of connections coming from the pool Connecting to the Oracle Database Features of Oracle Data Provider for .NET 3-3 con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle"; con.Open(); Console.WriteLine("Connected to Oracle" + con.ServerVersion); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } Connection Pooling ODP.NET connection pooling is enabled and disabled using the Pooling connection string attribute. By default, connection pooling is enabled. The following are ConnectionString attributes that control the behavior of the connection pooling service: ■ Pooling ■ Connection Lifetime ■ Connection Timeout ■ Max Pool Size ■ Min Pool Size ■ Incr Pool Size ■ Decr Pool Size ■ Validate Connection Connection Pooling Example The following code opens a connection using ConnectionString attributes related to connection pooling. // C# using System; using Oracle.DataAccess.Client; class ConnectionPoolingSample { static void Main() { OracleConnection con = new OracleConnection(); //Open a connection using ConnectionString attributes //related to connection pooling. con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;" + "Min Pool Size=10;Connection Lifetime=120;Connection Timeout=60;" + See Also: ■ "OracleConnection Properties" on page 4-62 for detailed information on connection attributes ■ "OracleCommand Object" on page 3-10 for detailed information on statement caching Connecting to the Oracle Database 3-4 Oracle Data Provider for .NET Developer’s Guide "Incr Pool Size=5; Decr Pool Size=2"; con.Open(); Console.WriteLine("Connection pool successfully created"); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Connection is placed back into the pool."); } } Using Connection Pooling With connection pooling enabled (the default), the Open and Close methods of the OracleConnection object implicitly use the connection pooling service. In the preceding code, the Open call uses the connection pooling service, which is responsible for pooling and returning connections to the application. The connection pooling service creates connection pools by using the ConnectionString as a signature, to uniquely identify a pool. If no pool with the exact attribute values in the ConnectionString exists, the connection pooling service creates a new connection pool. If a pool already exists with the requested signature, a connection is returned to the application from that pool. When a connection pool is created, the connection-pooling service initially creates the number of connections defined by the Min Pool Size attribute of the ConnectionString. This number of connections is always maintained by the connection pooling service for the connection pool. At any given time, these connections are available in the pool or used by the application. The Incr Pool Size attribute of the ConnectionString defines the number of new connections to be created by the connection pooling service when more connections are needed in the connection pool. When the application closes a connection, the connection pooling service determines whether the connection lifetime has exceeded the Connection Lifetime attribute; if so, the connection pooling service closes the connection; otherwise, the connection goes back to the connection pool. The connection pooling service only enforces the Connection Lifetime when a connection is going back to the connection pool. The Max Pool Size attribute of the ConnectionString sets the maximum number of connections for a connection pool. If a new connection is requested, no connections are available, and Max Pool Size has been reached, then the connection pooling service waits for the time defined by Connection Timeout. If the Connection Timeout has been reached and there are still no connections available in the pool, the connection pooling service raises an exception indicating that the pooled connection request has timed-out. The Validate Connection attribute validates connections coming out of the pool. This attribute should only be used when absolutely necessary because it causes a server round-trip to the database to validate each connection right before it is provided to the application. If invalid connections are uncommon, developers can create their own event handler to retrieve a new connection, rather than using Validate Connection. This generally provides better performance. The connection pooling service closes connections when they are not used; connections are closed every three minutes. The Decr Pool Size attribute of the Connecting to the Oracle Database Features of Oracle Data Provider for .NET 3-5 ConnectionString provides connection pooling service for the maximum number of connections that can be closed in one run. Operating System Authentication The Oracle Database can use Windows user login credentials to authenticate database users. To open a connection using Windows user login credentials, the User Id ConnectionString attribute must be set to /. If Password is provided, it is ignored. /* Create an OS-authenticated user in the database Assume init.ora does not have OS_AUTHENT_PREFIX set & a local OS user called 'FooUser' exists with the password 'FooUser': create user OPS$FooUser identified by FooUser; grant connect, resource to OPS$FooUser; Login as FooUsers and execute the sample See documentation for details on how to configure an OS-Authenticated user */ // C# using System; using Oracle.DataAccess.Client; class OSAuthenticationSample { static void Main() { OracleConnection con = new OracleConnection(); //Establish connection using OS Authentication con.ConnectionString = "User Id=/;Data Source=oracle;"; con.Open(); Console.WriteLine("Connected to Oracle" + con.ServerVersion); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } Privileged Connections Oracle allows database administrators to connect to an Oracle Database with either SYSDBA or SYSOPER privileges. This is done through the DBA Privilege attribute of the ConnectionString. The following example connects SYS/SYS as SYSDBA: // C# using System; using Oracle.DataAccess.Client; See Also: Oracle Database Platform Guide for Windows for information on how to set up an Oracle Database to authenticate database users using Windows user login credentials Connecting to the Oracle Database 3-6 Oracle Data Provider for .NET Developer’s Guide class PrivilegedConnectionSample { static void Main() { OracleConnection con = new OracleConnection(); //Connect SYS/SYS as SYSDBA con.ConnectionString = "User Id=SYS;Password=SYS;" + "DBA Privilege=SYSDBA;Data Source=oracle;"; con.Open(); Console.WriteLine("Connected to Oracle" + con.ServerVersion); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } Password Expiration Oracle allows users' password to expire. ODP.NET lets applications handle the password expiration by providing a new method, OpenWithNewPassword, that opens the connection with a new password. The following code snippet uses the OracleConnection OpenWithNewPassword method to connect with a new password of panther: /* Database Setup connect / as sysdba; drop user testexpire cascade; -- create user "testexpire" with password "testexpire" grant connect , resource to testexpire identified by testexpire; alter user testexpire password expire; */ // C# using System; using Oracle.DataAccess.Client; class PasswordExpirationSample { static void Main() { OracleConnection con = new OracleConnection(); try { con.ConnectionString = "User Id=testexpire;Password=testexpire;Data Source=oracle"; con.Open(); Console.WriteLine("Connected to Oracle" + con.ServerVersion); } catch (OracleException ex) { Console.WriteLine(ex.Message); See Also: "DBA Privilege" on page 4-64 for further information on privileged connections in the database Connecting to the Oracle Database Features of Oracle Data Provider for .NET 3-7 //check the error number //ORA-28001 : the password has expired if (ex.Number == 28001) { Console.WriteLine("\nChanging password to panther"); con.OpenWithNewPassword("panther"); Console.WriteLine("Connected with new password."); } } finally { // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } } Proxy Authentication The Oracle Database allows a middle-tier server to connect to proxy clients in a secure fashion. In multitier environments, proxy authentication allows control of middle-tier application security by preserving client identities and privileges through all tiers, and by auditing actions taken on behalf of clients. The proxy authentication feature allows the identity of a user (user id and password) using a Web application to be passed through the application to the database server. ODP.NET supports proxy authentication with or without a client password by providing the Proxy User Id and Proxy Password attributes of the ConnectionString property. /* Create a proxy user and modified scott to allow proxy connection: create user appserver identified by eagle; grant connect, resource to appserver; alter user scott grant connect through appserver; */ // C# using System; using Oracle.DataAccess.Client; class ProxyAuthenticationSample { static void Main() { OracleConnection con = new OracleConnection(); // Connecting using proxy authentication Note: OpenWithNewPassword should only be used when the user password has expired, not for changing the password. See Also: "OpenWithNewPassword" on page 4-80 for further information on connecting after the password expires Connecting to the Oracle Database 3-8 Oracle Data Provider for .NET Developer’s Guide con.ConnectionString = "User Id=scott;Password=tiger;" + "Data Source=oracle;Proxy User Id=appserver;Proxy Password=eagle; "; con.Open(); Console.WriteLine("Connected to Oracle" + con.ServerVersion); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } Transparent Application Failover (TAF) Callback Support Transparent Application Failover (TAF) is a feature in the Oracle Database that provides high availability. TAF enables an application connection to automatically reconnect to a database if the connection fails. Active transactions roll back, but the new database connection, made by way of a different node, is identical to the original. This is true regardless of how the connection fails. With Transparent Application Failover, a client notices no loss of connection as long as there is one instance left serving the application. The database administrator controls which applications run on which instances and also creates a failover order for each application. TAF Notification Given the delays that failovers can cause, applications may wish to be notified by a TAF callback. ODP.NET supports TAF callback through the Failover event of the OracleConnection object, which allows applications to be notified whenever a failover occurs. To receive TAF callbacks, an event handler function must be registered with the Failover event. When Failover Occurs When a failover occurs, the Failover event is raised and the registered event handler is invoked several times during the course of reestablishing the connection to another Oracle instance. The first call to the event handler occurs when the Oracle Database first detects an instance connection loss. This allows the application to act accordingly for the upcoming delay for the failover. If the failover is successful, the Failover event is raised again when the connection is reestablished and usable. At this time, the application can resynchronize the OracleGlobalization session setting and inform the application user that a failover has occurred. See Also: ■ Oracle Database Application Developer's Guide - Fundamentals for details on designing a middle-tier server using proxy users ■ Oracle Database SQL Reference for the description and syntax of the proxy clause for ALTER USER ■ Oracle Database Administrator's Guide section "Auditing in a Multi-Tier Environment" Connecting to the Oracle Database Features of Oracle Data Provider for .NET 3-9 If failover is unsuccessful, the Failover event is raised to inform the application that a failover did not take place. The application can determine whether or not the failover is successful by checking the OracleFailoverEventArgs that is passed to the event handler. Registering an Event Handler for Failover The following code example registers an event handler method called OnFailover: // C# using System; using Oracle.DataAccess.Client; class TAFCallBackSample { public static FailoverReturnCode OnFailover(object sender, OracleFailoverEventArgs eventArgs) { switch (eventArgs.FailoverEvent) { case FailoverEvent.Begin : Console.WriteLine( " \nFailover Begin - Failing Over ... Please standby \n"); Console.WriteLine( " Failover type was found to be " + eventArgs.FailoverType); break; case FailoverEvent.Abort : Console.WriteLine(" Failover aborted. Failover will not take place.\n"); break; case FailoverEvent.End : Console.WriteLine(" Failover ended ...resuming services\n"); break; case FailoverEvent.Reauth : Console.WriteLine(" Failed over user. Resuming services\n"); break; case FailoverEvent.Error : Console.WriteLine(" Failover error gotten. Sleeping...\n"); return FailoverReturnCode.Retry; default : Console.WriteLine("Bad Failover Event: %d.\n", eventArgs.FailoverEvent); break; } return FailoverReturnCode.Success; } /* OnFailover */ static void Main() { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); con.Failover += new OracleFailoverEventHandler(OnFailover); Console.WriteLine("Event Handler is successfully registered"); OracleCommand Object 3-10 Oracle Data Provider for .NET Developer’s Guide // Close and Dispose OracleConnection object con.Close(); con.Dispose(); } } The Failover event only invokes one event handler. If multiple Failover event handlers are registered with the Failover event, only the event handler registered last is invoked. OracleCommand Object The OracleCommand object represents SQL statements or stored procedures executed on the Oracle Database. This section includes the following topics: ■ Transaction ■ Parameter Binding ■ Statement Caching Transaction The Oracle Database starts a transaction only in the context of a connection. Once a transaction starts, all the successive command execution on that connection run in the context of that transaction. Transactions can only be started on a OracleConnection object and the read-only Transaction property on the OracleCommand object is implicitly set by the OracleConnection object. Therefore, the application cannot set the Transaction property, nor does it need to. Parameter Binding ODP.NET allows applications to retrieve data as either a .NET Framework type or an ODP.NET type. How the data is retrieved depends on whether application sets the OUT parameter to the DbType property (.NET type) or OracleDbType property (ODP.NET type) of the OracleParameter. For example, if the output parameter is bound as an DbType.String, the output data is returned as a .NET String. On the other hand, if the parameter is bound as OracleDbType.Char, the output data is returned as OracleString type. When the DbType of an OracleParameter is set, the OracleDbType of the OracleParameter changes accordingly, and vice versa. The parameter set last prevails. Note: Distributed transactions are not supported in an environment where failover is enabled. See Also: ■ Oracle Net Services Administrator's Guide ■ "OracleFailoverEventHandler Delegate" on page 7-8 ■ "OracleFailoverEventArgs Class" on page 7-2 OracleCommand Object Features of Oracle Data Provider for .NET 3-11 Lastly, an application can simply bind the data and have ODP.NET infer both the DbType and OracleDbType from the .NET type of the parameter value. ODP.NET populates InputOutput, Output, and ReturnValue parameters with the Oracle data, through the execution of the following OracleCommand methods: ■ ExecuteReader ■ ExecuteNonQuery ■ ExecuteScalar An application should not bind a value for output parameters; it is the responsibility of ODP.NET to create the value object and populate the OracleParameter Value property with the object. This section describes the following: ■ Datatypes BINARY_FLOAT and BINARY_DOUBLE ■ OracleDbType Enumeration Type ■ Inference of DbType, OracleDbType, and .NET Types ■ PL/SQL Associative Array ■ Array Binding Datatypes BINARY_FLOAT and BINARY_DOUBLE Starting from Oracle Database 10g, the database supports two new native datatypes, BINARY_FLOAT and BINARY_DOUBLE. BINARY_FLOAT and BINARY_DOUBLE datatypes represent single-precision and double-precision floating point values respectively. In OracleParameter binding, an application should use the enumerations OracleDbType.Float and OracleDbType.Double for BINARY_FLOAT and BINARY_DOUBLE datatypes. OracleDbType Enumeration Type OracleDbType enumerated values are used to explicitly specify the OracleDbType of an OracleParameter. Table 3–2 lists all the OracleDbType enumeration values with a description of each enumerated value. See Also: "OracleDbType Enumeration" on page 4-282 See Also: ■ "GetDouble" on page 4-130 ■ "GetFloat" on page 4-131 Table 3–2 OracleDbType Enumeration Values Member Name Description BFile Oracle BFILE type Blob Oracle BLOB type Byte byte type Char Oracle CHAR type OracleCommand Object 3-12 Oracle Data Provider for .NET Developer’s Guide Inference of DbType, OracleDbType, and .NET Types This section explains the inference from the System.Data.DbType, OracleDbType, and Value properties in the OracleParameter class. In the OracleParameter class, DbType, OracleDbType, and Value properties are linked. Specifying the value of any of these properties infers the value of one or more of the other properties. Inference of DbType from OracleDbType In the OracleParameter class, specifying the value of OracleDbType infers the value of DbType as shown in Table 3–3. Clob Oracle CLOB type Date Oracle DATE type Decimal Oracle NUMBER type Double 8-byte FLOAT type Int16 2-byte INTEGER type Int32 4-byte INTEGER type Int64 8-byte INTEGER type IntervalDS Oracle INTERVAL DAY TO SECOND type IntervalYM Oracle INTERVAL YEAR TO MONTH type Long Oracle LONG type LongRaw Oracle LONG RAW type NChar Oracle NCHAR type NClob Oracle NCLOB type NVarchar2 Oracle NVARCHAR2 type Raw Oracle RAW type RefCursor Oracle REF CURSOR type Single 4-byte FLOAT type TimeStamp Oracle TIMESTAMP type TimeStampLTZ Oracle TIMESTAMP WITH LOCAL TIME ZONE type TimeStampTZ Oracle TIMESTAMP WITH TIME ZONE type Varchar2 Oracle VARCHAR2 type XmlType Oracle XMLType type Table 3–3 Inference of System.Data.DbType from OracleDbType OracleDbType System.Data.DbType BFile Object Blob Object Byte Byte Char StringFixedLength Clob Object Table 3–2 (Cont.) OracleDbType Enumeration Values Member Name Description OracleCommand Object Features of Oracle Data Provider for .NET 3-13 Inference of OracleDbType from DbType In the OracleParameter class, specifying the value of DbType infers the value of OracleDbType as shown in Table 3–4. Date Date Decimal Decimal Double Double Int16 Int16 Int32 Int32 Int64 Int64 IntervalDS TimeSpan IntervalYM Int64 Long String LongRaw Binary NChar StringFixedLength NClob Object NVarchar2 String Raw Binary RefCursor Object Single Single TimeStamp DateTime TimeStampLTZ DateTime TimeStampTZ DateTime Varchar2 String XmlType String Table 3–4 Inference of OracleDbType from DbType System.Data.DbType OracleDbType Binary Raw Boolean Not Supported Byte Byte Currency Not Supported Date Date DateTime TimeStamp Decimal Decimal Double Double Guid Not Supported Int16 Int16 Int32 Int32 Table 3–3 (Cont.) Inference of System.Data.DbType from OracleDbType OracleDbType System.Data.DbType OracleCommand Object 3-14 Oracle Data Provider for .NET Developer’s Guide Inference of DbType and OracleDbType from Value In the OracleParameter class, Value is an object type which can be of any .NET Framework datatype or ODP.NET type. If the OracleDbType and DbType in the OracleParameter object are not specified, OracleDbType is inferred from the type of the Value property. Table 3–5 shows the inference of DbType and OracleDbType from Value when the type of Value is one of the .NET Framework datatypes. Int64 Int64 Object Not Supported Sbyte Not Supported Single Single String Varchar2 StringFixedLength Char Time TimeStamp UInt16 Not Supported UInt32 Not Supported Uint64 Not Supported VarNumeric Not Supported Table 3–5 Inference of DbType and OracleDbType from Value (.NET Datatypes) Value (.NET Datatypes) System.Data.DbType OracleDbType Byte Byte Byte Byte[] Binary Raw Char / Char [] String Varchar2 DateTime DateTime TimeStamp Decimal Decimal Decimal Double Double Double Float Single Single Int16 Int16 Int16 Int32 Int32 Int32 Int64 Int64 Int64 Single Single Single String String Varchar2 TimeSpan TimeSpan IntervalDS Note: Using other .NET Framework datatypes as values for OracleParameter without specifying either the DbType or the OracleDbType raises an exception because inferring DbType and OracleDbType from other .NET Framework datatypes is not supported. Table 3–4 (Cont.) Inference of OracleDbType from DbType System.Data.DbType OracleDbType OracleCommand Object Features of Oracle Data Provider for .NET 3-15 Table 3–6 shows the inference of DbType and OracleDbType from Value when type of Value is one of Oracle.DataAccess.Types. PL/SQL Associative Array ODP.NET supports PL/SQL Associative Array (formerly known as PL/SQL Index-By Tables) binding. An application can bind an OracleParameter, as a PL/SQL Associative Array, to a PL/SQL stored procedure. The following OracleParameter properties are used for this feature. ■ CollectionType This property must be set to OracleCollectionType.PLSQLAssociativeArray to bind a PL/SQL Associative Array. ■ ArrayBindSize This property is ignored for the fixed-length element types (such as Int32). For variable-length element types (such as Varchar2), each element in the ArrayBindSize property specifies the size of the corresponding element in the Value property. For Output parameters, InputOutput parameters, and return values, this property must be set for variable-length variables. ■ ArrayBindStatus This property specifies the execution status of each element in the OracleParameter.Value property. ■ Size This property specifies the maximum number of elements to be bound in the PL/SQL Associative Array. Table 3–6 Inference of DbType and OracleDbType from Value (ODP.NET Types) Value (Oracle.DataAccess.Types) System.Data.DbType OracleDbType OracleBFile Object BFile OracleBinary Binary Raw OracleBlob Object Blob OracleClob Object Clob OracleDate Date Date OracleDecimal Decimal Decimal OracleIntervalDS Object IntervalDS OracleIntervalYM Int64 IntervalYM OracleRefCursor Object RefCursor OracleString String Varchar2 OracleTimeStamp DateTime TimeStamp OracleTimeStampLTZ DateTime TimeStampLTZ OracleTimeStampTZ DateTime TimeStampTZ OracleXmlType String XmlType OracleCommand Object 3-16 Oracle Data Provider for .NET Developer’s Guide ■ Value This property must either be set to an array of values or null or DBNull.Value. Code Example This example binds three OracleParameter objects as PL/SQL Associative Arrays: Param1 as an In parameter, Param2 as an InputOutput parameter, and Param3 as an Output parameter. PL/SQL Package: MYPACK /* Setup the tables and required PL/SQL: CREATE TABLE T1(COL1 number, COL2 varchar2(20)); CREATE or replace PACKAGE MYPACK AS TYPE AssocArrayVarchar2_t is table of VARCHAR(20) index by BINARY_INTEGER; PROCEDURE TestVarchar2( Param1 IN AssocArrayVarchar2_t, Param2 IN OUT AssocArrayVarchar2_t, Param3 OUT AssocArrayVarchar2_t); END MYPACK; CREATE or REPLACE package body MYPACK as PROCEDURE TestVarchar2( Param1 IN AssocArrayVarchar2_t, Param2 IN OUT AssocArrayVarchar2_t, Param3 OUT AssocArrayVarchar2_t) IS i integer; BEGIN -- copy a few elements from Param2 to Param1\n Param3(1) := Param2(1); Param3(2) := NULL; Param3(3) := Param2(3); -- copy all elements from Param1 to Param2\n Param2(1) := Param1(1); Param2(2) := Param1(2); Param2(3) := Param1(3); -- insert some values to db\n FOR i IN 1..3 LOOP insert into T1 values(i,Param2(i)); END LOOP; END TestVarchar2; END MYPACK; */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class AssociativeArraySample { static void Main() { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle"; con.Open(); OracleCommand Object Features of Oracle Data Provider for .NET 3-17 Console.WriteLine("Connected to Oracle" + con.ServerVersion); OracleCommand cmd = new OracleCommand( "begin MyPack.TestVarchar2(:1, :2, :3); end;", con); OracleParameter Param1 = cmd.Parameters.Add("1", OracleDbType.Varchar2); OracleParameter Param2 = cmd.Parameters.Add("2", OracleDbType.Varchar2); OracleParameter Param3 = cmd.Parameters.Add("3", OracleDbType.Varchar2); Param1.Direction = ParameterDirection.Input; Param2.Direction = ParameterDirection.InputOutput; Param3.Direction = ParameterDirection.Output; // Specify that we are binding PL/SQL Associative Array Param1.CollectionType = OracleCollectionType.PLSQLAssociativeArray; Param2.CollectionType = OracleCollectionType.PLSQLAssociativeArray; Param3.CollectionType = OracleCollectionType.PLSQLAssociativeArray; // Setup the values for PL/SQL Associative Array Param1.Value = new string[3] { "First Element", "Second Element ", "Third Element " }; Param2.Value = new string[3] { "First Element", "Second Element ", "Third Element " }; Param3.Value = null; // Specify the maximum number of elements in the PL/SQL Associative Array Param1.Size = 3; Param2.Size = 3; Param3.Size = 3; // Setup the ArrayBindSize for Param1 Param1.ArrayBindSize = new int[3] { 13, 14, 13 }; // Setup the ArrayBindStatus for Param1 Param1.ArrayBindStatus = new OracleParameterStatus[3] { OracleParameterStatus.Success, OracleParameterStatus.Success, OracleParameterStatus.Success}; // Setup the ArrayBindSize for Param2 Param2.ArrayBindSize = new int[3] { 20, 20, 20 }; // Setup the ArrayBindSize for Param3 Param3.ArrayBindSize = new int[3] { 20, 20, 20 }; // execute the cmd cmd.ExecuteNonQuery(); //print out the parameter's values Console.WriteLine("parameter values after executing the PL/SQL block"); for (int i = 0; i < 3; i++) Console.WriteLine("Param2[{0}] = {1} ", i, (cmd.Parameters[1].Value as Array).GetValue(i)); for (int i = 0; i < 3; i++) Console.WriteLine("Param3[{0}] = {1} ", i, (cmd.Parameters[2].Value as Array).GetValue(i)); // Close and Dispose OracleConnection object OracleCommand Object 3-18 Oracle Data Provider for .NET Developer’s Guide con.Close(); con.Dispose(); Console.WriteLine("Disconnected"); } } Array Binding The array bind feature enables applications to bind arrays of a type using the OracleParameter class. Using the array bind feature, an application can insert multiple rows into a table in a single database round-trip. The following code example inserts three rows into the Dept table with a single database round-trip. The OracleCommand ArrayBindCount property defines the number of elements of the array to use when executing the statement. // C# using System; using System.Data; using Oracle.DataAccess.Client; class ArrayBindSample { static void Main() { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); Console.WriteLine("Connected successfully"); int[] myArrayDeptNo = new int[3] { 10, 20, 30 }; OracleCommand cmd = new OracleCommand(); // Set the command text on an OracleCommand object cmd.CommandText = "insert into dept(deptno) values (:deptno)"; cmd.Connection = con; // Set the ArrayBindCount to indicate the number of values cmd.ArrayBindCount = 3; // Create a parameter for the array operations OracleParameter prm = new OracleParameter("deptno", OracleDbType.Int32); prm.Direction = ParameterDirection.Input; prm.Value = myArrayDeptNo; // Add the parameter to the parameter collection cmd.Parameters.Add(prm); // Execute the command cmd.ExecuteNonQuery(); Console.WriteLine("Insert Completed Successfully"); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); } } OracleCommand Object Features of Oracle Data Provider for .NET 3-19 OracleParameter Array Bind Properties The OracleParameter object provides two properties for granular control when using the array bind feature: ■ ArrayBindSize Property The ArrayBindSize property is an array of integers specifying the maximum size for each corresponding value in an array. The ArrayBindSize property is similar to the Size property of an OracleParameter except ArrayBindSize specifies the size for each value in an array. Before the execution, the application must populate ArrayBindSize; after the execution, ODP.NET populates the ArrayBindSize. ArrayBindSize is used only for parameter types that have variable length such as Clob, Blob and Varchar2. The size is represented in bytes for binary datatypes and characters for the Unicode string types. The count for string types does not include the terminating character. The size is inferred from the actual size of the value, if it is not explicitly set. For an output parameter, the size of each value is set by ODP.NET. The ArrayBindSize property is ignored for fixed length datatypes. ■ ArrayBindStatus Property The ArrayBindStatus property is an array of OracleParameterStatus values specifying status of each corresponding value in an array for a parameter. This property is similar to the Status property of OracleParameter, except that ArrayBindStatus specifies the status for each value in an array. Before the execution, the application must populate the ArrayBindStatus property and after the execution, ODP.NET populates it. Before the execution, an application using ArrayBindStatus can specify a NULL value for the corresponding element in the array for a parameter. After the execution, ODP.NET populates the ArrayBindStatus array, indicating whether the corresponding element in the array has a NULL value or if data truncation occurred when the value was fetched. Error Handling for Array Binding If an error occurs during an Array Bind execution, it can be difficult to determine which element in the Value property caused the error. ODP.NET provides a way to determine the row where the error occurred, making it easier to find the element in the row that caused the error. When an OracleException is thrown during an Array Bind execution, the OracleErrorCollection contains one or more OracleError objects. Each of these OracleError objects represents an individual error that occurred during the execution and contains a provider-specific property, ArrayBindIndex, which indicates the row number at which the error occurred. /* Database Setup drop table depttest; create table depttest(deptno number(2)); */ // C# using System; using System.Data; using Oracle.DataAccess.Client; See Also: "Value" on page 4-221 for more information OracleCommand Object 3-20 Oracle Data Provider for .NET Developer’s Guide class ArrayBindExceptionSample { static void Main() { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); OracleCommand cmd = new OracleCommand(); // Start a transaction OracleTransaction txn = con.BeginTransaction(IsolationLevel.ReadCommitted); try { int[] myArrayDeptNo = new int[3] { 10, 200000, 30 }; // int[] myArrayDeptNo = new int[3]{ 10,20,30}; // Set the command text on an OracleCommand object cmd.CommandText = "insert into depttest(deptno) values (:deptno)"; cmd.Connection = con; // Set the ArrayBindCount to indicate the number of values cmd.ArrayBindCount = 3; // Create a parameter for the array operations OracleParameter prm = new OracleParameter("deptno", OracleDbType.Int32); prm.Direction = ParameterDirection.Input; prm.Value = myArrayDeptNo; // Add the parameter to the parameter collection cmd.Parameters.Add(prm); // Execute the command cmd.ExecuteNonQuery(); } catch (OracleException e) { Console.WriteLine("OracleException {0} occured", e.Message); if (e.Number == 24381) for (int i = 0; i < e.Errors.Count; i++) Console.WriteLine("Array Bind Error {0} occured at Row Number {1}", e.Errors[i].Message, e.Errors[i].ArrayBindIndex); txn.Commit(); } cmd.Parameters.Clear(); cmd.CommandText = "select count(*) from depttest"; decimal rows = (decimal)cmd.ExecuteScalar(); Console.WriteLine("{0} row have been inserted", rows); con.Close(); con.Dispose(); } } See Also: "ArrayBindIndex" on page 4-166 for more information OracleCommand Object Features of Oracle Data Provider for .NET 3-21 OracleParameterStatus Enumeration Types Table 3–7 provides different values for OracleParameterStatus enumeration. Statement Caching Statement caching eliminates the need to parse each SQL or PL/SQL statement before the execution by caching server cursors created from its initial execution. Subsequent executions of the same statement (possibly with different parameter values) can reuse the parsed information from the cursor and execute the statement without parsing for better performance. It is recommended that only those statements that will be repeatedly executed be cached to see performance gains from statement caching. Furthermore, SQL or PL/SQL statements should use parameters rather than using literal values. This is because when statement caching is enabled, parameterized statements that have already been prepared can be re-used for subsequent executions of the same statement with different parameter values. Statement Caching Connection String Attributes The following connection string attributes control the behavior of the ODP.NET statement caching feature: ■ Statement Cache Size This attribute enables or disables ODP.NET Statement Caching. By default, this attribute is set to 0 and ODP.NET Statement Caching is disabled. If is set to a value greater than 0, ODP.NET Statement Caching is enabled and the value specified is used as maximum number of statements that can be cached for a connection. Once a connection has cached up to the specified maximum cache size, the least recently used cursor is freed to make room to cache the newly created cursor. ■ Statement Cache Purge This attribute provides a way for connections to purge all statements that are cached when a connection is closed or placed back into the connection pool. By default, this attribute is set to False, which means that cursors are not freed when connections are placed back into the pool. Statement Caching Methods and Properties The following method and property are only relevant when Statement Caching is enabled: ■ OracleCommand.AddToStatementCache property Table 3–7 OracleParameterStatus Members Member Names Description Success For input parameters, it indicates that the input value has been assigned to the column. For output parameters, it indicates that the provider assigned an intact value to the parameter. NullFetched Indicates that a NULL value has been fetched from a column or an OUT parameter. NullInsert Indicates that a NULL value is to be inserted into a column. Truncation Indicates that truncation has occurred when fetching the data from the column. ODP.NET Types Overview 3-22 Oracle Data Provider for .NET Developer’s Guide If statement caching is enabled, having this property set to True adds statements to the cache when they are executed. If statement caching is disabled or if this property is set to False, the executed statement is not cached. By default, this property is set to True. ■ OracleConnection.PurgeStatementCache method This method purges all the cached statements by closing all open cursors on the server that are associated with the particular connection. Note that statement caching remains enabled after this call. Connections and Statement Caching Statement caching is managed separately for each connection. Therefore, executing the same statement on different connections requires parsing once for each connection and caching a separate cursor for each connection. Pooling and Statement Caching Pooling and statement caching can be used in conjunction. If connection pooling is enabled and Statement Change Purge is set to False, statements executed on each separate connection are cached throughout the lifetime of the pooled connection. If Statement Cache Purge is set to True, all the cached cursors are freed when the connection is placed back into the pool. When connection pooling is disabled, cursors are cached during the lifetime of the connection, but the cursors are closed when the OracleConnection object is closed or disposed. ODP.NET Types Overview ODP.NET types represent Oracle native types as a structure or as a class. ODP.NET type structures follow value semantics while ODP.NET type classes follow reference semantics. ODP.NET types provide safer and more efficient ways of obtaining Oracle native data in a .NET application than .NET types. For example, an OracleDecimal holds up to 38 precisions while a .NET Decimal holds only up to 28 precisions. Table 3–8 lists all the Oracle native types supported by ODP.NET and their corresponding ODP.NET type. The third column lists the .NET Framework datatype that corresponds to the Value property of each ODP.NET Type. Table 3–8 Value Property Type of ODP.NET Type Oracle Native Type ODP.NET Type .NET Framework Datatypes BFILE OracleBFile class System.Byte[] BLOB OracleBlob class System.Byte[] CHAR OracleString structure System.String CLOB OracleClob class System.String DATE OracleDate structure System.DateTime INTERVAL DAY TO SECOND OracleIntervalDS structure System.TimeSpan INTERVAL YEAR TO MONTH OracleIntervalYM structure System.Int64 LONG OracleString structure System.String LONG RAW OracleBinary structure System.Byte[] Obtaining Data From an OracleDataReader Features of Oracle Data Provider for .NET 3-23 Obtaining Data From an OracleDataReader The ExecuteReader method of the OracleCommand object returns an OracleDataReader object, which is a read-only, forward-only result set. This section provides the following information about the OracleDataReader: ■ Typed OracleDataReader Accessors ■ Obtaining LONG and LONG RAW Data ■ Obtaining LOB Data ■ Controlling the Number of Rows Fetched in One Server Round-Trip Typed OracleDataReader Accessors The OracleDataReader provides two types of typed accessors: ■ .NET Type Accessors ■ ODP.NET Type Accessors .NET Type Accessors Table 3–9 lists all the Oracle native database types that ODP.NET supports and the corresponding .NET Types that can represents the Oracle native type. If more than one .NET Type can be used to represent an Oracle native type, the first entry is the .NET Type that best represents the Oracle native type. The third column indicates the valid typed accessor that can be invoked for an Oracle native type to be obtained as a .NET type. If an invalid typed accessor is used for a column, an InvalidCastException is thrown. Oracle native datatypes depend on the version of the database; therefore, some datatypes are not available in earlier versions of Oracle Database. NCLOB OracleClob class System.String NCHAR OracleString structure System.String NUMBER OracleDecimal structure System.Decimal NVARCHAR2 OracleString structure System.String RAW OracleBinary structure System.Byte[] REF CURSOR OracleRefCursor class Not Applicable TIMESTAMP OracleTimeStamp structure System.DateTime TIMESTAMP WITH LOCAL TIME ZONE OracleTimeStampLTZ structure System.DateTime TIMESTAMP WITH TIME ZONE OracleTimeStampTZ structure System.DateTime UROWID OracleString structure System.String VARCHAR2 OracleString structure System.String XMLType OracleXmlType class System.String Table 3–8 (Cont.) Value Property Type of ODP.NET Type Oracle Native Type ODP.NET Type .NET Framework Datatypes Obtaining Data From an OracleDataReader 3-24 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "OracleDataAdapter Class" on page 4-86 ■ "OracleDataReader Class" on page 4-109 Table 3–9 .NET Type Accessors Oracle Native Datatype .NET Type Typed Accessor BFILE System.Byte[] GetBytes BINARY_DOUBLE System.Double GetDouble BINARY_FLOAT System.Single GetFloat BLOB System.Byte[] GetBytes CHAR System.String System.Char[] GetString GetChars CLOB System.String System.Char[] GetString GetChars DATE System.DateTime GetDateTime INTERVAL(DS) System.Timespan GetTimeSpan INTERVAL (YM) System.Int64 GetInt64 LONG System.String System.Char[] GetString GetChars LONG RAW System.Byte[] GetBytes NCHAR System.String System.Char[] GetString GetChars NCLOB System.String System.Char[] GetString GetChars NUMBER System.Decimal System.Byte System.Int16 System.Int32 System.Int64 System.Single System.Double GetDecimal GetByte GetInt16 GetInt32 GetInt64 GetFloat GetDouble NVARCHAR2 System.String System.Char[] GetString GetChars RAW System.Byte[] GetBytes ROWID System.String System.Char[] GetString GetChars TIMESTAMP System.DateTime GetDateTime TIMESTAMP WITH LOCAL TIME ZONE System.DateTime GetDateTime TIMESTAMP WITH TIME ZONE System.DateTime GetDateTime UROWID System.String System.Char[] GetString GetChars Obtaining Data From an OracleDataReader Features of Oracle Data Provider for .NET 3-25 Certain methods and properties of the OracleDataReader require ODP.NET to map a NUMBER column to a .NET type based on the precision and scale of the column. These members are: ■ Item Property ■ GetFieldType Method ■ GetValue Method ■ GetValues Method ODP.NET determines the appropriate .NET type by considering the following .NET types in order and selecting the first .NET type from the list that can represent the entire range of values of the column. ■ System.Byte ■ System.Int16 ■ System.Int32 ■ System.Int64 ■ System.Single ■ System.Double ■ System.Decimal If no .NET type exists that can represent the entire range of values of the column, then an attempt is made to represent the column values as a System.Decimal. If the value in the column cannot be represented as System.Decimal, then an exception is raised. For example, consider two columns defined as NUMBER(4,0) and NUMBER(10,2). The first .NET types from the previous list that can represent the entire range of values of the columns are System.Int16 and System.Double, respectively. However, consider a column defined as NUMBER(20,10). In this case, there is no .NET type that can represent the entire range of values on the column, so an attempt is made to return values in the column as a System.Decimal. If a value in the column cannot be represented as a System.Decimal, then an exception is raised. The Fill method of the OracleDataAdapter utilizes the OracleDataReader to populate or refresh a DataTable or DataSet with .NET types. As a result, the .NET type used to represent a NUMBER column in the DataTable or DataSet also depends on the precision and scale of the column. VARCHAR2 System.String System.Char[] GetString GetChars XMLType System.String System.Xml.XmlReader GetString GetXmlReader Table 3–9 (Cont.) .NET Type Accessors Oracle Native Datatype .NET Type Typed Accessor Obtaining Data From an OracleDataReader 3-26 Oracle Data Provider for .NET Developer’s Guide ODP.NET Type Accessors ODP.NET exposes provider-specific types that natively represent the datatypes in the database. In some cases, these ODP.NET types provide better performance and functionality that is not available to the corresponding .NET types. The ODP.NET types can be obtained from the OracleDataReader by calling their respective typed accessor. Table 3–10 lists the valid type accessors that ODP.NET uses to obtain ODP.NET Types for an Oracle native type. See Also: ■ "OracleDataReader Class" on page 4-109 ■ "OracleDataAdapter Class" on page 4-109 ■ "Item" on page 4-119 ■ "GetFieldType" on page 4-131 ■ "GetValues" on page 4-158 ■ "GetValue" on page 4-157 See Also: "ODP.NET Types Overview" on page 3-22 for a list of all ODP.NET types Table 3–10 ODP.NET Type Accessors Oracle Native Database Type ODP.NET Type Typed Accessor BFILE OracleBFile GetOracleBFile BLOB OracleBlob OracleBlob OracleBinary GetOracleBlob GetOracleBlobForUpdate GetOracleBinary CHAR OracleString GetOracleString CLOB OracleClob OracleClob OracleString GetOracleClob GetOracleClobForUpdate GetOracleString DATE OracleDate GetOracleDate INTERVAL (DS) OracleIntervalDS GetOracleIntervalDS INTERVAL (YM) OracleIntervalYM GetOracleIntervalYM LONG OracleString GetOracleString LONG RAW OracleBinary GetOracleBinary NCHAR OracleString GetOracleString NCLOB OracleString GetOracleString NUMBER OracleDecimal GetOracleDecimal NVARCHAR2 OracleString GetOracleString RAW OracleBinary GetOracleBinary ROWID OracleString GetOracleString Obtaining Data From an OracleDataReader Features of Oracle Data Provider for .NET 3-27 Obtaining LONG and LONG RAW Data When an OracleDataReader is created containing a LONG or LONG RAW column type, OracleDataReader determines whether this column data needs to be fetched immediately or not, by checking the value of the InitialLONGFetchSize property of the OracleCommand that created the OracleDataReader. By default, InitialLONGFetchSize is set to 0. If the InitialLONGFetchSize property value of the OracleCommand is left as 0, the entire LONG or LONG RAW data retrieval is deferred until that data is explicitly requested by the application. If the InitialLONGFetchSize property is set to a nonzero value, the LONG or LONG RAW data is immediately fetched up to the number of characters or bytes that the InitialLONGFetchSize property specifies. ODP.NET does not support CommandBehavior.SequentialAccess. Therefore, LONG and LONG RAW data can be fetched in a random fashion. To obtain data beyond InitialLONGFetchSize bytes or characters, one of the following must be in the select list: ■ primary key ■ ROWID ■ unique columns - (defined as a set of columns on which a unique constraint has been defined or a unique index has been created, where at least one of the columns in the set has a NOT NULL constraint defined on it) The requested data is fetched from the database when the appropriate typed accessor method (GetOracleString or GetString for LONG or GetOracleBinary or GetBytes for LONG RAW) is called on the OracleDataReader object. In order to fetch the data in a non-defer mode or when the columns in the select list do not have a primary key column, a ROWID, or unique columns, set the size of the InitialLONGFetchSize property on the OracleCommand object to equal or greater than the amount of bytes or characters needed to be retrieved. Obtaining LOB Data When an OracleDataReader is created containing LOB column types, OracleDataReader determines whether the LOB column data needs to be fetched immediately or not by checking the value of the InitialLONGFetchSize property of the OracleCommand that created the OracleDataReader. By default, InitialLOBFetchSize is set to 0. If the InitialLOBFetchSize property value of TIMESTAMP OracleTimeStamp GetOracleTimeStamp TIMESTAMP WITH LOCAL TIME ZONE OracleTimeStampLTZ GetOracleTimeStampLTZ TIMESTAMP WITH TIME ZONE OracleTimeStampTZ GetOracleTimeStampTZ UROWID OracleString GetOracleString VARCHAR2 OracleString GetOracleString XMLType OracleString OracleXmlType GetOracleString GetOracleXmlType Table 3–10 (Cont.) ODP.NET Type Accessors Oracle Native Database Type ODP.NET Type Typed Accessor Obtaining Data From an OracleDataReader 3-28 Oracle Data Provider for .NET Developer’s Guide the OracleCommand is left as 0, the entire LOB data retrieval is deferred until that data is explicitly requested by the application. If the InitialLOBFetchSize property is set to a nonzero value, the LOB data is immediately fetched up to the number of characters or bytes that the InitialLOBFetchSize property specifies. By default, when InitialLOBFetchSize property is 0, GetOracleBlob() and GetOracleClob() can be invoked on the OracleDataReader to obtain OracleBlob and OracleClob objects. However, if the InitialLOBFetchSize is set to a nonzero value, GetOracleBlob() and GetOracleClob() methods are disabled. In this scenario, the BLOB and CLOB data needs to be fetched by using GetBytes() and GetChars(), respectively. Methods Supported or Not Supported for InitialLOBFetchSize Table 3–11 and Table 3–12 list supported and not supported methods for the CLOB and BLOB datatypes when the OracleCommand InitialLOBFetchSize property is set to a nonzero value. LOB Data Fetching Considerations ODP.NET does not support CommandBehavior.SequentialAccess. Therefore, LOB data can be fetched in a random fashion. To obtain data beyond InitialLOBFetchSize bytes or characters, one of the following must be in the select list: ■ primary key ■ ROWID ■ unique columns - (defined as a set of columns on which a unique constraint has been defined or a unique index has been created, where at least one of the columns in the set has a NOT NULL constraint defined on it) The requested data is fetched from the database when the appropriate typed accessor method is called on the OracleDataReader object. Note that the primary key column is not required if InitialLOBFetchSize is set to 0. Table 3–11 OracleDataReader CLOB Methods Supported Not Supported GetChars GetOracleClob GetString GetOracleClobForUpdate GetValue GetOracleValue GetValues GetOracleValues GetOracleString Table 3–12 OracleDataReader BLOB Methods Supported Not Supported GetBytes GetOracleBlob GetValue GetOracleBlobForUpdate GetValues GetOracleValue GetOracleBinary GetOracleValues Obtaining Data From an OracleDataReader Features of Oracle Data Provider for .NET 3-29 In order to fetch the data in a non-defer mode or when the columns in the select list do not have a primary key column, a ROWID, or unique columns, set the size of the InitialLOBFetchSize property on the OracleCommand object to an amount equal to or greater than the bytes or characters that need to be retrieved. Performance Setting InitialLOBFetchSize to a nonzero value can improve performance in certain cases. Using InitialLOBFetchSize can provide better performance than retrieving the underlying LOB data using OracleBlob or OracleClob objects. This is true if an application does not need to obtain OracleBlob and OracleClob objects from the OracleDataReader and the size the LOB column data is not very large. InitialLOBFetchSize is particularly useful in cases where the size of the LOB column data returned by query is approximately the same for all the rows. It is generally recommended that InitialLOBFetchSize be set to a value larger than the size of the LOB data for more than 80% of the rows returned by the query. For example, if the size of the LOB data is less than 1 KB in 80% of the rows and more than 1 MB for 20% of the rows, set InitialLOBFetchSize to 1 KB. Controlling the Number of Rows Fetched in One Server Round-Trip Application performance depends on the number of rows the application needs to fetch and the number of database round-trips that are needed to retrieve them. Use of FetchSize The FetchSize property represents the total memory size in bytes that ODP.NET allocates to cache the data fetched from a server round-trip. The FetchSize property can be set either on the OracleCommand or the OracleDataReader depending on the situation. Additionally, the FetchSize property of the OracleCommand is inherited by the OracleDataReader and can be modified. If the FetchSize property is set on the OracleCommand, then the newly created OracleDataReader inherits the FetchSize property of the OracleCommand. This inherited FetchSize can be left as is or modified to override the inherited value. The FetchSize property of the OracleDataReader object can be changed before the first Read method invocation, which allocates memory specified by the FetchSize. All subsequent fetches from the database use the same cache allocated for that OracleDataReader. Therefore, changing the FetchSize after the first Read method invocation has no effect. Fine-Tuning FetchSize By fine-tuning the FetchSize property, applications can control memory usage and the number of rows fetched in one server round-trip for better performance. For example, if a query returns 100 rows and each row takes 1024 bytes, then setting FetchSize to 102400 takes just one server round-trip to fetch the hundred rows. For the same query, if the FetchSize is set to 10240, it takes 10 server round-trips to retrieve 100 rows. If the application requires all the rows to be fetched from the result See Also: ■ "LOB Support" on page 3-32 ■ "InitialLOBFetchSize" on page 4-17 ■ "InitialLONGFetchSize" on page 4-18 PL/SQL REF CURSOR and OracleRefCursor 3-30 Oracle Data Provider for .NET Developer’s Guide set, the first scenario is faster than the second. However, if the application requires just the first 10 rows from the result set, the second scenario can perform better since it only fetches 10 rows and not 100 rows. Using the RowSize Property The RowSize property of the OracleCommand object is populated with the row size (in bytes) after an execution of a SELECT statement. The FetchSize property can then be set to a value relative to the RowSize by setting it to the product of RowSize and the number of rows to fetch for each server round-trip. For example, setting the FetchSize to RowSize * 10 forces the OracleDataReader to fetch exactly 10 rows for each server round-trip. Note that the RowSize does not change due to the data length in each individual columns. Instead, the RowSize is determined strictly from the metadata information of the database table(s) that the SELECT is executed against. The RowSize property can be used to set the FetchSize at design time or at runtime as described in the following sections. Setting FetchSize Value at Design Time If the row size for a particular SELECT statement is already known from a previous execution, FetchSize of the OracleCommand can be set at design time to the product of that row size and the number of rows the application wishes to fetch for each server round-trip. The FetchSize value set on the OracleCommand object is inherited by the OracleDataReader that is created by the ExecuteReader method invocation on the OracleCommand. Rather than setting the FetchSize on the OracleCommand, the FetchSize can also be set on the OracleDataReader directly. In either case, the FetchSize is set at design time without accessing the RowSize property value at runtime. Setting FetchSize Value at Runtime Applications that do not know the row size at design time can use the RowSize property of the OracleCommand object to set the FetchSize property of the OracleDataReader object. The RowSize property provides a dynamic way of setting the FetchSize property based on the size of a row. After an OracleDataReader object is obtained by invoking the ExecuteReader method on the OracleCommand, the RowSize property is populated with the size of the row (in bytes). By using the RowSize property, the application can dynamically set the FetchSize property of the OracleDataReader to the product of the RowSize property value and the number of rows the application wishes to fetch for each server round-trip. In this scenario, the FetchSize is set by accessing the RowSize property at runtime. PL/SQL REF CURSOR and OracleRefCursor The REF CURSOR is a datatype in the Oracle PL/SQL language. It represents a cursor or a result set in the Oracle database. The OracleRefCursor is a corresponding ODP.NET type for the REF CURSOR type. This section discusses the following aspects of using REF CURSOR and OracleRefCursor objects: ■ Obtaining an OracleRefCursor ■ Obtaining a REF CURSOR ■ Populating an OracleDataReader from a REF CURSOR PL/SQL REF CURSOR and OracleRefCursor Features of Oracle Data Provider for .NET 3-31 ■ Populating the DataSet From a REF CURSOR ■ Populating an OracleRefCursor From a REF CURSOR ■ Updating a DataSet Obtained From a REF CURSOR ■ Behavior of ExecuteScalar Method for REF CURSOR Obtaining an OracleRefCursor There are no constructors for OracleRefCursor objects. They can only be acquired as parameter values from PL/SQL stored procedures, stored functions, or anonymous blocks. An OracleRefCursor is a connected object. The connection used to execute the command returning a OracleRefCursor object is required for its lifetime. Once the connection associated with an OracleRefCursor is closed, the OracleRefCursor cannot be used. Obtaining a REF CURSOR A REF CURSOR can be obtained as an OracleDataReader, DataSet, or OracleRefCursor. If the REF CURSOR is obtained as an OracleRefCursor object, it can be used to create an OracleDataReader or populate a DataSet from it. When accessing a REF CURSOR, always bind as a OracleDbType.RefCursor. Populating an OracleDataReader from a REF CURSOR An Oracle REF CURSOR can be obtained as an OracleDataReader by calling the OracleCommand ExecuteReader method. The output parameter with the OracleDbType property set is bound to OracleDbType.RefCursor. None of the output parameters of type OracleDbType.RefCursor are populated after the ExecuteReader is invoked. If there are multiple output REF CURSOR parameters, use the OracleDataReader NextResult method to access the next REF CURSOR. The OracleDataReader NextResult method provides sequential access to the REF CURSORs; only one REF CURSOR can be accessed at a given time. The order in which OracleDataReader objects are created for the corresponding REF CURSOR depends on the order in which the parameters are bound. If a PL/SQL stored function returns a REF CURSOR, then it becomes the first OracleDataReader and all the output REF CURSOR objects follow the order in which the parameters are bound. Populating the DataSet From a REF CURSOR For the Fill method to populate the DataSet properly, the SelectCommand of the OracleDataAdapter must be bound with an output parameter of type OracleDbType.RefCursor. If the Fill method is successful, the DataSet is populated with a DataTable that represents a REF CURSOR. If the command execution returns multiple REF CURSORs, the DataSet is populated with multiple DataTables. LOB Support 3-32 Oracle Data Provider for .NET Developer’s Guide Populating an OracleRefCursor From a REF CURSOR When ExecuteNonQuery is invoked on a command that returns one or more REF CURSORs, each of the OracleCommand parameters that are bound as OracleDbType.RefCursor gets a reference to an OracleRefCursor object. To create an OracleDataReader from an OracleRefCursor object, invoke GetDataReader from an OracleRefCursor object. Subsequent calls to GetDataReader return the reference to the same OracleDataReader. To populate a DataSet with an OracleRefCursor object, the application can invoke an OracleDataAdapter Fill method that takes an OracleRefCursor object. When multiple REF CURSORs are returned from a command execution as OracleRefCursor objects, the application can choose to create an OracleDataReader or populate a DataSet with a particular OracleRefCursor object. All the OracleDataReaders or DataSet created from the OracleRefCursor are active at the same time and can be accessed in any order. Updating a DataSet Obtained From a REF CURSOR REF CURSORs are not updatable. However, data that is retrieved into a DataSet can be updated. Therefore, the OracleDataAdapter requires a custom SQL statement to flush any REF CURSOR data updates to the database. The OracleCommandBuilder cannot be used to generate SQL for REF CURSOR updates. Behavior of ExecuteScalar Method for REF CURSOR ExecuteScalar returns the return value of a stored function or the first bind parameter of a stored procedure or an anonymous PL/SQL block. Therefore, if the REF CURSOR is not the return value of a stored function or the first bind parameter of a stored procedure or an anonymous PL/SQL block, the REF CURSOR is ignored by ExecuteScalar. However, if the REF CURSOR is a return value of a stored function or the first bind parameter of a stored procedure or an anonymous PL/SQL block, the value of the first column of the first row in the REF CURSOR is returned. LOB Support ODP.NET provides an easy and optimal way to access and manipulate large datatypes. This section includes the following topics: ■ Large Character and Large Binary Datatypes ■ Oracle Data Provider for .NET LOB Objects ■ Updating LOBs Using a DataSet ■ Updating LOBs Using OracleCommand and OracleParameter ■ Updating LOBs Using ODP.NET LOB Objects ■ Temporary LOBs See Also: Oracle Database Application Developer's Guide - Large Objects for more information LOB Support Features of Oracle Data Provider for .NET 3-33 Large Character and Large Binary Datatypes Oracle Database supports large character and large binary datatypes. Large Character Datatypes ■ CLOB - Character data can store up to 4 gigabytes (4 GB). ■ NCLOB - Unicode National character set data can store up to 4 gigabytes. Large Binary Datatypes ■ BLOB - Unstructured binary data can store up to 4 gigabytes. ■ BFILE - Binary data stored in external file can store up to 4 gigabytes. Oracle Data Provider for .NET LOB Objects ODP.NET provides three objects for LOBs for manipulating LOB data: OracleBFile, OracleBlob, and OracleClob. Table 3–13 shows the proper ODP.NET class to use for a particular Oracle LOB type. The ODP.NET LOB objects can be obtained by calling the proper typed accessor on the OracleDataReader or as an output parameter on a command execution with the proper bind type. All ODP.NET LOB objects inherit from the .NET Stream class to provide generic Stream operations. The LOB data (except for BFILEs) can be updated using the ODP.NET LOB objects by using methods such as Write. Data is not cached in the LOB objects when read and write operations are carried out. Therefore, each Read or Write request incurs a server round-trip. The OracleClob overloads the Read method, providing two ways to read data from a CLOB. The Read method that takes a byte[] as the buffer populates it with CLOB data as Unicode byte array. The Read method that takes a char[] as the buffer populates it with Unicode characters. Extensions can also be found on the OracleBFile object. An OracleBFile object must be explicitly opened using the OpenFile method before any data can be read from it. To close a previously opened BFILE, use the CloseFile method. Every ODP.NET LOB object is a connected object and requires a connection during its lifetime. If the connection associated with a LOB object is closed, then the LOB object is not usable and should be disposed. If an ODP.NET LOB object is obtained from an OracleDataReader through a typed accessor, then its Connection property is set with a reference to the same Note: LONG and LONG RAW datatypes are made available for backward compatibility in Oracle9i, but should not be used in new applications. Table 3–13 ODP.NET LOB Objects Oracle LOB Type ODP.NET LOB object BFILE OracleBFile object BLOB OracleBlob object CLOB OracleClob object NCLOB OracleClob object LOB Support 3-34 Oracle Data Provider for .NET Developer’s Guide OracleConnection object used by the OracleDataReader. If a LOB object is obtained as an output parameter, then its Connection property is set with a reference to the same OracleConnection property used by the OracleCommand. If a LOB object is obtained by invoking an ODP.NET LOB object constructor to create a temporary LOB, the Connection property is set with a reference to the OracleConnection object provided in the constructor. The ODP.NET LOB object Connection property is read-only and cannot be changed during its lifetime. In addition, the ODP.NET LOB types object can only be used within the context of the same OracleConnection referenced by the ODP.NET LOB object. For example, the ODP.NET LOB object's Connection must reference the same connection as the OracleCommand if the ODP.NET LOB object is a parameter of the OracleCommand. If that is not the case, ODP.NET raises an exception when the command is executed. Updating LOBs Using a DataSet BFILE and BLOB data are stored in the DataSet as byte arrays while CLOB and NCLOB data are stored as strings. In a similar manner to other types, an OracleDataAdapter object can be used to fill and update LOB data changes along with the use of the OracleCommandBuilder for auto-generating SQL. Note that an Oracle LOB column can store up to 4 GB of data. When the LOB data is fetched into the DataSet, the actual amount of LOB data the DataSet can hold for a LOB column is limited to the maximum size of a .NET string type, which is 2 GB. Therefore, when fetching LOB data that is greater than 2 GB, ODP.NET LOB objects must be used to avoid any data loss. Updating LOBs Using OracleCommand and OracleParameter To update LOB columns, LOB data can be bound as a parameter for SQL statements, anonymous PL/SQL blocks, or stored procedures. The parameter value can be set as a NET Framework type, ODP.NET type, or as an ODP.NET LOB object type. For example, when inserting a .NET string data into a LOB column in a Oracle9i database, that parameter can be bound as OracleDbType.Varchar2. For a parameter whose value is set to an OracleClob object, the parameter should be bound as OracleDbType.Clob. Updating LOBs Using ODP.NET LOB Objects Oracle BFILEs are not updatable and hence OracleBFile objects do not allow updates to BFILE columns. Two requirements must be met to update LOB data using ODP.NET LOB objects. 1. A transaction must be started before a LOB column is selected. The transaction must be started using the BeginTransaction method on the OracleConnection before the command execution so that the lock can be released when OracleTransaction Commit or Rollback is invoked. 2. The row in which the LOB column resides must be locked; on a row by row basis or as part of an entire result set. a. Locking the entire result See Also: Oracle Database Application Developer's Guide - Large Objects for complete information about Oracle Database 10g LOBs and how to use them ODP.NET XML Support Features of Oracle Data Provider for .NET 3-35 Add the FOR UPDATE clause to the end of the SELECT statement. After execution of the command, the entire result set is locked. b. Locking the row - There are two options: – Invoke one of OracleDataReader's typed accessors (GetOracleClobForUpdate or GetOracleBlobForUpdate) on the OracleDataReader to obtain an ODP.NET LOB object while also locking the current row. This approach requires a primary key, unique column(s), or a ROWID in the result set because the OracleDataReader must uniquely identify the row to re-select it for locking. – Execute an INSERT or an UPDATE statement that returns a LOB in the RETURNING clause. Temporary LOBs Temporary LOBs can be instantiated for BLOBs, CLOBs, and NCLOBs. To instantiate an ODP.NET LOB object that represents a temporary LOB, the OracleClob or the OracleBlob constructor can be used. Temporary ODP.NET LOB objects can be used for the following purposes: ■ To initialize and populate a LOB column with empty or non-empty LOB data. ■ To pass a LOB type as an input parameter to a SQL statement, anonymous PL/SQL blocks, or stored procedure. ■ To act as the source or the destination of data transfer between two LOB objects as in the CopyTo operation. ODP.NET XML Support From Oracle8i release 3 (8.1.7) and on, Oracle Database allows the extraction of data from relational and object-relational tables and views as XML documents. The use of XML documents for insert, update, and delete operations to the database server is also allowed. With Oracle9i release 2 (9.2), Oracle Database supports XML natively in the database, through Oracle XML Database (Oracle XML DB), a distinct group of technologies related to high-performance XML storage and retrieval. Oracle XML DB is an evolution of the database that encompasses both SQL and XML data models in a highly interoperable manner, providing native XML support. For samples related to ODP.NET XML support, see the following directory: ORACLE_BASE\ORACLE_HOME\ODP.NET\Samples Note: Temporary LOBs are not transaction aware. Commits and rollbacks do not affect the data referenced by a temporary LOB. Note: For database releases 8.1.7 and 9.0.1 only, certain OracleCommand methods require Oracle XML Developer's Kit (Oracle XDK) release 9.2 (Oracle XDK) or higher, to be installed in the database. The XDK can be downloaded from Oracle Technology Network (OTN). ODP.NET XML Support 3-36 Oracle Data Provider for .NET Developer’s Guide This section includes these topics: ■ Supported XML Features ■ OracleXmlType and Connection Dependency ■ Updating XMLType Data in the Database Server ■ Updating XML Data in OracleXmlType ■ Special Characters in XML ■ Retrieving Query Result Set as XML ■ Data Manipulation Using XML Supported XML Features XML support in ODP.NET provides the following features: ■ 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. For the .NET application developer, these features include the following: ■ Enhancements to the OracleCommand, OracleConnection, and OracleDataReader classes ■ The following XML-specific classes: ■ OracleXmlType Class OracleXmlType objects are used to retrieve Oracle native XMLType data. ■ OracleXmlStream Class OracleXmlStream objects are used to retrieve XML data from OracleXmlType objects as a read-only .NET Stream object. ■ OracleXmlQueryProperties Class OracleXmlQueryProperties objects represent the XML properties used by the OracleCommand class when the XmlCommandType property is Query. ■ OracleXmlSaveProperties Class OracleXmlSaveProperties objects represent the XML properties used by the OracleCommand class when the XmlCommandType property is Insert, Update, or Delete. ODP.NET XML Support Features of Oracle Data Provider for .NET 3-37 OracleXmlType and Connection Dependency The read-only Connection property of the OracleXmlType object holds a reference to the OracleConnection object used to instantiate the OracleXmlType object. How the OracleXmlType object obtains a reference to an OracleConnection object depends on how the OracleXmlType object is instantiated: ■ Instantiated from an OracleDataReader using the GetOracleXmlType, GetOracleValue, or GetOracleValues method: The Connection property is set with a reference to the same OracleConnection object used by the OracleDataReader. ■ Instantiated by invoking an OracleXmlType constructor with one of the parameters of type OracleConnection: The Connection property is set with a reference to the same OracleConnection object provided in the constructor. ■ Instantiated by invoking an OracleXmlType(OracleClob) constructor: The Connection property is set with a reference to the OracleConnection object used by the OracleClob object. An OracleXmlType object that is associated with one connection cannot be used with a different connection. For example, if an OracleXmlType object is obtained using OracleConnection A, that OracleXmlType object cannot be used as an input parameter of a command that uses OracleConnection B. By checking the Connection property of the OracleXmlType objects, the application can ensure that OracleXmlType objects are used only within the context of the OracleConnection referenced by its connection property. Otherwise, ODP.NET raises an exception. Updating XMLType Data in the Database Server Updating XMLType columns does not require a transaction. However, encapsulating the entire database update process within a transaction is highly recommended. This allows the updates to be rolled back if there are any errors. XMLType columns in the database can be updated using the Oracle Data Provider for .NET in several ways: ■ Updating with DataSet, OracleDataAdapter, and OracleCommandBuilder ■ Updating with OracleCommand and OracleParameter Updating with DataSet, OracleDataAdapter, and OracleCommandBuilder If the XMLType column is fetched into the DataSet, the XMLType data is represented as a .NET String. See Also: ■ "OracleCommand Class" on page 4-2 ■ "OracleXmlType Class" on page 5-36 ■ "OracleXmlStream Class" on page 5-22 ■ "OracleXmlQueryProperties Class" on page 5-3 ■ "OracleXmlSaveProperties Class" on page 5-12 ■ Oracle XML DB Developer's Guide ODP.NET XML Support 3-38 Oracle Data Provider for .NET Developer’s Guide Modifying XMLType data in the DataSet does not require special treatment. XMLType data can be modified in the same way as any data that is stored in the DataSet. When a change is made and OracleDataAdapter.Update() is invoked, the OracleDataAdapter ensures that the XMLType data is handled properly. OracleDataAdapter uses any custom SQL INSERT, UPDATE, or DELETE statements that are provided. Otherwise, valid SQL statements are generated by the OracleCommandBuilder as needed to flush the changes to the database server. Updating with OracleCommand and OracleParameter OracleCommand provides a powerful way of updating XMLType data, especially with the use of OracleParameter. To update columns in a database table, the new value for the column can be passed as an input parameter of a command. Input Binding To update an XMLType column in the database, a SQL statement can be executed using static values. In addition, input parameters can be bound to SQL statements, anonymous PL/SQL blocks, or stored procedures to update XMLType columns. The parameter value can be set as .NET Framework Types, ODP.NET Types, or OracleXmlType objects. While XMLType columns can be updated using the OracleXmlType object, having an instance of an OracleXmlType object does not guarantee that the XMLType column in the database can be updated. Setting XMLType Column to NULL Value Applications can set an XMLType column in the database to a NULL value, with or without input binding, as follows: ■ Setting NULL values in an XMLType column with Input Binding To set the XMLType column to NULL, the application can bind an input parameter whose value is DBNull.Value. This indicates to the OracleCommand that a NULL value is to be inserted. Passing in a null OracleXmlType object as an input parameter does not insert a NULL into the XMLType column. In this case, the OracleCommand raises an exception. ■ Setting NULL Values in an XMLType Column without Input Binding The following example demonstrates setting NULL values in an XMLType column without input binding: // Create a table with an XMLType column in the database CREATE TABLE XML_TABLE(NUM_COL number, XMLTYPE_COL xmltype); An application can set a NULL value in the XMLType column by explicitly inserting a NULL or by not inserting anything into that column as in the following examples: insert into xml_table(xmltype_col) values(NULL); update xml_table t set t.xmltype_col=NULL; Setting XMLType Column to Empty XML Data The XMLType column can be initialized with empty XML data, using a SQL statement: // Create a table with an XMLType column in the database CREATE TABLE XML_TABLE(NUM_COL number, XMLTYPE_COL xmltype); INSERT INTO XML_TABLE (NUM_COL, XMLTYPE_COL) VALUES (4, XMLType.createxml('')); ODP.NET XML Support Features of Oracle Data Provider for .NET 3-39 Updating XML Data in OracleXmlType There are several ways that XML data can be updated in an OracleXmlType object. ■ The XML data can be updated by passing an XPATH expression and the new value to the Update method on the OracleXmlType object. ■ The XML data can be retrieved on the client side as the .NET Framework XmlDocument object using the GetXmlDocument method on the OracleXmlType object. This XML data can then be manipulated using suitable .NET Framework classes. A new OracleXmlType can be created with the updated XML data from the .NET Framework classes. This new OracleXmlType is bound as an input parameter to an update or insert statement. Special Characters in XML The following characters have special meaning in XML. For more information, refer to the XML 1.0 specifications When these characters appear as data in an XML element, they are replaced with their equivalent entity encoding. Also certain characters are not valid in XML element names. When SQL identifiers (such as column names) are mapped to XML element names, these characters are converted to a sequence of hexadecimal digits, derived from the Unicode encoding of the character, bracketed by an introductory underscore, a lowercase x and a trailing underscore. For example, the space is not a valid character in an XML element name. If a SQL identifier contains a space character, then in the corresponding XML element name, the space character is replaced by _x0020_, which is based on Unicode encoding of the space character. Retrieving Query Result Set as XML This section discusses retrieving the result set from a SQL query as XML data. Handling Date and Time Format Table 3–15 lists the date and time format handling for different database releases. Table 3–14 Special Characters Special Character Meaning in XML Entity Encoding < Begins an XML tag < > Ends an XML tag > " Quotation mark " ' Apostrophe or single quotation mark ' &Ampersand& ODP.NET XML Support 3-40 Oracle Data Provider for .NET Developer’s Guide Special Characters in Column Data If any of the data in the select list columns in the query contain any characters with special meaning in XML (see Table 3–14), these characters are replaced with their corresponding entity encoding in the result XML document. The following examples demonstrate how ODP.NET handles the angle bracket special characters in the column data: /* Database Setup drop table specialchars; create table specialchars ("id" number, name varchar2(255)); insert into specialchars values (1, ''); commit; */ // C# using System; using System.Data; using System.Xml; using Oracle.DataAccess.Client; class QueryResultAsXMLSample { static void Main() Table 3–15 Database Release Date and Time Differences When Retrieving Data Database Release Date and Time Format Supported Oracle8i release 3 (8.1.7) and Oracle9i release 1 (9.0.x) Oracle DATE type data is always retrieved in the result XML document as the ISO Date and Time Format: YYYY-MM-DDThh:mm:ss.sss (ISO Format notation). The following string is the ISO Date and Time Format notation represented in the Oracle Date and Time Format notation: YYYY-MM-DD"T"HH24:MI:SS.FF3. TIMESTAMP and TIMESTAMP WITH TIME ZONE are not supported for 8.1.7 and 9.0.x. Oracle9i release 2 (9.2.x) and Oracle Database 10g Oracle DATE type data is retrieved in the format specified using the NLS_DATE_FORMAT in the session. TIMESTAMP and TIMESTAMP WITH TIME ZONE type data is retrieved in the format specified using the NLS_TIMESTAMP_ FORMAT and the NLS_TIMESTAMP_TZ_FORMAT in the session. If the result XML document is used to save changes to back to the database, then all DATE and TIMESTAMP data must be retrieved in the XML document as the following ISO Date and Time Format: YYYY-MM-DDThh:mm:ss.sss (ISO Format notation). To do this, before the query is executed, the application must explicitly perform an ALTER SESSION command on the session for the following NLS session parameters: ■ NLS_DATE_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS ■ NLS_TIMESTAMP_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS.FF3 ■ NLS_TIMESTAMP_TZ_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS.FF3 ODP.NET XML Support Features of Oracle Data Provider for .NET 3-41 { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); // Create the command OracleCommand cmd = new OracleCommand("", con); // Set the XML command type to query. cmd.XmlCommandType = OracleXmlCommandType.Query; // Set the SQL query cmd.CommandText = "select * from specialchars"; // Set command properties that affect XML query behavior. cmd.BindByName = true; // Set the XML query properties cmd.XmlQueryProperties.MaxRows = -1; // Get the XML document as an XmlReader. XmlReader xmlReader = cmd.ExecuteXmlReader(); XmlDocument xmlDocument = new XmlDocument(); xmlDocument.PreserveWhitespace = true; xmlDocument.Load(xmlReader); Console.WriteLine(xmlDocument.OuterXml); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); } } The following XML document is generated for that table: 1 <Jones> Special Characters In Table or View Name If a table or view name has any non-alphanumeric characters other than an underscore (_), the table or view name must be enclosed in quotation marks. For example, to select all entries from a table with the name test'ing, the CommandText property of the OracleCommand object must be set to the following string. "select * from \"test'ing\""; Case-Sensitivity in Column Name to XML Element Name Mapping The mapping of SQL identifiers (column names) to XML element names is case sensitive and the element names are in exactly the same case as the column names of the table or view. ODP.NET XML Support 3-42 Oracle Data Provider for .NET Developer’s Guide However, the root tag and row tag names are case insensitive. The following example demonstrates case-sensitivity in this situation: //Create the following table create table casesensitive_table ("Id" number, NAME varchar2(255)); //insert name and id insert into casesensitive_table values(1, 'Smith'); The following XML document is generated: 1 Smith Note that the element name for the Id column matches the case with the column name. Column Name to XML Element Name Mapping For each row generated by the SQL query, the SQL identifier (column name) maps to an XML element in the generated XML document. The following example demonstrates this: // Create the following table create table emp_table (EMPLOYEE_ID NUMBER(4), LAST_NAME varchar2(25)); // Insert some data insert into emp_table values(205, 'Higgins'); The SQL query, select * from emp_table, generates the following XML document: 205 Higgins The EMPLOYEE_ID and LAST_NAME database columns of the employees table map to the EMPLOYEE_ID and LAST_NAME elements of the generated XML document. Retrieving Results from Oracle 8.1.7 When retrieving the query results as XML from an Oracle 8.1.7 database, the SQL identifiers in the query select-list cannot contain characters that are not valid in XML element names. To handle the lack of support for this feature in Oracle 8.1.7, the SQL query in the following example can be used to get a result as a XML document from the specialchars table: select "some id" as "some_x0020_id", name from specialchars; Retrieving Results from Oracle9i or Higher When retrieving the query results as XML from Oracle9i and higher, the SQL identifiers in the query select-list can contain characters that are not valid in XML element names. When these SQL identifiers (such as column names) are mapped to XML element names, each of these characters are converted to a sequence of hexadecimal digits, derived from the Unicode encoding of the characters, bracketed by an introductory underscore, a lower case x, and a trailing underscore. ODP.NET XML Support Features of Oracle Data Provider for .NET 3-43 Thus, with an Oracle9i database, the SQL query in the following example can be used to get a result as an XML document from the specialchars table: select "some id", name from specialchars; Improving Default Mapping If this default mapping of SQL identifiers to XML element names is not adequate, you can improve the mapping by the following techniques: ■ Modify the source. Create an object-relational view over the source schema, and make that view the new source. ■ Use cursor subqueries and cast-multiset constructs in the SQL query. ■ Create an alias for the column or attribute names in the SQL query. Prepend the aliases with an at sign (@) to map them to XML attributes instead of XML elements. ■ Modify the XML Document. Use XSLT to transform the XML document. Specify the XSL document and parameters. The transformation is done automatically after the XML document is generated from the relational data. Note that this is not the best solution in terms of performance. ■ Specify the name of the root tag and row tag used in the XML document. Object-Relational Data ODP.NET can generate an XML document for data stored in object-relational columns, tables, and views. The following example demonstrates this: // Create the following tables and types CREATE TYPE "EmployeeType" AS OBJECT (EMPNO NUMBER, ENAME VARCHAR2(20)); / CREATE TYPE EmployeeListType AS TABLE OF "EmployeeType"; / CREATE TABLE mydept (DEPTNO NUMBER, DEPTNAME VARCHAR2(20), EMPLIST EmployeeListType) NESTED TABLE EMPLIST STORE AS EMPLIST_TABLE; INSERT INTO mydept VALUES (1, 'depta', EmployeeListType("EmployeeType"(1, 'empa'))); The following XML document is generated for the table: 1 depta 1 empa See Also: "Special Characters in XML" on page 3-39 ODP.NET XML Support 3-44 Oracle Data Provider for .NET Developer’s Guide ODP.NET encloses each item in a collection element, with the database type name of the element in the collection. The mydept table has a collection in the EMPLIST database column and each item in the collection is of type EmployeeType. Therefore, in the XML document, each item in the collection is enclosed in the type name EmployeeType. NULL values If any database row has a column with a NULL value, then that column does not appear for that row in the generated XML document. Data Manipulation Using XML This section discusses making changes to the database using XML. Handling of Date and Time Format Table 3–16 lists the date and time format handling for different database releases. Saving Changes Using XML Changes can be saved to database tables and views using XML data. However, insert, update, and delete operations cannot be combined in a single XML document. ODP.NET cannot accept a single XML document and determine which changes are inserts, updates, or deletes. Table 3–16 Database Release Date and Time Differences When Saving Data Database Release Date and Time Format Supported Oracle8i release (8.1.7), Oracle9i release 1 (9.0.x) All DATE type data must be specified in the XML document in the ISO Date and Time Format YYYY-MM-DDThh:mm:ss.sss (ISO Format notation). The following string is the ISO Date and Time Format notation represented in the Oracle Date and Time Format notation: YYYY-MM-DD"T"HH24:MI:SS.FF3. TIMESTAMP and TIMESTAMP WITH TIME ZONE are not supported for 8.1.7 and 9.0.x. Oracle9i release 2 (9.2.x) and Oracle Database 10g All DATE, TIMESTAMP, and TIMESTAMP WITH TIME ZONE type data must be specified in the XML document in the ISO Date and Time Format YYYY-MM-DDThh:mm:ss.sss (ISO Format notation). The following string is the ISO Date and Time Format notation represented in the Oracle Date and Time Format notation: YYYY-MM-DD"T"HH24:MI:SS.FF3. In addition to using the ISO Format notation in the XML document, before the save is executed, the application must explicitly perform an ALTER SESSION command on the session for the following NLS session parameters: ■ NLS_DATE_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS ■ NLS_TIMESTAMP_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS.FF3 ■ NLS_TIMESTAMP_TZ_FORMAT - Must be set to the following Oracle Date and Time Format: YYYY-MM-DD"T"HH24:MI:SS.FF3 ODP.NET XML Support Features of Oracle Data Provider for .NET 3-45 The inserts must be in an XML document containing only rows to be inserted, the updates only with rows to be updated, and the deletes only with rows to be deleted. For example, using the employees table that comes with the HR sample schema, you can specify the following query: select employee_id, last_name from employees where employee_id = 205; The following XML document is generated: 205 Higgins To change the name of employee 205 from Higgins to Smith, specify the employees table and the XML data containing the changes as follows: 205 Smith Special Characters in Column Data If the data in any of the elements in the XML document contains characters that have a special meaning in XML (see Table 3–14), these characters must be entity- encoded or escaped in the XML document, so that the data is stored correctly in the database table column. Otherwise, ODP.NET throws an exception. The following examples demonstrate how ODP.NET handles the angle bracket special characters in the column data. // Create the following table create table specialchars ("id" number, name varchar2(255)); The following XML document can be used to insert values (1, '7') to the specialchars table: 1 <Jones> Special Characters in Table or View Name If a table or view name has any non-alphanumeric characters other than an underscore (_), the table or view name must be enclosed in quotation marks. For example, to save changes to a table with the name test'ing, the OracleCommand.XmlSaveProperties.TableName property must be set to "\"test'ing\"". ODP.NET XML Support 3-46 Oracle Data Provider for .NET Developer’s Guide Case-Sensitivity in XML Element Name to Column Name Mapping For each XML element representing a row of data in the XML document, the child XML elements map to database column names. The mapping of the child element name to the column name is always case sensitive, but the root tag and row tag names are case insensitive. The following example demonstrates this case-sensitivity: //Create the following table create table casesensitive_table ("Id" number, NAME varchar2(255)); The following XML document can be used to insert values (1, Smith) into the casesensitive_table: 1 Smith Note the element name for the Id column matches the case with the column name. XML Element Name to Column Name Mapping Oracle9i and higher handles the mapping of XML element names to column names differently from Oracle 8.1.7 when using XML for data manipulation in the database. This section demonstrate these differences with changes to the following specialchars table involving the some id column. // Create the specialchars table create table specialchars ("some id" number, name varchar2(255)); Note that the specialchars table has a some id column that contains a space character. The space character is not allowed in an XML element name. Saving changes to Oracle 8.1.7 In this scenario, with an Oracle 8.1.7 database, in order to save changes to the specialchars table using an XML document, a view must be created over the table and the changes saved to the view using XML data. The column names in the view corresponding to the some id column in the table can be either a column name with no invalid characters or the escaped column name as in the following example. // Create the view with the escaped column name create view view1(some_x0020_id, name) as select * from specialchars; // Create the view with the column name with no invalid character create view view2(someid, name) as select * from specialchars; The following XML document can be used to insert values (1, ) into the specialchars table using view1: 1 <Jones> ODP.NET XML Support Features of Oracle Data Provider for .NET 3-47 The following XML document can be used to insert values (1, ) into the specialchars table using view2: 2 <Jones> Saving Changes to Oracle9i or higher When an XML document is used to save changes to a table or view, the OracleCommand.XmlSaveProperties. UpdateColumnsList is used to specify the list of columns to update or insert. With Oracle9i or higher, when an XML document is used to save changes to a column in a table or view and the corresponding column name contains any of the characters which are not valid in an XML element name, the escaped column name needs to be specified in the UpdateColumnsList property as in the following example. The following XML document can be used to insert values (2, ) into the specialchars table. 2 <Jones> The following code example specifies the list of columns to update or insert. /* Database Setup drop table specialchars; create table specialchars ("id" number, name varchar2(255)); insert into specialchars values (1, ''); commit; */ // C# using System; using System.Data; using System.Xml; using Oracle.DataAccess.Client; class InsertUsingXmlDocSample { static void Main() { OracleConnection con = new OracleConnection(); con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); Console.WriteLine("Connected Successfully"); // Create the command OracleCommand cmd = new OracleCommand("", con); // Set the XML command type to query. cmd.XmlCommandType = OracleXmlCommandType.Insert; ODP.NET XML Support 3-48 Oracle Data Provider for .NET Developer’s Guide // Set the XML document cmd.CommandText = "\n" + "\n" + "\n" + "2\n" + "<Jones>\n" + "\n" + "\n"; cmd.XmlSaveProperties.Table = "specialchars"; string[] ucols = new string[2]; ucols[0] = "id"; ucols[1] = "NAME"; cmd.XmlSaveProperties.UpdateColumnsList = ucols; // Insert rows int rows = cmd.ExecuteNonQuery(); Console.WriteLine("Number of rows inserted successfully : {0} ", rows); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); } } Improving Default Mapping If the default mapping is not adequate, you can improve the mapping by the following techniques: ■ Modify the target. Create an object-relational view over the target schema, and make the view the new target. ■ Modify the XML Document. Use XSLT to transform the XML document. Specify the XSL document and parameters. The transformation is done before the changes are saved. Note that this is not the best solution in terms of performance. ■ Specify the name of the row tag used in the XML document. Object-Relational Data Changes in an XML document can also be saved to object-relational data. Each item in a collection can be specified in one of the following ways in the XML document: ■ By enclosing the database type name of the item as the XML element name. ■ By enclosing the name of the database column holding the collection with _ ITEM appended as the XML element name. Multiple Tables Oracle Database does not support saving changes to multiple relational tables that have been joined together. In this case, Oracle recommends that you create a view on those relational tables, and then update that view. If the view is not updatable, triggers can be used instead. Commits When the changes in an XML document are made, either all the changes are committed, or if an error occurs, any changes that were made are rolled back. See Also: Oracle Database SQL Reference for the description and syntax of the CREATE VIEW command OracleDataAdapter Safe Type Mapping Features of Oracle Data Provider for .NET 3-49 OracleDataAdapter Safe Type Mapping The ODP.NET OracleDataAdapter provides the Safe Type Mapping feature because the following Oracle datatypes can potentially lose data when converted to their closely related .NET type: ■ NUMBER ■ DATE ■ TimeStamp (refers to all TimeStamp objects) ■ INTERVAL DAY TO SECOND When populating Oracle data containing any of these types into a .NET DataSet there is a possibility of data loss. The OracleDataAdapter Safe Type Mapping feature prevents data loss. By setting the SafeMapping property appropriately, these types can be safely represented in the DataSet, as either of the following: ■ .NET byte[] in Oracle format ■ .NET String Potential Data Loss The following sections provide more detail about the types and circumstances where data can be lost. Oracle NUMBER Type to .NET Decimal Type The Oracle datatype NUMBER can hold up to 38 precisions whereas .NET Decimal type can hold up to 28 precisions. If a NUMBER datatype that has more than 28 precisions is retrieved into .NET decimal type, it loses precision. Table 3–17 lists the maximums and minimums for Oracle NUMBER and .NET Decimal. Oracle Date Type to .NET DateTime Type The Oracle datatype DATE can represent dates in BC whereas .NET DateTime cannot. If a DATE that goes to BC get retrieved into .NET DateTime type, it loses data. Table 3–18 lists the maximums and minimums for Oracle Date and .NET DateTime. Oracle TimeStamp Type to .NET DateTime Type Similarly to DATE, Oracle datatype TimeStamp can represent a date in BC whereas .NET DateTime type cannot. If a TimeStamp that goes to BC is retrieved into .NET Table 3–17 Oracle NUMBER to .NET Decimal Comparisons Oracle NUMBER .NET Decimal Maximum 9.999999999999999999999999999999999 9999 e125 79,228,162,514,264,337,593,543,950,335 Minimum -9.99999999999999999999999999999999 99999 e125 -79,228,162,514,264,337,593,543,950,335 Table 3–18 Oracle Date to .NET DateTime Comparisons Oracle Date .NET DateTime Maximum Dec 31, 9999 AD Dec 31, 9999 AD 23:59:59.9999999 Minimum Jan 1, 4712 BC Jan 1, 0001 AD 00:00:00.0000000 OracleDataAdapter Safe Type Mapping 3-50 Oracle Data Provider for .NET Developer’s Guide DateTime type, it loses data. Oracle TimeStamp type can represent values in units of e-9, whereas the .NET DateTime type can only represent values in units of e-7. The Oracle TimeStamp with time zone datatype can store time zone information whereas .NET DateTime cannot. Table 3–19 lists the maximums and minimums for Oracle TimeStamp and .NET DateTime. Oracle INTERVAL DAY TO SECOND to .NET TimeSpan Similarly to DATE, the Oracle datatype INTERVAL DAY TO SECOND can represent dates in BC, whereas the .NET TimeSpan type cannot. If an INTERVAL DAY TO SECOND that goes to BC is retrieved into .NET TimeSpan type, it loses the data. The Oracle INTERVAL DAY TO SECOND type can represent values in units of e-9 whereas .NET TimeSpan type can only represent values in units of e-7. Table 3–20 lists the maximums and minimums for Oracle INTERVAL DAY TO SECOND and .NET DateTime. SafeMapping Property By default, Safe Type Mapping is disabled. Using Safe Type Mapping To use the Safe Type Mapping functionality, the OracleDataAdapter.SafeMapping property must be set with a hashtable of key-value pairs. The key-value pairs must map database table column names (of type string) to a .NET type (of type Type). ODP.NET supports safe type mapping to byte[] and String types. Any other type mapping causes an exception. In situations where the column names are not known at design time, an asterisk ("*") can be used to map all occurrences of database types to a safe .NET type where it is needed. If both the valid column name and the asterisk are present, the column name is used. Table 3–19 Oracle TimeStamp to .NET DateTime Comparisons Oracle TimeStamp .NET DateTime Maximum Dec 31, 9999 AD 23:59:59.999999999 Dec 31, 9999 AD 23:59:59.9999999 Minimum Jan 1, 4712 BC 00:00:00.000000000 Jan 1, 0001 AD 00:00:00.0000000 Table 3–20 Oracle INTERVAL DAY TO SECOND to .NET TimeSpan Comparisons Oracle INTERVAL DAY TO SECOND .NET TmeSpan Maximum +999999999 23:59:59.999999999 +10675199 02:48:05.4775807 Minimum -999999999 23:59:59.999999999 -10675199 02:48:05.4775808 Note: ■ Database table column names are case sensitive. ■ Column names in the hashtable that correspond to invalid column names are ignored. Guaranteeing Uniqueness in Updating DataSet to Database Features of Oracle Data Provider for .NET 3-51 Mapping to a .NET String The safe type mapping as a string is more readable without further conversion. Converting certain Oracle datatypes to a string requires extra conversion, which can be slower than converting it to a byte[]. Conversion of .NET strings back to ODP.NET types relies on the formatting information of the session. OracleDataAdapter Requery Property The OracleDataAdapter Requery property controls whether queries are reexecuted for OracleDataAdapter Fill calls after the initial Fill call. The OracleDataAdapter Fill method allows appending or refreshing data in the DataSet. When appending the DataSet using the same query with subsequent Fill calls, it may be desired not to reexecute the query. When the Requery property is set to true, each subsequent Fill call reexecutes the query and fills the DataSet. It is an expensive operation and if the reexecution is not required, set Requery to false. If any of the SelectCommand properties or associated parameters needs to be changed, Requery must be true. When the Requery property is set to false, the DataSet has the entire data as a snapshot at a particular time. The query is executed only for the first Fill call, subsequent Fill calls fetch the data from a cursor opened with the first execution of the query. This feature is only supported for forward-only fetches. Fill calls that try to fetch rows before the last fetched row raise an exception. The connection used for the first Fill call must be available for subsequent Fill calls. When filling a DataSet with a OracleRefCursor, the Requery property can be used in a similar manner. When the Requery property is set to false, both the connection used for the first Fill and the OracleRefCursor must be available for the subsequent Fill calls. Guaranteeing Uniqueness in Updating DataSet to Database This section describes how the OracleDataAdapter configures the PrimaryKey and Constraints properties of the DataTable which guarantee uniqueness when the OracleCommandBuilder is updating DataSet changes to the database. Using the OracleCommandBuilder object to dynamically generate DML statements to be executed against the database is one of the ways to reconcile changes made in a single DataTable with the database. In this process, the OracleCommandBuilder must not be allowed to generate DML statements that may affect (update or delete) more that a single row in the database when reconciling a single DataRow change. Otherwise the OracleCommandBuilder could corrupt data in the database. To guarantee that each DataRow change affects only a single row, there must be a set of DataColumns in the DataTable for which all rows in the DataTable have a unique set of values. The set of DataColumns indicated by the properties DataTable.PrimaryKey and DataTable.Constraints meet this requirement. The OracleCommandBuilder determines uniqueness in the DataTable by checking See Also: ■ "Requery" on page 4-95 ■ "SelectCommand" on page 4-97 Guaranteeing Uniqueness in Updating DataSet to Database 3-52 Oracle Data Provider for .NET Developer’s Guide whether the DataTable.PrimaryKey is non-null or if there exists a UniqueConstraint in the DataTable.Constraints collection. This discussion first explains what constitutes uniqueness in DataRows and then explains how to maintain that uniqueness while updating, through DataTable property configuration. This section includes the following topics: ■ What Constitutes Uniqueness in DataRows? ■ Configuring PrimaryKey and Constraints Properties ■ Updating Without PrimaryKey and Constraints Configuration What Constitutes Uniqueness in DataRows? This section describes the minimal conditions that must be met to guarantee uniqueness of DataRows. The condition of uniqueness must be guaranteed before the DataTable.PrimaryKey and DataTable.Constraints properties can be configured, as described in the next section. Uniqueness is guaranteed in a DataTable if any one of the following is true: ■ All the columns of the primary key are in the select list of the OracleDataAdapter.SelectCommand. ■ All the columns of a unique constraint are in the select list of the OracleDataAdapter.SelectCommand, with at least one involved column having a NOT NULL constraint defined on it. ■ All the columns of a unique index are in the select list of the OracleDataAdapter.SelectCommand, with at least one of the involved columns having a NOT NULL constraint defined on it. ■ A ROWID is present in the select list of the OracleDataAdapter.SelectCommand. Configuring PrimaryKey and Constraints Properties If the minimal conditions described in "What Constitutes Uniqueness in DataRows?" on page 3-52 are met, then the DataTable.PrimaryKey or DataTable.Constraints properties can be set. After these properties are set, the OracleCommandBuilder can determine uniqueness in the DataTable by checking the DataTable.PrimaryKey property or the presence of a UniqueConstraint in the DataTable.Constraints collection. Once uniqueness is determined, OracleCommandBuilder can safely generate DML statements to perform updates. The OracleDataAdapter.FillSchema method attempts to set these properties according to this order of priority: Note: A set of columns, on which a unique constraint has been defined or a unique index has been created, require at least one non-nullable column for following reason; if all the columns of the column set are nullable, then multiple rows could exist which have a NULL value for each column in the column set. This would violate the uniqueness condition that each row has a unique set of values for the column set. Globalization Support Features of Oracle Data Provider for .NET 3-53 1. If the primary key is returned in the select list, it is set as the DataTable.PrimaryKey. 2. If a set of columns that meets the following criteria is returned in the select list, it is set as the DataTable.PrimaryKey. Criteria: The set of columns has a unique constraint defined on it or a unique index created on it, with each column having a NOT NULL constraint defined on it. 3. If a set of columns that meets the following criteria is returned in the select list, a UniqueConstraint is added to the DataTable.Constraints collection, but the DataTable.PrimaryKey is not set. Criteria: The set of columns has a unique constraint defined on it or a unique index created on it, with at least one column having a NOT NULL constraint defined on it. 4. If a ROWID is part of the select list, it is set as the DataTable.PrimaryKey. Additionally, OracleDataAdapter.FillSchema exhibits the following behaviors: ■ Setting DataTable.PrimaryKey implicitly creates a UniqueConstraint. ■ If there are multiple occurrences of a column in the select list and the column is also part of the DataTable.PrimaryKey or UniqueConstraint, or both, each occurrence of the column is present as part of the DataTable.PrimaryKey or UniqueConstraint, or both. Updating Without PrimaryKey and Constraints Configuration If the DataTable.PrimaryKey or Constraints properties have not been configured, for example, if the application has not called OracleDataAdapter.FillSchema, the OracleCommandBuilder directly checks the select list of the OracleDataAdapter.SelectCommand to determine if it guarantees uniqueness in the DataTable. However this check results in a server round-trip to retrieve the metadata for the SELECT statement of the OracleDataAdapter.SelectCommand. Note that OracleCommandBuilder cannot update a DataTable created from PL/SQL statements because they do not return any key information in their metadata. Globalization Support ODP.NET globalization support enables applications to manipulate culture-sensitive data appropriately. This feature ensures proper string format, date, time, monetary, numeric, sort order, and calendar conventions depending on the Oracle globalization settings. This section includes the following: ■ Globalization Settings ■ Globalization-Sensitive Operations Globalization Settings An OracleGlobalization object can be used to represent the following: ■ Client Globalization Settings See Also: "OracleGlobalization Class" on page 6-2 Globalization Support 3-54 Oracle Data Provider for .NET Developer’s Guide ■ Session Globalization Settings ■ Thread-Based Globalization Settings Client Globalization Settings Client globalization settings are derived from the Oracle globalization setting (NLS_ LANG) in the Windows registry of the local computer. The client globalization parameter settings are read-only and remain constant throughout the lifetime of the application. The client globalization settings can be obtained by calling the OracleGlobalization.GetClientInfo() static method. The following example retrieves the client globalization setting: // C# using System; using Oracle.DataAccess.Client; class ClientGlobalizationInfoSample { static void Main() { OracleGlobalization ClientGlob = OracleGlobalization.GetClientInfo(); Console.WriteLine("Client machine language: " + ClientGlob.Language); Console.WriteLine("Client characterset: " + ClientGlob.ClientCharacterSet); } } The properties of the OracleGlobalization object provide the Oracle globalization value settings. Session Globalization Settings Session globalization parameters are initially identical to client globalization settings. Unlike client settings, session globalization settings can be updated. However, they can only be obtained after establishing a connection against the database server. The session globalization settings can be obtained by calling GetSessionInfo() on the OracleConnection. Invoking this method returns an instance of an OracleGlobalization object whose properties represent the globalization settings of the session. When the OracleConnection object establishes a connection, it implicitly opens a session whose globalization parameters are initialized with those values specified by the client computer's Oracle globalization (or National Language Setting (NLS)) registry settings. The session settings are updatable and can change during its lifetime. The following example changes the date format setting on the session: // C# using System; using Oracle.DataAccess.Client; class SessionGlobalizationSample { static void Main() { OracleConnection con = new OracleConnection(); Globalization Support Features of Oracle Data Provider for .NET 3-55 con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;"; con.Open(); OracleGlobalization SessionGlob = con.GetSessionInfo(); // SetSessionInfo updates the Session with the new value SessionGlob.DateFormat = "YYYY/MM/DD"; con.SetSessionInfo(SessionGlob); Console.WriteLine("Date Format successfully changed for the session"); // Close and Dispose OracleConnection object con.Close(); con.Dispose(); } } Thread-Based Globalization Settings Thread-based globalization parameter settings are specific to each thread. Initially, these settings are identical to the client globalization parameters, but they can be changed as specified by the application. When ODP.NET Types are converted to and from strings, the thread-based globalization parameters are used, if applicable. Thread-based globalization parameter settings are obtained by invoking the GetThreadInfo static method of the OracleGlobalization object. The SetThreadInfo static method of the OracleGlobalization object can be called to set the thread's globalization settings. ODP.NET classes and structures rely solely on the OracleGlobalization settings when manipulating culture-sensitive data. They do not use .NET thread culture information. If the application uses only .NET types, OracleGlobalization settings have no effect. However, when conversions are made between ODP.NET types and .NET types, OracleGlobalization settings are used where applicable. The following code snippet shows how the thread's globalization settings are used by the ODP.NET Types: // C# using System; using Oracle.DataAccess.Types; using Oracle.DataAccess.Client; class ThreadBasedGlobalizationSample { static void Main(string[] args) { // Set the thread's DateFormat for the OracleDate constructor OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "YYYY-MON-DD"; OracleGlobalization.SetThreadInfo(info); // construct OracleDate from a string using the DateFormat specified. OracleDate date = new OracleDate("1999-DEC-01"); Note: Changes to System.Threading.Thread. CurrentThread.CurrentCulture do not impact the settings of the OracleGlobalization settings of the thread or the session and vice versa. Globalization Support 3-56 Oracle Data Provider for .NET Developer’s Guide // Set a different DateFormat for the thread info.DateFormat = "MM/DD/YYYY"; OracleGlobalization.SetThreadInfo(info); // Print "12/01/1999" Console.WriteLine(date.ToString()); } } The OracleGlobalization object validates property changes made to it. If an invalid value is used to set a property, an exception is thrown. Note that changes made to the Territory and Language properties change other properties of the OracleGlobalization object implicitly. Globalization-Sensitive Operations This section lists ODP.NET types and operations that are dependent on or sensitive to globalization settings. Operations Dependent on Client Computer's Globalization Settings The OracleString structure depends on the client computer's OracleGlobalization settings. The local computer's client character set is used when it converts a Unicode string to a byte[] in the GetNonUnicode method and when it converts a byte[] of ANSI characters to Unicode in the OracleString constructor which accepts a byte[]. Operations Dependent on Thread Globalization Settings The thread globalization settings are used by ODP.NET types whenever they are converted to and from .NET string types, where applicable. In most cases, the ToString method, the Parse static method, constructors that accept .NET string data, and conversion operators to and from .NET strings use specific thread globalization settings depending on the ODP.NET type used. For example, the OracleDate type uses the DateFormat property of the thread globalization settings when the ToString method is invoked on it. This returns a DATE as a string in the format specified by the thread's settings. For more details, read the remarks in Chapter 5 for the ODP.NET type methods that convert between ODP.NET types and .NET string types, to identify which thread globalization settings are used for that particular method. The thread globalization settings also affect data that is retrieved into the DataSet as a string using Safe Type Mapping. If the type is format-sensitive, the strings are always in the format specified by the thread globalization settings. For example, INTERVAL DAY TO SECOND data are not affected by thread settings since no format is applicable for this type. However, the DateFormat and NumericCharacters properties can impact the string representation of DATE and NUMBER types, respectively, when they are retrieved as strings into the DataSet through Safe Type Mapping. See Also: Oracle Database Globalization Support Guide for more information on the properties affected by Territory and Language Globalization settings Debug Tracing Features of Oracle Data Provider for .NET 3-57 Operations Sensitive to Session Globalization Parameters Session globalization settings affect any data that is retrieved from or sent to the server as a string. For example, if a DATE column is selected with the TO_CHAR() function applied on it, the DATE column data will be a string in the date format specified by the DateFormat of the session globalization settings. Transmitting data in the other direction, the string data that is to be inserted into the DATE column, must be in the format specified by the DateFormat property of the session globalization settings. Debug Tracing ODP.NET provides debug tracing support, which allows logging of all the ODP.NET activities into a trace file. Different levels of tracing are available. The provider can record the following information: ■ Entry and Exit information for the ODP.NET public methods. ■ User provided SQL statements as well as any SQL statements modified by the provider. ■ Connection Pooling statistics such as Enlistment and Delistment. ■ Thread ID (entry and exit). Registry Settings for Tracing Calls The following registry settings should be configured under HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID\ODP.NET\HOME where ID is the appropriate Oracle Home. TraceFileName The valid values for TraceFileName are: any valid path and filename TraceFileName specifies the filename that is to be used for logging trace information. If TraceOption is set to 0, the name is used as is. However, if TraceOption is 1, the Thread ID is appended to the filename provided. TraceLevel The valid values for TraceLevel are: ■ 0 = None ■ 1 = Entry, Exit, and SQL execution information ■ 2 = Connection Pooling statistics ■ 4 = Distributed Transactions (Enlistment and Delistment) See Also: ■ "OracleDataAdapter Safe Type Mapping" on page 3-49 ■ Chapter 9, "Oracle Data Provider for .NET Types Structures" See Also: "TraceOption" on page 3-58 Debug Tracing 3-58 Oracle Data Provider for .NET Developer’s Guide TraceLevel specifies the level of tracing in ODP.NET. Because tracing all the entry and exit calls for all the objects can be excessive, TraceLevel is provided to limit tracing to certain areas of the provider. To obtain tracing on multiple objects, simply add the valid values. For example, if TraceLevel is set to 3, trace information is logged for Entry, Exit, SQL, and Connection pooling information. TraceOption The valid values for TraceOption are: ■ 0 = Single trace file ■ 1 = Multiple trace files TraceOption specifies whether to log trace information in single or multiple files for each Thread ID. If a single trace file is specified, the filename specified in TraceFileName is used. If the multiple trace files option is requested, a Thread ID is appended to the filename provided to create a trace file for each thread. Oracle Data Provider for .NET Classes 4-1 4 Oracle Data Provider for .NET Classes This chapter describes the following Oracle Data Provider for .NET classes. ■ OracleCommand Class ■ OracleCommandBuilder Class ■ OracleConnection Class ■ OracleDataAdapter Class ■ OracleDataReader Class ■ OracleError Class ■ OracleErrorCollection Class ■ OracleException Class ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventHandler Delegate ■ OracleParameter Class ■ OracleParameterCollection Class ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventHandler Delegate ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventHandler Delegate ■ OracleTransaction Class ■ OracleCollectionType Enumeration ■ OracleDbType Enumeration ■ OracleParameterStatus Enumeration OracleCommand Class 4-2 Oracle Data Provider for .NET Developer’s Guide OracleCommand Class An OracleCommand object represents a SQL command, a stored procedure, or a table name. The OracleCommand object is responsible for formulating the request and passing it to the database. If results are returned, OracleCommand is responsible for returning results as an OracleDataReader, a .NET XmlReader, a .NET Stream, a scalar value, or as output parameters. Class Inheritance Object MarshalByRefObject Component OracleCommand Declaration // C# public sealed class OracleCommand : Component, IDbCommand, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks The execution of any transaction-related statements from an OracleCommand is not recommended because it is not reflected in the state of the OracleTransaction object represents the current local transaction, if one exists. ExecuteXmlReader, ExecuteStream, and ExecuteToStream methods are only supported for XML operations. ExecuteReader and ExecuteScalar methods are not supported for XML operations. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleCommandSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); string cmdQuery = "select ename, empno from emp"; // Create the OracleCommand OracleCommand cmd = new OracleCommand(cmdQuery); OracleCommand Class Oracle Data Provider for .NET Classes 4-3 cmd.Connection = con; cmd.CommandType = CommandType.Text; // Execute command, create OracleDataReader object OracleDataReader reader = cmd.ExecuteReader(); while (reader.Read()) { // output Employee Name and Number Console.WriteLine("Employee Name : " + reader.GetString(0) + " , " + "Employee Number : " + reader.GetDecimal(1)); } // Clean up reader.Dispose(); cmd.Dispose(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Members ■ OracleCommand Constructors ■ OracleCommand Static Methods ■ OracleCommand Properties ■ OracleCommand Public Methods OracleCommand Members 4-4 Oracle Data Provider for .NET Developer’s Guide OracleCommand Members OracleCommand members are listed in the following tables: OracleCommand Constructors OracleCommand constructors are listed in Table 4–1. OracleCommand Static Methods OracleCommand static methods are listed in Table 4–2. OracleCommand Properties OracleCommand properties are listed in Table 4–3. Table 4–1 OracleCommand Constructors Constructor Description OracleCommand Constructors Instantiates a new instance of OracleCommand class (Overloaded) Table 4–2 OracleCommand Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–3 OracleCommand Properties Name Description AddRowid Adds the ROWID as part of the select list AddToStatementCache Causes executed statements to be cached, when the property is set to True and statement caching is enabled ArrayBindCount Specifies if the array binding feature is to be used and also specifies the maximum number of array elements to be bound in the Value property BindByName Specifies the binding method in the collection CommandText Specifies the SQL statement or stored procedure to run against the Oracle database or the XML data used to store changes to the Oracle database CommandTimeout Specifies the number of seconds the command is allowed to execute before terminating the execution with an exception CommandType Specifies the command type that indicates how the CommandText property is to be interpreted Connection Specifies the OracleConnection object that is used to identify the connection to execute a command Container Inherited from Component FetchSize Specifies the size of OracleDataReader's internal cache to store result set data InitialLOBFetchSize Specifies the amount that the OracleDataReader initially fetches for LOB columns InitialLONGFetchSize Specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns OracleCommand Class Oracle Data Provider for .NET Classes 4-5 OracleCommand Public Methods OracleCommand public methods are listed in Table 4–4. Parameters Specifies the parameters for the SQL statement or stored procedure RowSize Specifies the amount of memory needed by the OracleDataReader internal cache to store one row of data XmlCommandType Specifies the type of XML operation on the OracleCommand XmlQueryProperties Specifies the properties that are used when an XML document is created from the result set of a SQL query statement XmlSaveProperties Specifies the properties that are used when an XML document is used to save changes to the database Table 4–4 OracleCommand Public Methods Public Method Description Cancel Attempts to cancels a command that is currently executing on a particular connection Clone Creates a copy of OracleCommand object CreateObjRef Inherited from MarshalByRefObject CreateParameter Creates a new instance of OracleParameter class Dispose Inherited from Component Equals Inherited from Object (Overloaded) ExecuteNonQuery Executes a SQL statement or a command using the XmlCommandType and CommandText properties and returns the number of rows affected ExecuteReader Executes a command (Overloaded) ExecuteScalar Returns the first column of the first row in the result set returned by the query ExecuteStream Executes a command using the XmlCommandType and CommandText properties and returns the results in a new Stream object ExecuteToStream Executes a command using the XmlCommandType and CommandText properties and appends the results as an XML document to the existing Stream ExecuteXmlReader Executes a command using the XmlCommandType and CommandText properties and returns the result as an XML document in a .NET XmlTextReader object GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Prepare This method is a no-op Table 4–3 (Cont.) OracleCommand Properties Name Description OracleCommand Members 4-6 Oracle Data Provider for .NET Developer’s Guide ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class Table 4–4 (Cont.) OracleCommand Public Methods Public Method Description OracleCommand Class Oracle Data Provider for .NET Classes 4-7 OracleCommand Constructors OracleCommand constructors instantiate new instances of OracleCommand class. Overload List: ■ OracleCommand() This constructor instantiates a new instance of OracleCommand class. ■ OracleCommand(string) This constructor instantiates a new instance of OracleCommand class using the supplied SQL command or stored procedure, and connection to the Oracle database. ■ OracleCommand(string, OracleConnection) This constructor instantiates a new instance of OracleCommand class using the supplied SQL command or stored procedure, and connection to the Oracle database. OracleCommand() This constructor instantiates a new instance of OracleCommand class. Declaration // C# public OracleCommand(); Remarks Default constructor. OracleCommand(string) This constructor instantiates a new instance of OracleCommand class using the supplied SQL command or stored procedure, and connection to the Oracle database. Declaration // C# public OracleCommand(string cmdText); Parameters ■ cmdText See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Constructors 4-8 Oracle Data Provider for .NET Developer’s Guide The SQL command or stored procedure to be executed. OracleCommand(string, OracleConnection) This constructor instantiates a new instance of OracleCommand class using the supplied SQL command or stored procedure, and connection to the Oracle database. Declaration // C# public OracleCommand(string cmdText, OracleConnection OracleConnection); Parameters ■ cmdText Specifies the SQL command or stored procedure to be executed. ■ OracleConnection Specifies the connection to the Oracle database. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-9 OracleCommand Static Methods OracleCommand static methods are listed in Table 4–5. Table 4–5 OracleCommand Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Properties 4-10 Oracle Data Provider for .NET Developer’s Guide OracleCommand Properties OracleCommand properties are listed in Table 4–6. Table 4–6 OracleCommand Properties Name Description AddRowid Adds the ROWID as part of the select list AddToStatementCache Causes executed statements to be cached, when the property is set to True and statement caching is enabled ArrayBindCount Specifies if the array binding feature is to be used and also specifies the maximum number of array elements to be bound in the Value property BindByName Specifies the binding method in the collection CommandText Specifies the SQL statement or stored procedure to run against the Oracle database or the XML data used to store changes to the Oracle database CommandTimeout Specifies the number of seconds the command is allowed to execute before terminating the execution with an exception CommandType Specifies the command type that indicates how the CommandText property is to be interpreted Connection Specifies the OracleConnection object that is used to identify the connection to execute a command Container Inherited from Component FetchSize Specifies the size of OracleDataReader's internal cache to store result set data InitialLOBFetchSize Specifies the amount that the OracleDataReader initially fetches for LOB columns InitialLONGFetchSize Specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns Parameters Specifies the parameters for the SQL statement or stored procedure RowSize Specifies the amount of memory needed by the OracleDataReader internal cache to store one row of data Site Inherited from Component Transaction Specifies the OracleTransaction object in which the OracleCommand executes UpdatedRowSource Specifies how query command results are applied to the row being updated XmlCommandType Specifies the type of XML operation on the OracleCommand XmlQueryProperties Specifies the properties that are used when an XML document is created from the result set of a SQL query statement XmlSaveProperties Specifies the properties that are used when an XML document is used to save changes to the database OracleCommand Class Oracle Data Provider for .NET Classes 4-11 AddRowid This property adds the ROWID as part of the select list. Declaration // C# public bool AddRowid {get; set;} Property Value bool Remarks Default is false. This ROWID column is hidden and is not accessible by the application. To gain access to the ROWIDs of a table, the ROWID must explicitly be added to the select list without the use of this property. AddToStatementCache This property causes executed statements to be cached when the property is set to True and statement caching is enabled. If statement caching is disabled or if this property is set to False, the executed statement is not cached. Declaration // C# public bool AddToStatementCache{get; set;} Return Value Returns bool value. A value of True indicates that statements are being added to the cache, False indicates otherwise. Property Value A bool value that indicates that the statements will be cached when they are executed, if statement caching is enabled. Remarks Default is True. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "LOB Support" on page 3-32 for further information on how this property used with LOBs OracleCommand Properties 4-12 Oracle Data Provider for .NET Developer’s Guide AddToStatementCache is ignored if statement caching is disabled. Statement caching is enabled by setting the Statement Cache Size connection string attribute to a value greater than 0. When statement caching is enabled, however, this property provides a way to selectively add statements to the cache. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class AddToStatementCacheSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle;" + "statement cache size=10"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand("select * from emp", con); // The execution of "select * from emp" will be added to the statement cache // because statement cache size is greater than 0 and OracleCommand's // AddToStatementCache is true by default. OracleDataReader readerEmp = cmd.ExecuteReader(); // Do not add "select * from dept" to the statement cache cmd.CommandText = "select * from dept"; cmd.AddToStatementCache = false; // The execution of "select * from dept" will not be added to the // statement cache because AddToStatementCache is set to false. OracleDataReader readerDept = cmd.ExecuteReader(); // Clean up con.Dispose(); } } ArrayBindCount This property specifies if the array binding feature is to be used and also specifies the number of array elements to be bound in the OracleParameter Value property. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "Statement Caching" on page 3-21 ■ ConnectionString on page 4-62 OracleCommand Class Oracle Data Provider for .NET Classes 4-13 Declaration // C# public int ArrayBindCount {get; set;} Property Value An int value that specifies number of array elements to be bound in the OracleParameter Value property. Exceptions ArgumentException - The ArrayBindCount value specified is invalid. Remarks Default = 0. If ArrayBindCount is equal to 0, array binding is not used; otherwise, array binding is used and OracleParameter Value property is interpreted as an array of values. The value of ArrayBindCount must be specified to use the array binding feature. If neither DbType nor OracleDbType is set, it is strongly recommended that you set ArrayBindCount before setting the OracleParameter Value property so that inference of DbType and OracleDbType from Value can be correctly done. Array binding is not used by default. If the XmlCommandType property is set to any value other than None, this property is ignored. BindByName This property specifies the binding method in the collection. Declaration // C# public bool BindByName {get; set;} Property Value Returns true if the parameters are bound by name; returns false if the parameters are bound by position. Remarks Default = false. BindByName is ignored under the following conditions: ■ The value of the XmlCommandType property is Insert, Update, or Delete. ■ The value of the XmlCommandType property is Query, but there are no parameters set on the OracleCommand. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "Array Binding" on page 3-18 ■ "Value" on page 4-62 OracleCommand Properties 4-14 Oracle Data Provider for .NET Developer’s Guide If the XmlCommandType property is OracleXmlCommandType.Query and any parameters are set on the OracleCommand, the BindByName property must be set to true. Otherwise, the following OracleCommand methods throw an InvalidOperationException. ■ ExecuteNonQuery ■ ExecuteXmlReader ■ ExecuteStream ■ ExecuteToStream CommandText This property specifies the SQL statement or stored procedure to run against the Oracle database or the XML data used to store changes to the Oracle database. Declaration // C# public string CommandText {get; set;} Property Value A string. Implements IDbCommand Remarks The default is an empty string. When the CommandType property is set to StoredProcedure, the CommandText property is set to the name of the stored procedure. The command calls this stored procedure when an Execute method is called. The effects of XmlCommandType values on CommandText are: ■ XmlCommandType = None. CommandType property determines the contents of CommandText. ■ XmlCommandType = Query. CommandText must be a SQL query. The SQL query should be a select statement. CommandType property is ignored. ■ XmlCommandType property is Insert, Update, or Delete. CommandText must be an XML document. CommandType property is ignored. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "Array Binding" on page 3-18 ■ "Value" on page 4-62 OracleCommand Class Oracle Data Provider for .NET Classes 4-15 CommandTimeout This property specifies the number of seconds that the command is allowed to execute before terminating with an exception. Declaration // C# public int CommandTimeout {get; set;} Property Value int Implements IDbCommand.CommandTimeout Exception InvalidArgument - The specified value is less than 0. Remarks Default is 0 seconds, which enforces no time limit. When the specified timeout value expires before a command execution finishes, the command attempts to cancel. If cancellation is successful, an exception is thrown with the message of ORA-01013: user requested cancel of current operation error. If the command executed in time without any errors, no exceptions are thrown. In a situation where multiple OracleCommand objects use the same connection, the timeout expiration on one of the OracleCommand objects may terminate any of the executions on the single connection. To make the timeout expiration of a OracleCommand cancel only its own command execution, simply use one OracleCommand for each connection if that OracleCommand sets the CommandTimeout property to a value greater than 0. CommandType This property specifies the command type that indicates how the CommandText property is to be interpreted. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ http://msdn.microsoft.com/library for detailed information about this Microsoft .NET Framework 1.1 feature OracleCommand Properties 4-16 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public System.Data.CommandType CommandType {final get; final set;} Property Value A CommandType. Exceptions ArgumentException - The value is not a valid CommandType such as: CommandType.Text, CommandType.StoredProcedure, CommandType.TableDirect. Remarks Default = CommandType.Text If the value of the XmlCommandType property is not None, then the CommandType property is ignored. Connection This property specifies the OracleConnection object that is used to identify the connection to execute a command. Declaration // C# public OracleConnection Connection {get; set;} Property Value An OracleConnection object. Implements IDbCommand Remarks Default = null FetchSize This property specifies the size of OracleDataReader's internal cache to store result set data. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-17 Declaration // C# public long FetchSize {get; set;} Property Value A long that specifies the size (in bytes) of the OracleDataReader's internal cache. Exceptions ArgumentException - The FetchSize value specified is invalid. Remarks Default = 65536. The FetchSize property is inherited by the OracleDataReader that is created by a command execution returning a result set. The FetchSize property on the OracleDataReader object determines the amount of data the OracleDataReader fetches into its internal cache for each server round-trip. If the XmlCommandType property is set to any value other than None, this property is ignored. InitialLOBFetchSize This property specifies the amount that the OracleDataReader initially fetches for LOB columns. Declaration // C# public int InitialLOBFetchSize {get; set;} Property Value An int specifying the amount. Exceptions ArgumentException - The InitialLOBFetchSize value specified is invalid. Remarks The maximum value supported for InitialLOBFetchSize is 32767. If this property is set to a higher value, the provider resets it to 32767. Default = 0. The value of InitialLOBFetchSize specifies the initial amount of LOB data that is immediately fetched by the OracleDataReader. The property value specifies the number of characters for CLOB and NCLOB data and the number of bytes for BLOB data. To fetch more than the specified InitialLOBFetchSize amount, one of the following must be in the select list: See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ OracleDataReader "FetchSize" on page 4-117 OracleCommand Properties 4-18 Oracle Data Provider for .NET Developer’s Guide ■ primary key ■ ROWID ■ unique columns - (defined as a set of columns on which a unique constraint has been defined or a unique index has been created, where at least one of the columns in the set has a NOT NULL constraint defined on it) The InitialLOBFetchSize value is used to determine the length of the LOB column data to fetch if LOB column is in the select list. If the select list does not contain a LOB column, the InitialLOBFetchSize value is ignored. A primary key, a ROWID, or unique columns are not required if this property is set to 0. If the InitialLOBFetchSize is set to a nonzero value, GetOracleBlob() and GetOracleClob() methods are disabled. BLOB and CLOB data are fetched by using GetBytes() and GetChars(), respectively. InitialLONGFetchSize This property specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns. Declaration // C# public int InitialLONGFetchSize {get; set;} Property Value An int specifying the amount. Exceptions ArgumentException - The InitialLONGFetchSize value specified is invalid. Remarks The maximum value supported for InitialLONGFetchSize is 32767. If this property is set to a higher value, the provider resets it to 32767. The value of InitialLONGFetchSize specifies the initial amount of LONG or LONG RAW data that is immediately fetched by the OracleDataReader. The property value specifies the number of characters for LONG data and the number of bytes for LONG RAW. To fetch more than the specified InitialLONGFetchSize amount, one of the following must be in the select list: ■ primary key ■ ROWID ■ unique columns - (defined as a set of columns on which a unique constraint has been defined or a unique index has been created, where at least one of the columns in the set has a NOT NULL constraint defined on it) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "Obtaining LOB Data" on page 3-27 OracleCommand Class Oracle Data Provider for .NET Classes 4-19 The InitialLONGFetchSize value is used to determine the length of the LONG and LONG RAW column data to fetch if one of the two is in the select list. If the select list does not contain a LONG or a LONG RAW column, the InitialLONGFetchSize value is ignored. Default = 0. Setting this property to 0 defers the LONG and LONG RAW data retrieval entirely until the application specifically requests it. Parameters This property specifies the parameters for the SQL statement or stored procedure. Declaration // C# public OracleParameterCollection Parameters {get;} Property Value OracleParameterCollection Implements IDbCommand Remarks Default value = an empty collection The number of the parameters in the collection must be equal to the number of parameter placeholders within the command text, or an error is raised. If the command text does not contain any parameter tokens (such as,:1,:2), the values in the Parameters property are ignored. RowSize This property specifies the amount of memory needed by the OracleDataReader internal cache to store one row of data. Declaration // C# public long RowSize {get;} See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "Obtaining LONG and LONG RAW Data" on page 3-27 for further information See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Properties 4-20 Oracle Data Provider for .NET Developer’s Guide Property Value A long that indicates the amount of memory (in bytes) that an OracleDataReader needs to store one row of data for the executed query. Remarks Default value = 0 The RowSize property is set to a nonzero value after the execution of a command that returns a result set. This property can be used at design time or dynamically during run-time, to set the FetchSize, based on number of rows. For example, to enable the OracleDataReader to fetch N rows for each server round-trip, the OracleDataReader's FetchSize property can be set dynamically to RowSize * N. Note that for the FetchSize to take effect appropriately, it must be set after OracleCommand.ExecuteReader() but before OracleDataReader.Read(). Transaction This property specifies the OracleTransaction object in which the OracleCommand executes. Declaration // C# public OracleTransaction Transaction {get;} Property Value OracleTransaction Implements IDbCommand Remarks Default value = null Transaction returns a reference to the transaction object associated with the OracleCommand connection object. Thus the command is executed in whatever transaction context its connection is currently in. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ OracleDataReader "FetchSize" on page 4-16 Note: When this property is accessed through an IDbCommand reference, its set accessor method is not operational. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-21 UpdatedRowSource This property specifies how query command results are applied to the row to be updated. Declaration // C# public System.Data.UpdateRowSource UpdatedRowSource {final get; final set;} Property Value An UpdateRowSource. Implements IDbCommand Exceptions ArgumentException - The UpdateRowSource value specified is invalid. Remarks Default = UpdateRowSource.None if the command is automatically generated. Default = UpdateRowSource.Both if the command is not automatically generated. XmlCommandType This property specifies the type of XML operation on the OracleCommand. Declaration // C# public OracleXmlCommandType XmlCommandType {get; set;} Property Value An OracleXmlCommandType. Remarks Default value is None. XmlCommandType values and usage: ■ None - The CommandType property specifies the type of operation. ■ Query - CommandText property must be set to a SQL select statement. The query is executed, and the results are returned as an XML document. The SQL select statement in the CommandText and the properties specified by the XmlQueryProperties property are used to perform the operation. The CommandType property is ignored. ■ Insert, Update, or Delete - CommandText property is an XML document containing the changes to be made. The XML document in the CommandText and the properties specified by the XmlSaveProperties property are used to perform the operation. The CommandType property is ignored. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Properties 4-22 Oracle Data Provider for .NET Developer’s Guide XmlQueryProperties This property specifies the properties that are used when an XML document is created from the result set of a SQL query statement. Declaration // C# public OracleXmlQueryProperties XmlQueryProperties {get; set;} Property Value OracleXmlQueryProperties. Remarks When a new instance of OracleCommand is created, an instance of OracleXmlQueryProperties is automatically available on the OracleCommand instance through the OracleCommand.XmlQueryProperties property. A new instance of OracleXmlQueryProperties can be assigned to an OracleCommand instance. Assigning an instance of OracleXmlQueryProperties to the XmlQueryProperties of an OracleCommand instance creates a new instance of the given OracleXmlQueryProperties instance for the OracleCommand. This way each OracleCommand instance has its own OracleXmlQueryProperties instance. Use the default constructor to get a new instance of OracleXmlQueryProperties. Use the OracleXmlQueryProperties.Clone() method to get a copy of an OracleXmlQueryProperties instance. XmlSaveProperties This property specifies the properties that are used when an XML document is used to save changes to the database. Declaration // C# public OracleXmlSaveProperties XmlSaveProperties {get; set;} Property Value OracleXmlSaveProperties. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-23 Remarks When a new instance of OracleCommand is created, an instance of OracleXmlSaveProperties is automatically available on the OracleCommand instance through the OracleCommand.XmlSaveProperties property. A new instance of OracleXmlSaveProperties can be assigned to an OracleCommand instance. Assigning an instance of OracleXmlSaveProperties to the XmlSaveProperties of an OracleCommand instance creates a new instance of the given OracleXmlSaveProperties instance for the OracleCommand. This way each OracleCommand instance has its own OracleXmlSaveProperties instance. Use the default constructor to get a new instance of OracleXmlSaveProperties. Use the OracleXmlSaveProperties.Clone() method to get a copy of an OracleXmlSaveProperties instance. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Public Methods 4-24 Oracle Data Provider for .NET Developer’s Guide OracleCommand Public Methods OracleCommand public methods are listed in Table 4–7. Cancel This method attempts to cancel a command that is currently executing on a particular connection. Table 4–7 OracleCommand Public Methods Public Method Description Cancel Attempts to cancels a command that is currently executing on a particular connection Clone Creates a copy of OracleCommand object CreateObjRef Inherited from MarshalByRefObject CreateParameter Creates a new instance of OracleParameter class Dispose Inherited from Component Equals Inherited from Object (Overloaded) ExecuteNonQuery Executes a SQL statement or a command using the XmlCommandType and CommandText properties and returns the number of rows affected ExecuteReader Executes a command (Overloaded) ExecuteScalar Returns the first column of the first row in the result set returned by the query ExecuteStream Executes a command using the XmlCommandType and CommandText properties and returns the results in a new Stream object ExecuteToStream Executes a command using the XmlCommandType and CommandText properties and appends the results as an XML document to the existing Stream ExecuteXmlReader Executes a command using the XmlCommandType and CommandText properties and returns the result as an XML document in a .NET XmlTextReader object GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Prepare This method is a no-op ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-25 Declaration // C# public void Cancel(); Implements IDbCommand.Cancel Remarks Invoking the Cancel method does not guarantee that the command executing at the time is actually cancelled. If the cancellation of the command succeeds, an exception is thrown. If the cancellation is not successful, no exception is thrown. If there is no command being executed at the time of the Cancel invocation, Cancel does nothing. When multiple OracleCommand objects share the same connection, only one command can be executed on that connection at any one time. When it is invoked, the Cancel method attempts to cancel the statement currently running on the connection that the OracleCommand object is using to execute the command. However, when multiple OracleCommand objects execute statements on the same connection simultanously, issuing a Cancel method invocation may cancel any of the issued commands. This is because the currently running statement may have completed and the next command started executing by the time the cancel request reaches the server. There are several ways to eliminate this non-deterministic situation as follows: ■ If Cancel is used on that command, the application can create just one OracleCommand object for each connection or the command executions between OracleCommand objects that use the same connection can be synchronized. ■ If Cancel is not used, there is no need to synchronize or limit one OracleCommand object for each connection. Since the termination on the currently running execution is non-deterministic, it is recommended that any non-atomic SQL or PL/SQL execution be started within a transaction. When the command execution successfully terminates with an exception of ORA-01013: user requested cancel of current operation error, the transaction can be rolled back for data integrity. Examples of non-atomic execution are collections of DML command executions that are executed one-by-one and multiple DML commands that are part of a PL/SQL stored procedure or function. Example // C# // This example shows how command executions can be cancelled in a deterministic // way even if multiple commands are executed on a single connection. // This is accomplished by synchronizing threads through events. // Since the Cancel method terminates the currently running operation on the // connection, threads must be serialized if multiple threads are using the same // connection to execute server round-trip incurring operations. // Furthermore, the example shows how the execution and cancel threads should // be synchronized so that nth iteration of the command execution does not // inappropriately cancel the (n+1)th command executed by the same thread. using System; using System.Data; using Oracle.DataAccess.Client; using System.Threading; OracleCommand Public Methods 4-26 Oracle Data Provider for .NET Developer’s Guide class CancelSample { private OracleCommand cmd; Thread t1, t2; // threads signal following events when assigned operations are completed private AutoResetEvent ExecuteEvent = new AutoResetEvent(false); private AutoResetEvent CancelEvent = new AutoResetEvent(false); private AutoResetEvent FinishedEvent = new AutoResetEvent(false); AutoResetEvent[] ExecuteAndCancel = new AutoResetEvent[2]; // Default constructor CancelSample() { cmd = new OracleCommand("select * from all_objects", new OracleConnection("user id=scott;password=tiger;data source=oracle")); ExecuteAndCancel[0] = ExecuteEvent; ExecuteAndCancel[1] = CancelEvent; } // Constructor that takes a particular command and connection CancelSample(string command, OracleConnection con) { cmd = new OracleCommand(command, con); ExecuteAndCancel[0] = ExecuteEvent; ExecuteAndCancel[1] = CancelEvent; } // Execution of the command public void Execute() { OracleDataReader reader = null; try { Console.WriteLine("Execute."); reader = cmd.ExecuteReader(); Console.WriteLine("Execute Done."); reader.Close(); } catch(Exception e) { Console.WriteLine("The command has been cancelled.", e.Message); } Console.WriteLine("ExecuteEvent.Set()"); ExecuteEvent.Set(); } // Canceling of the command public void Cancel() { try { // cancel query if it takes longer than 100 ms to finish execution System.Threading.Thread.Sleep(100); Console.WriteLine("Cancel."); cmd.Cancel(); } catch (Exception e) { Console.WriteLine(e.ToString()); OracleCommand Class Oracle Data Provider for .NET Classes 4-27 } Console.WriteLine("Cancel done."); Console.WriteLine("CancelEvent.Set()"); CancelEvent.Set(); } // Execution of the command with a potential of cancelling public void ExecuteWithinLimitedTime() { for (int i = 0; i < 5; i++) { Monitor.Enter(typeof(CancelSample)); try { Console.WriteLine("Executing " + this.cmd.CommandText); ExecuteEvent.Reset(); CancelEvent.Reset(); t1 = new Thread(new ThreadStart(this.Execute)); t2 = new Thread(new ThreadStart(this.Cancel)); t1.Start(); t2.Start(); } finally { WaitHandle.WaitAll(ExecuteAndCancel); Monitor.Exit(typeof(CancelSample)); } } FinishedEvent.Set(); } [MTAThread] static void Main() { try { AutoResetEvent[] ExecutionCompleteEvents = new AutoResetEvent[3]; // Create the connection that is to be used by three commands OracleConnection con = new OracleConnection("user id=scott;" + "password=tiger;data source=oracle"); con.Open(); // Create instances of CancelSample class CancelSample test1 = new CancelSample("select * from all_objects", con); CancelSample test2 = new CancelSample("select * from all_objects, emp", con); CancelSample test3 = new CancelSample("select * from all_objects, dept", con); // Create threads for each CancelSample object instance Thread t1 = new Thread(new ThreadStart(test1.ExecuteWithinLimitedTime)); Thread t2 = new Thread(new ThreadStart(test2.ExecuteWithinLimitedTime)); Thread t3 = new Thread(new ThreadStart(test3.ExecuteWithinLimitedTime)); // Obtain a handle to an event from each object ExecutionCompleteEvents[0] = test1.FinishedEvent; ExecutionCompleteEvents[1] = test2.FinishedEvent; ExecutionCompleteEvents[2] = test3.FinishedEvent; // Start all threads to execute three commands using a single connection OracleCommand Public Methods 4-28 Oracle Data Provider for .NET Developer’s Guide t1.Start(); t2.Start(); t3.Start(); // Wait for all three commands to finish executing/canceling before //closing the connection WaitHandle.WaitAll(ExecutionCompleteEvents); con.Close(); } catch (Exception e) { Console.WriteLine(e.ToString()); } } } Clone This method creates a copy of an OracleCommand object. Declaration // C# public object Clone(); Return Value An OracleCommand object. Implements ICloneable Remarks The cloned object has the same property values as that of the object being cloned. CreateParameter This method creates a new instance of OracleParameter class. Declaration // C# public OracleParameter CreateParameter(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ http://msdn.microsoft.com/library for detailed information about this Microsoft .NET Framework 1.1 feature See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-29 Return Value A new OracleParameter with default values. Implements IDbCommand ExecuteNonQuery This method executes a SQL statement or a command using the XmlCommandType and CommandText properties and returns the number of rows affected. Declaration // C# public int ExecuteNonQuery(); Return Value The number of rows affected. Implements IDbCommand Exceptions InvalidOperationException - The command cannot be executed. Remarks ExecuteNonQuery returns the number of rows affected, for the following: ■ If the command is UPDATE, INSERT, or DELETE and the XmlCommandType property is set to OracleXmlCommandType.None. ■ If the XmlCommandType property is set to OracleXmlCommandType.Insert, OracleXmlCommandType.Update, OracleXmlCommandType.Delete. For all other types of statements, the return value is -1. ExecuteNonQuery is used for either of the following: ■ catalog operations (for example, querying the structure of a database or creating database objects such as tables). ■ changing the data in a database without using a DataSet, by executing UPDATE, INSERT, or DELETE statements. ■ changing the data in a database using an XML document. Although ExecuteNonQuery does not return any rows, it populates any output parameters or return values mapped to parameters with data. If the XmlCommandType property is set to OracleXmlCommandType.Query then ExecuteNonQuery executes the select statement in the CommandText property, and if successful, returns -1. The XML document that is generated is discarded. This is See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Public Methods 4-30 Oracle Data Provider for .NET Developer’s Guide useful for determining if the operation completes successfully without getting the XML document back as a result. If the XmlCommandType property is set to OracleXmlCommandType.Insert, OracleXmlCommandType.Update, or OracleXmlCommandType.Delete, then the value of the CommandText property is an XML document. ExecuteNonQuery saves the changes in that XML document to the table or view that is specified in the XmlSaveProperties property. The return value is the number of rows that are processed in the XML document. Also, each row in the XML document could affect multiple rows in the database, but the return value is still the number of rows in the XML document. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class ExecuteNonQuerySample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand( "select sal from emp where empno=7934", con); object sal = cmd.ExecuteScalar(); Console.WriteLine("Employee sal before update: " + sal); cmd.CommandText = "update emp set sal = sal + .01 where empno=7934"; // Auto-commit changes int rowsUpdated = cmd.ExecuteNonQuery(); if (rowsUpdated > 0) { cmd.CommandText = "select sal from emp where empno=7934"; sal = cmd.ExecuteScalar(); Console.WriteLine("Employee sal after update: " + sal); } // Clean up cmd.Dispose(); con.Dispose(); } } Requirements For XML support, this method requires Oracle9i XML Developer's Kits (Oracle XDK) or higher, to be installed in the database. Oracle XDK can be downloaded from Oracle Technology Network (OTN). OracleCommand Class Oracle Data Provider for .NET Classes 4-31 ExecuteReader Overload List: ExecuteReader executes a command specified in the CommandText. ■ ExecuteReader() This method executes a command specified in the CommandText and returns an OracleDataReader object. ■ ExecuteReader(CommandBehavior) This method executes a command specified in the CommandText and returns an OracleDataReader object, using the specified CommandBehavior value. ExecuteReader() This method executes a command specified in the CommandText and returns an OracleDataReader object. Declaration // C# public OracleDataReader ExecuteReader(); Return Value An OracleDataReader. Implements IDbCommand Exceptions InvalidOperationException - The command cannot be executed. Remarks When the CommandType property is set to CommandType.StoredProcedure, the CommandText property should be set to the name of the stored procedure. The command executes this stored procedure when you call ExecuteReader(). If parameters for the stored procedure consists of REF CURSORs, behavior differs depending on whether ExecuteReader() or ExecuteNonQuery() is called. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ http://otn.oracle.com/ See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Public Methods 4-32 Oracle Data Provider for .NET Developer’s Guide The value of 100 is used for the FetchSize. If 0 is specified, no rows are fetched. For further information, see "Obtaining LONG and LONG RAW Data" on page 3-27. If the value of the XmlCommandType property is set to OracleXmlCommandType.Insert, OracleXmlCommandType.Update, OracleXmlCommandType.Delete, or OracleXmlCommandType.Query then the ExecuteReader method throws an InvalidOperationException. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class ExecuteReaderSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand("select ename from emp", con); OracleDataReader reader = cmd.ExecuteReader(); while (reader.Read()) { Console.WriteLine("Employee Name : " + reader.GetString(0)); } // Clean up reader.Dispose(); cmd.Dispose(); con.Dispose(); } } ExecuteReader(CommandBehavior) This method executes a command specified in the CommandText and returns an OracleDataReader object, using the specified behavior. Declaration // C# public OracleDataReader ExecuteReader(CommandBehavior behavior); Parameters ■ behavior See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "OracleRefCursor Class" on page 8-109 OracleCommand Class Oracle Data Provider for .NET Classes 4-33 Specifies expected behavior. Return Value An OracleDataReader. Implements IDbCommand Exceptions InvalidOperationException - The command cannot be executed. Remarks A description of the results and the effect on the database of the query command is indicated by the supplied behavior that specifies command behavior. For valid CommandBehavior values and for the expected behavior of each CommandBehavior enumerated type, read the .NET Framework documentation. When the CommandType property is set to CommandType.StoredProcedure, the CommandText property should be set to the name of the stored procedure. The command executes this stored procedure when ExecuteReader() is called. If the stored procedure returns stored REF CURSORs, read the section on OracleRefCursors for more details. See "OracleRefCursor Class" on page 8-109. The value of 100 is used for the FetchSize. If 0 is specified, no rows are fetched. For more information, see "Obtaining LONG and LONG RAW Data" on page 3-27. If the value of the XmlCommandType property is set to OracleXmlCommandType.Insert, OracleXmlCommandType.Update, OracleXmlCommandType.Delete, or OracleXmlCommandType.Query then the ExecuteReader method throws an InvalidOperationException. ExecuteScalar This method executes the query using the connection, and returns the first column of the first row in the result set returned by the query. Declaration // C# public object ExecuteScalar(); Return Value An object which represents the value of the first row, first column. Implements IDbCommand See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ "OracleRefCursor Class" on page 8-109 OracleCommand Public Methods 4-34 Oracle Data Provider for .NET Developer’s Guide Exceptions InvalidOperationException - The command cannot be executed. Remarks Extra columns or rows are ignored. ExecuteScalar retrieves a single value (for example, an aggregate value) from a database. This requires less code than using the ExecuteReader() method, and then performing the operations necessary to generate the single value using the data returned by an OracleDataReader. If the query does not return any row, it returns null. The ExecuteScalar method throws an InvalidOperationException, if the value of the XmlCommandType property is set to one of the following OracleXmlCommandType values: Insert, Update, Delete, Query. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class ExecuteScalarSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand("select count(*) from emp", con); object count = cmd.ExecuteScalar(); Console.WriteLine("There are {0} rows in table emp", count); // Clean up cmd.Dispose(); con.Dispose(); } } ExecuteStream This method executes a command using the XmlCommandType and CommandText properties and returns the result as an XML document in a new Stream object. Declaration // C# public Stream ExecuteStream(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members OracleCommand Class Oracle Data Provider for .NET Classes 4-35 Return Value A Stream. Remarks The behavior of ExecuteStream varies depending on the XmlCommandType property value: ■ XmlCommandType = OracleXmlCommandType.None ExecuteStream throws an InvalidOperationException. ■ XmlCommandType = OracleXmlCommandType.Query ExecuteStream executes the select statement in the CommandText property, and if successful, returns an OracleClob object containing the XML document that was generated. OracleClob contains Unicode characters. If the SQL query does not return any rows, then ExcecuteStream returns an OracleClob object containing an empty XML document. ■ XmlCommandType = OracleXmlCommandType.Insert, OracleXmlCommandType.Update, or OracleXmlCommandType.Delete. The value of the CommandText property is an XML document. ExecuteStream saves the data in that XML document to the table or view that is specified in the XmlSaveProperties property and an empty OracleClob is returned. Requirements For database releases 8.1.7 and 9.0.1 only: This method requires 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). ExecuteToStream This method executes a command using the XmlCommandType and CommandText properties and appends the result as an XML document to the existing Stream provided by the application. Declaration // C# public void ExecuteToStream(Stream outputStream); Parameters ■ outputStream A Stream. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ Oracle XML DB Developer's Guide ■ http://otn.oracle.com/ OracleCommand Public Methods 4-36 Oracle Data Provider for .NET Developer’s Guide Remarks The behavior of ExecuteToStream varies depending on the XmlCommandType property value: ■ XmlCommandType = OracleXmlCommandType.None ExecuteToStream throws an InvalidOperationException. ■ XmlCommandType = OracleXmlCommandType.Query ExecuteToStream executes the select statement in the CommandText property, and if successful, appends the XML document that was generated to the given Stream. If the SQL query does not return any rows, then nothing is appended to the given Stream. The character set of the appended data is Unicode. ■ XmlCommandType = OracleXmlCommandType.Insert, OracleXmlCommandType.Update, or OracleXmlCommandType.Delete The value of the CommandText property is an XML document. ExecuteToStream saves the changes in that XML document to the table or view that is specified in the XmlSaveProperties property. Nothing is appended to the given Stream. Requirements For database releases 8.1.7 and 9.0.1 only: This method requires 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). ExecuteXmlReader This method executes the command using the XmlCommandType and CommandText properties and returns the result as an XML document in a .NET XmlTextReader object. Declaration // C# public XmlReader ExecuteXmlReader(); Return Value An XmlReader. Remarks The behavior of ExecuteXmlReader varies depending on the XmlCommandType property value: ■ XmlCommandType = OracleXmlCommandType.None See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ Oracle XML DB Developer's Guide ■ http://otn.oracle.com/ OracleCommand Class Oracle Data Provider for .NET Classes 4-37 ExecuteStream throws an InvalidOperationException. ■ XmlCommandType = OracleXmlCommandType.Query ExecuteXmlReader executes the select statement in the CommandText property, and if successful, returns a .NET XmlTextReader object containing the XML document that was generated. If the XML document is empty, which can happen if the SQL query does not return any rows, then an empty .NET XmlTextReader object is returned. ■ XmlCommandType = OracleXmlCommandType.Insert, OracleXmlCommandType.Update, or OracleXmlCommandType.Delete. The value of the CommandText property is an XML document, and ExecuteXmlReader saves the changes in that XML document to the table or view that is specified in the XmlSaveProperties property. An empty .NET XmlTextReader object is returned. Requirements For database releases 8.1.7 and 9.0.1 only: This method requires 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). See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommand Class ■ OracleCommand Members ■ Oracle XML DB Developer's Guide ■ http://otn.oracle.com/ OracleCommandBuilder Class 4-38 Oracle Data Provider for .NET Developer’s Guide OracleCommandBuilder Class An OracleCommandBuilder object provides automatic SQL generation for the OracleDataAdapter when updates are made to the database. Class Inheritance Object MarshalByRefObject Component OracleCommandBuilder Declaration // C# public sealed class OracleCommandBuilder : Component Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleCommandBuilder automatically generates SQL statements for single-table updates when the SelectCommand property of the OracleDataAdapter is set. An exception is thrown if the DataSet contains multiple tables. The OracleCommandBuilder registers itself as a listener for RowUpdating events whenever its DataAdapter property is set. Only one OracleDataAdapter object and one OracleCommandBuilder object can be associated with each other at one time. To generate INSERT, UPDATE, or DELETE statements, the OracleCommandBuilder uses ExtendedProperties within the DataSet to retrieve a required set of metadata. If the SelectCommand is changed after the metadata is retrieved (for example, after the first update), the RefreshSchema method should be called to update the metadata. OracleCommandBuilder first looks for the metadata from the ExtendedProperties of the DataSet; if the metadata is not available, OracleCommandBuilder uses the SelectCommand property of the OracleDataAdapter to retrieve the metadata. Example The following example performs an update on the EMP table. It uses the OracleCommandBuilder object to create the UpdateCommand for the OracleDataAdapter object when OracleDataAdapter.Update() is called. // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleCommandBuilderSample { static void Main() OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-39 { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; string cmdstr = "SELECT empno, sal from emp"; // Create the adapter with the selectCommand txt and the // connection string OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr); // Create the builder for the adapter to automatically generate // the Command when needed OracleCommandBuilder builder = new OracleCommandBuilder(adapter); // Create and fill the DataSet using the EMP DataSet dataset = new DataSet(); adapter.Fill(dataset, "EMP"); // Get the EMP table from the dataset DataTable table = dataset.Tables["EMP"]; // Indicate DataColumn EMPNO is unique // This is required by the OracleCommandBuilder to update the EMP table table.Columns["EMPNO"].Unique = true; // Get the first row from the EMP table DataRow row = table.Rows[0]; // Update the salary double sal = double.Parse(row["SAL"].ToString()); row["SAL"] = sal + .01; // Now update the EMP using the adapter // The OracleCommandBuilder will create the UpdateCommand for the // adapter to update the EMP table adapter.Update(dataset, "EMP"); Console.WriteLine("Row updated successfully"); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Members ■ OracleCommandBuilder Constructors ■ OracleCommandBuilder Static Methods ■ OracleCommandBuilder Properties ■ OracleCommandBuilder Public Methods ■ OracleCommandBuilder Events ■ OracleCommandBuilder Event Delegates OracleCommandBuilder Members 4-40 Oracle Data Provider for .NET Developer’s Guide OracleCommandBuilder Members OracleCommandBuilder members are listed in the following tables: OracleCommandBuilder Constructors OracleCommandBuilder constructors are listed in Table 4–8. OracleCommandBuilder Static Methods OracleCommandBuilder static methods are listed in Table 4–9. OracleCommandBuilder Properties OracleCommandBuilder properties are listed in Table 4–10. OracleCommandBuilder Public Methods OracleCommandBuilder public methods are listed in Table 4–11. Table 4–8 OracleCommandBuilder Constructors Constructor Description OracleCommandBuilder Constructors Instantiates a new instance of OracleCommandBuilder class (Overloaded) Table 4–9 OracleCommandBuilder Static Methods Methods Description DeriveParameters Queries for the parameters of a stored procedure or function, represented by a specified OracleCommand, and populates the OracleParameterCollection of the command with the return values Equals Inherited from Object (Overloaded) Table 4–10 OracleCommandBuilder Properties Name Description Container Inherited from Component DataAdapter Indicates the OracleDataAdapter for which the SQL statements are generated CaseSensitive Indicates whether or not double quotes are used around Oracle object names when generating SQL statements Site Inherited from Component Table 4–11 OracleCommandBuilder Public Methods Public Method Description CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component Equals Inherited from Object (Overloaded) GetDeleteCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform deletions on the database GetHashCode Inherited from Object OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-41 OracleCommandBuilder Events OracleCommandBuilder events are listed in Table 4–12. OracleCommandBuilder Event Delegates OracleCommandBuilder event delegates are listed in Table 4–13. GetInsertCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform insertions on the database GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object GetUpdateCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform updates on the database InitializeLifetimeService Inherited from MarshalByRefObject RefreshSchema Refreshes the database schema information used to generate INSERT, UPDATE, or DELETE statements ToString Inherited from Object Table 4–12 OracleCommandBuilder Events Event Name Description Disposed Inherited from Component Table 4–13 OracleCommandBuilder Event Delegates Event Delegate Name Description EventHandler Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class Table 4–11 (Cont.) OracleCommandBuilder Public Methods Public Method Description OracleCommandBuilder Constructors 4-42 Oracle Data Provider for .NET Developer’s Guide OracleCommandBuilder Constructors OracleCommandBuilder constructors create new instances of the OracleCommandBuilder class. Overload List: ■ OracleCommandBuilder() This constructor creates an instance of the OracleCommandBuilder class. ■ OracleCommandBuilder(OracleDataAdapter) This constructor creates an instance of the OracleCommandBuilder class and sets the DataAdapter property to the provided OracleDataAdapter object. OracleCommandBuilder() This constructor creates an instance of the OracleCommandBuilder class. Declaration // C# public OracleCommandBuilder(); Remarks Default constructor. OracleCommandBuilder(OracleDataAdapter) This constructor creates an instance of the OracleCommandBuilder class and sets the DataAdapter property to the provided OracleDataAdapter object. Declaration // C# public OracleCommandBuilder(OracleDataAdapter da); Parameters ■ da The OracleDataAdapter object provided. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-43 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Static Methods 4-44 Oracle Data Provider for .NET Developer’s Guide OracleCommandBuilder Static Methods OracleCommandBuilder static methods are listed in Table 4–14. DeriveParameters This method queries for the parameters of a stored procedure or function, represented by a specified OracleCommand, and populates the OracleParameterCollection of the command with the return values. Declaration // C# public static void DeriveParameters(OracleCommand command); Parameters ■ command The command that represents the stored procedure or function for which parameters are to be derived. Exceptions InvalidOperationException - The CommandText is not a valid stored procedure or function name, the CommandType is not CommandType.StoredProcedure, or the Connection.State is not ConnectionState.Open. Remarks DeriveParameters can only be used for stored procedures or functions, not for anonymous PL/SQL blocks. Invoking DeriveParameters deletes all existing parameters in the parameter collection of the command. DeriveParameters incurs a server round-trip and should only be used during design time. To avoid unnecessary server round-trips in a production environment, the DeriveParameters method itself should be replaced with the explicit parameter settings that were returned by the DeriveParameters method at design time. DeriveParameters can only preserve the case of the stored procedure or function name if it is encapsulated by double-quotes. For example, if the stored procedure in Table 4–14 OracleCommandBuilder Static Methods Methods Description DeriveParameters Queries for the parameters of a stored procedure or function, represented by a specified OracleCommand, and populates the OracleParameterCollection of the command with the return values Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-45 the database is named GetEmployees with mixed-case, the CommandText property on the OracleCommand object must be set appropriately as in the following example: cmd.CommandText = "\"GetEmployees\""; Stored procedures and functions in a package must be provided in the following format: . For example, to obtain parameters for a stored procedure named GetEmployees (mixed-case) in a package named EmpProcedures (mixed-case), the name provided to the OracleCommand is: "\"EmpProcedures\".\"GetEmployees\"" DeriveParameters cannot be used for object type methods. The derived parameters contain all the metadata information that is needed for the stored procedure to execute properly. The application must provide the value of the parameters before execution, if required. The output values of derived parameters return as .NET Types by default. To obtain output parameters as provider types, the OracleDbType property of the parameter must be set explicitly by the application to override this default behavior. One quick way to do this is to set the OracleDbType to itself for all output parameters that should be returned as provider types. The BindByName property of the supplied OracleCommand is left as is, but the application can change its value. If the specified stored procedure or function is overloaded, the first overload is used to populate the parameters collection. Example // Database Setup /* CREATE OR REPLACE PROCEDURE MyOracleStoredProc (arg_in IN VARCHAR2, arg_out OUT VARCHAR2) IS BEGIN arg_out := arg_in; END; / */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class DeriveParametersSample { static void Main() { // Create the PL/SQL Stored Procedure MyOracleStoredProc as indicated above string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommandBuilder Static Methods 4-46 Oracle Data Provider for .NET Developer’s Guide // Create an OracleCommand OracleCommand cmd = new OracleCommand("MyOracleStoredProc", con); cmd.CommandType = CommandType.StoredProcedure; // Derive Parameters OracleCommandBuilder.DeriveParameters(cmd); Console.WriteLine("Parameters Derived"); // Prints "Number of Parameters for MyOracleStoredProc = 2" Console.WriteLine("Number of Parameters for MyOracleStoredProc = {0}", cmd.Parameters.Count); // Modify the OracleParameter Properties, if applicable // Set the Value for the IN parameter. // The Size can also be set, this sample uses the default size cmd.Parameters[0].Value = "MyText"; // Prints "cmd.Parameters[1].Size = 4000" // The default size for OUT VARCHAR2 is 4000 Console.WriteLine("cmd.Parameters[1].Size = " + cmd.Parameters[1].Size); // Set the Size for the OUT parameter cmd.Parameters[1].Size = 6; // Execute the command cmd.ExecuteNonQuery(); // Prints "cmd.Parameters[1].Value = MyText" Console.WriteLine("cmd.Parameters[1].Value = " + cmd.Parameters[1].Value); con.Close(); con.Dispose(); } } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members ■ OracleCommand Class ■ OracleParameter Class ■ OracleParameterCollection Class ■ http://msdn.microsoft.com/library for detailed information about this Microsoft .NET Framework 1.1 feature OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-47 OracleCommandBuilder Properties OracleCommandBuilder properties are listed in Table 4–15. DataAdapter This property indicates the OracleDataAdapter for which the SQL statements are generated. Declaration // C# OracleDataAdapter DataAdapter{get; set;} Property Value OracleDataAdapter Remarks Default = null CaseSensitive This property indicates whether or not double quotes are used around Oracle object names (for example, tables or columns) when generating SQL statements. Declaration // C# bool CaseSensitive {get; set;} Property Value A bool that indicates whether or not double quotes are used. Table 4–15 OracleCommandBuilder Properties Name Description Container Inherited from Component DataAdapter Indicates the OracleDataAdapter for which the SQL statements are generated CaseSensitive Indicates whether or not double quotes are used around Oracle object names when generating SQL statements Site Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Properties 4-48 Oracle Data Provider for .NET Developer’s Guide Remarks Default = false See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-49 OracleCommandBuilder Public Methods OracleCommandBuilder public methods are listed in Table 4–16. GetDeleteCommand This method gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform deletions on the database when an application calls Update() on the OracleDataAdapter. Declaration // C# public OracleCommand GetDeleteCommand(); Return Value An OracleCommand. Exceptions ObjectDisposedException - The OracleCommandBuilder object is already disposed. Table 4–16 OracleCommandBuilder Public Methods Public Method Description CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component Equals Inherited from Object (Overloaded) GetDeleteCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform deletions on the database GetHashCode Inherited from Object GetInsertCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform insertions on the database GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object GetUpdateCommand Gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform updates on the database InitializeLifetimeService Inherited from MarshalByRefObject RefreshSchema Refreshes the database schema information used to generate INSERT, UPDATE, or DELETE statements ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Public Methods 4-50 Oracle Data Provider for .NET Developer’s Guide InvalidOperationException - Either the SelectCommand or the DataAdapter property is null, or the primary key cannot be retrieved from the SelectCommand property of the OracleDataAdapter. GetInsertCommand This method gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform insertions on the database when an application calls Update() on the OracleDataAdapter. Declaration // C# public OracleCommand GetInsertCommand(); Return Value An OracleCommand. Exceptions ObjectDisposedException - The OracleCommandBuilder object is already disposed. InvalidOperationException - Either the SelectCommand or the DataAdapter property is null, or the primary key cannot be retrieved from the SelectCommand property of the OracleDataAdapter. GetUpdateCommand This method gets the automatically generated OracleCommand object that has the SQL statement (CommandText) perform updates on the database when an application calls Update() on the OracleDataAdapter. Declaration // C# public OracleCommand GetUpdateCommand(); Return Value An OracleCommand. Exceptions ObjectDisposedException - The OracleCommandBuilder object is already disposed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-51 InvalidOperationException - Either the SelectCommand or the DataAdapter property is null, or the primary key cannot be retrieved from the SelectCommand property of the OracleDataAdapter. RefreshSchema This method refreshes the database schema information used to generate INSERT, UPDATE, or DELETE statements. Declaration // C# public void RefreshSchema(); Remarks An application should call RefreshSchema whenever the SelectCommand value of the OracleDataAdapter changes. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Events 4-52 Oracle Data Provider for .NET Developer’s Guide OracleCommandBuilder Events OracleCommandBuilder events are listed in Table 4–17. Table 4–17 OracleCommandBuilder Events Event Name Description Disposed Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleCommandBuilder Class Oracle Data Provider for .NET Classes 4-53 OracleCommandBuilder Event Delegates OracleCommandBuilder event delegates are listed in Table 4–18. Table 4–18 OracleCommandBuilder Event Delegates Event Delegate Name Description EventHandler Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleCommandBuilder Class ■ OracleCommandBuilder Members OracleConnection Class 4-54 Oracle Data Provider for .NET Developer’s Guide OracleConnection Class An OracleConnection object represents a connection to an Oracle database. Class Inheritance Object MarshalByRefObject Component OracleConnection Declaration // C# public sealed class OracleConnection : Component, IDbConnection, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleConnectionSample { static void Main() { // Connect string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Execute a SQL SELECT OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select * from emp"; OracleDataReader reader = cmd.ExecuteReader(); // Print all employee numbers while (reader.Read()) Console.WriteLine(reader.GetInt32(0)); // Clean up reader.Dispose(); cmd.Dispose(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client OracleConnection Class Oracle Data Provider for .NET Classes 4-55 Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Members ■ OracleConnection Constructors ■ OracleConnection Static Methods ■ OracleConnection Properties ■ OracleConnection Public Methods ■ OracleConnection Events ■ OracleConnection Event Delegates OracleConnection Members 4-56 Oracle Data Provider for .NET Developer’s Guide OracleConnection Members OracleConnection members are listed in the following tables: OracleConnection Constructors OracleConnection constructors are listed in Table 4–19. OracleConnection Static Methods OracleConnection static methods are listed in Table 4–20. OracleConnection Properties OracleConnection properties are listed in Table 4–21 OracleConnection Public Methods OracleConnection public methods are listed in Table 4–22. Table 4–19 OracleConnection Constructors Constructor Description OracleConnection Constructors Instantiates a new instance of the OracleConnection class (Overloaded) Table 4–20 OracleConnection Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–21 OracleConnection Properties Name Description ConnectionString Specifies connection information used to connect to an Oracle database ConnectionTimeout Specifies the maximum amount of time that the Open() method can take to obtain a pooled connection before terminating the request Container Inherited from Component DataSource Specifies the Oracle Net Service Name (also known as TNS alias) that identifies an Oracle database instance ServerVersion Specifies the version number of the Oracle database to which the OracleConnection has established a connection Site Inherited from Component State Specifies the current state of the connection Table 4–22 OracleConnection Public Methods Public Method Description BeginTransaction Begins a local transaction (Overloaded) ChangeDatabase Not Supported Clone Creates a copy of an OracleConnection object OracleConnection Class Oracle Data Provider for .NET Classes 4-57 OracleConnection Events OracleConnection events are listed in Table 4–23. OracleConnection Event Delegates OracleConnection event delegates are listed in Table 4–24. Close Closes the database connection CreateCommand Creates and returns an OracleCommand object associated with the OracleConnection object CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component EnlistDistributedTransaction Enables applications to explicitly enlist in a specified distributed transaction Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetSessionInfo Returns or refreshes the property values of the OracleGlobalization object that represents the globalization settings of the session (Overloaded) GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Open Opens a database connection with the property settings specified by the ConnectionString OpenWithNewPassword Opens a new connection with the new password PurgeStatementCache Flushes the Statement Cache by closing all open cursors on the server, when Statement Caching is enabled SetSessionInfo Alters the session's globalization settings with the property values provided by the OracleGlobalization object ToString Inherited from Object Table 4–23 OracleConnection Events Event Name Description Disposed Inherited from Component Failover An event that is triggered when an Oracle failover occurs InfoMessage An event that is triggered for any message or warning sent by the database StateChange An event that is triggered when the connection state changes Table 4–22 (Cont.) OracleConnection Public Methods Public Method Description OracleConnection Members 4-58 Oracle Data Provider for .NET Developer’s Guide Table 4–24 OracleConnection Event Delegates Event Delegate Name Description OracleFailoverEventHandler An event delegate that handles the Failover event OracleInfoMessageEventHandler An event delegate that handles the InfoMessage event StateChangeEventHandler An event delegate that handles the StateChange event See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class OracleConnection Class Oracle Data Provider for .NET Classes 4-59 OracleConnection Constructors OracleConnection constructors instantiate new instances of the OracleConnection class. Overload List: ■ OracleConnection() This constructor instantiates a new instance of the OracleConnection class using default property values. ■ OracleConnection(String) This constructor instantiates a new instance of the OracleConnection class with the provided connection string. OracleConnection() This constructor instantiates a new instance of the OracleConnection class using default property values. Declaration // C# public OracleConnection(); Remarks The properties for OracleConnection are set to the following default values: ■ ConnectionString = empty string ■ ConnectionTimeout = 15 ■ DataSource = empty string ■ ServerVersion = empty string OracleConnection(String) This constructor instantiates a new instance of the OracleConnection class with the provided connection string. Declaration // C# public OracleConnection(String connectionString); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Constructors 4-60 Oracle Data Provider for .NET Developer’s Guide Parameters ■ connectionString The connection information used to connect to the Oracle database. Remarks The ConnectionString property is set to the supplied connectionString. The ConnectionString property is parsed and an exception is thrown if it contains invalid connection string attributes or attribute values. The properties of the OracleConnection object default to the following values unless they are set by the connection string: ■ ConnectionString = empty string ■ ConnectionTimeout = 15 ■ DataSource = empty string ■ ServerVersion = empty string See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-61 OracleConnection Static Methods OracleConnection static methods are listed in Table 4–25. Table 4–25 OracleConnection Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Properties 4-62 Oracle Data Provider for .NET Developer’s Guide OracleConnection Properties OracleConnection properties are listed in Table 4–26 ConnectionString This property specifies connection information used to connect to an Oracle database. Declaration // C# public string ConnectionString{get; set;} Property Value If the connection string is supplied through the constructor, this property is set to that string. Implements IDbConnection Exceptions ArgumentException - An invalid syntax is specified for the connection string. InvalidOperationException - ConnectionString is being set while the connection is open. Remarks The default value is an empty string. ConnectionString must be a string of attribute name and value pairings, separated by a semi-colon, for example: Table 4–26 OracleConnection Properties Name Description ConnectionString Specifies connection information used to connect to an Oracle database ConnectionTimeout Specifies the maximum amount of time that the Open() method can take to obtain a pooled connection before terminating the request Container Inherited from Component DataSource Specifies the Oracle Net Service Name (also known as TNS alias) that identifies an Oracle database instance ServerVersion Specifies the version number of the Oracle database to which the OracleConnection has established a connection Site Inherited from Component State Specifies the current state of the connection See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-63 "User Id=scott;password=tiger;data source=oracle" If the ConnectionString is not in a proper format, an exception is thrown. All spaces are ignored unless they are within double quotes. When the ConnectionString property is set, the OracleConnection object immediately parses the string for errors. An ArgumentException is thrown if the ConnectionString contains invalid attributes or invalid values. Attribute values for User Id, Password, Proxy User Id, Proxy Password, and Data Source (if provided) are not validated until the Open method is called. The connection must be closed to set the ConnectionString property. When the ConnectionString property is reset, all previously set values are reinitialized to their default values before the new values are applied. The Oracle database supports case-sensitive user names. To connect as a user whose name is of mixed case, for example, "MySchema", the User Id attribute value must be surrounded by double quotes, as follows: "User Id=\"MySchema\";Password=MYPASSWORD;Data Source=oracle" However, if the Oracle user name is all upper case, the User Id connection string attribute can be set to that user name without the use of the double quotes since User Ids that are not doubled-quoted are converted to all upper case when connecting. Single quotes are not supported. For a complete example, see "Example" on page 4-66. If a connection string attribute is set more than once, the last setting takes effect and no exceptions are thrown. Boolean connection string attributes can be set to either true, false, yes, or no. Supported connection string attributes: Table 4–27 lists the supported connection string attributes. Table 4–27 Supported Connection String Attributes Connection String Attribute Default value Description Connection Lifetime 0 Maximum life time (in seconds) of the connection This attribute specifies the lifetime of the connection in seconds. Before the Connection is placed back into the pool, the lifetime of the connection is checked. If the lifetime of the connection exceeds this property value, the connection is closed and disposed. If this property value is 0, the connection lifetime is never checked. Connections that have exceeded their lifetimes are not closed and disposed of, if doing so brings the number of connection in the pool below the Min Pool Size. OracleConnection Properties 4-64 Oracle Data Provider for .NET Developer’s Guide Connection Timeout 15 Maximum time (in seconds) to wait for a free connection from the pool This attribute specifies the maximum amount of time (in seconds) that the Open() method can take to obtain a pooled connection before it terminates the request. This value comes into effect only if no free connection is available from the connection pool and the Max Pool Size is reached. If a free connection is not available within the specified time, an exception is thrown. Connection Timeout does not limit the time required to open new connections. This attribute value takes effect for pooled connection requests and not for new connection requests. Data Source empty string Oracle Net Service Name that identifies the database to connect to This attribute specifies the Oracle Net Service Name (formerly known as TNS alias) that identifies an Oracle database instance. This attribute must be set to connect to a remote database. DBA Privilege empty string Administrative privileges SYSDBA or SYSOPER This connection string attribute only accepts SYSDBA or SYSOPER as the attribute value. It is case insensitive. Decr Pool Size 1 Number of connections that are closed when an excessive amount of established connections are unused. This connection string attribute controls the maximum number of unused connections that are closed when the pool regulator makes periodic checks. The regulator thread is spawned every 3 minutes and closes up to Decr Pool Size amount of pooled connections if they are not used. The pool regulator never takes the total number of connections below the Min Pool Size by closing pooled connections. Enlist True Serviced Components automatically enlist in distributed transactions If this attribute is set to true, the connection is automatically enlisted in the thread's transaction context. If this attribute is false, no enlistments are made. This attribute can be set to either true, false, yes, or no. Incr Pool Size 5 Number of connections established when all connections in pool are used This connection string attribute determines the number of new connections that are established when a pooled connection is requested, but no unused connections are available and Max Pool Size is not reached. If new connections have been created for a pool, the regulator thread skips a cycle and does not have an opportunity to close any connections for 6 minutes. Note, however, that some connections can be still be closed during this time if their lifetime has been exceeded. Table 4–27 (Cont.) Supported Connection String Attributes Connection String Attribute Default value Description OracleConnection Class Oracle Data Provider for .NET Classes 4-65 Max Pool Size 100 Maximum number of connections in a pool This attribute specifies the maximum number of connections allowed in the particular pool used by that OracleConnection. Simply changing this attribute in the connection string does not change the Max Pool Size restriction on a currently existing pool. Doing so simply creates a new pool with a different Max Pool Size restriction. This attribute must be set to a value greater than the Min Pool Size. This value is ignored unless Pooling is turned on. Min Pool Size 1 Minimum number of connections in a pool This attribute specifies the minimum number of connections to be maintained by the pool during its entire lifetime. Simply changing this attribute in the connection string does not change the Min Pool Size restriction on a currently existing pool. Doing so simply creates a new pool with a different Min Pool Size restriction. This value is ignored unless Pooling is turned on. Password empty string Password for the user specified by User Id This attribute specifies an Oracle user's password. Password is case insensitive. Persist Security Info False Enables or disables the retrieval of password in the connection string If this attribute is set to false, the Password value setting is not returned when the application requests the ConnectionString after the connection is successfully opened by the Open() method. This attribute can be set to either true, false, yes, or no. Pooling True Enables or disables connection pooling This attribute specifies whether connection pooling is to be used. Pools are created using an attribute value matching algorithm. This means that connection strings which only differ in the number of spaces in the connection string use the same pool. If two connection strings are identical except that one sets an attribute to a default value while the other does not set that attribute, both requests obtain connections from the same pool. This attribute can be set to either true, false, yes, or no. Proxy User Id empty string User name of the proxy user This connection string attribute specifies the middle-tier user, or the proxy user, who establishes a connection on behalf of a client user specified by the User Id attribute. ODP.NET attempts to establish a proxy connection if either the Proxy User Id or the Proxy Password attribute is set to a non-empty string. For the proxy user to connect to an Oracle database using operating system authentication, the Proxy User Id must be set to "/". The Proxy Password is ignored in this case. The User Id cannot be set to "/" when establishing proxy connections. The case of this attribute value is preserved if it is surrounded by double quotes. Table 4–27 (Cont.) Supported Connection String Attributes Connection String Attribute Default value Description OracleConnection Properties 4-66 Oracle Data Provider for .NET Developer’s Guide Example This code example shows that the case of the User Id attribute value is not preserved unless it is surrounded by double quotes. The example also demonstrates when connection pools are created and when connections are drawn from the connection pool. /* Database Setup grant connect , resource to "MYSCHEMA" identified by MYPWD; grant connect , resource to "MySchema" identified by MYPWD; */ // C# using System; using Oracle.DataAccess.Client; class ConnectionStringSample { static void Main() { string constr1 = "User Id=myschema;Password=mypwd;Data Source=oracle"; string constr2 = "User Id=MySchema;Password=MyPwd;Data Source=oracle"; string constr3 = "User Id=\"MYSCHEMA\";Password=MYPWD;Data Source=oracle"; string constr4 = "User Id=\"MySchema\";Password=MYPWD;Data Source=oracle"; Proxy Password empty string Password of the proxy user This connection string attribute specifies the password of the middle-tier user or the proxy user. This user establishes a connection on behalf of a client user specified by the User Id attribute. ODP.NET attempts to establish a proxy connection if either the Proxy User Id or the Proxy Password attribute is set to a non-empty string. Statement Cache Purge False Purges the Statement Cache If Statement Caching is enabled, setting this attribute to True purges the Statement Cache when the connection goes back to the pool. Statement Cache Size 0 Enables Statement Cache and sets the cache size Statement Cache Size is the maximum number of statements that can be cached. A value greater than zero enables Statement Caching and sets the cache size to itself. This value should not be greater than the value of the OPEN_ CURSORS parameter set in the init.ora database configuration file. User Id empty string Oracle user name This attribute specifies the Oracle user name. The case of this attribute value is preserved if it is surrounded by double quotes. For the user to connect to an Oracle database using operating system authentication, set the User Id to "/". Any Password attribute setting is ignored in this case. Validate Connection False Enables or disables validation of connections coming from the pool Validation causes a round-trip to the database for each connection. Therefore, it should only be used when necessary. Table 4–27 (Cont.) Supported Connection String Attributes Connection String Attribute Default value Description OracleConnection Class Oracle Data Provider for .NET Classes 4-67 string constr5 = " User Id=myschema;Password=mypwd;Data Source=oracle; "; string constr6 = "User Id=myschema;Password=mypwd;Data Source=oracle;pooling=true"; // Connect as "MYSCHEMA/MYPWD" // NOTE: the password is case insensitive // A new connection and a new connection pool X is created OracleConnection con1 = new OracleConnection(constr1); con1.Open(); // Place connection back into connection pool X con1.Dispose(); // Connect as "MYSCHEMA/MYPWD" // The connection from pool X is obtained. No new connection created. OracleConnection con2 = new OracleConnection(constr2); con2.Open(); // Place connection back into connection pool X con2.Dispose(); // Connect as "MYSCHEMA/MYPWD" // The connection from pool X is obtained. No new connection created. OracleConnection con3 = new OracleConnection(constr3); con3.Open(); // Place connection back into connection pool X con3.Dispose(); // Connect as "MySchema/MYPWD" // A new connection and connection pool Y is created OracleConnection con4 = new OracleConnection(constr4); con4.Open(); // Place connection back into connection pool Y con4.Dispose(); // Connect as "MYSCHEMA/MYPWD" // The connection from pool X is obtained // Extra spaces or semi-colons in the connection string do not force // new pools to be created OracleConnection con5 = new OracleConnection(constr5); con5.Open(); // Place connection back into connection pool X con5.Dispose(); // Connect as "MYSCHEMA/MYPWD" // A connection is obtained from Connection Pool X. // It's important to note that different connection strings do // not necessarily mean that ODP.NET will create different // connection pools for them. In other words, ODP.NET does not // use exact string matching alogrithm to determine whether // a new connection pool needs to be created or not. // Instead, it creates connection pools based on the uniqueness // of attribute values settings in the connection string. OracleConnection con6 = new OracleConnection(constr6); con6.Open(); // Place connection back into connection pool X OracleConnection Properties 4-68 Oracle Data Provider for .NET Developer’s Guide con6.Dispose(); } } ConnectionTimeout This property specifies the maximum amount of time that the Open() method can take to obtain a pooled connection before terminating the request. Declaration // C# public int ConnectionTimeout {get;} Property Value The maximum time allowed for a pooled connection request, in seconds. Implements IDbConnection Remarks The default value is 15. Setting this property to 0 allows the pooled connection request to wait for a free connection without a time limit. The timeout takes effect only for pooled connection requests and not for new connection requests. DataSource This property specifies the Oracle Net Service Name (formerly known as TNS alias) that identifies an Oracle database instance. Declaration // C# public string DataSource {get;} Property Value The Oracle Net Service Name. Remarks The default value of this property is an empty string See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-69 ServerVersion This property specifies the version number of the Oracle database to which the OracleConnection has established a connection. Declaration // C# public string ServerVersion {get;} Property Value The version of the Oracle database, for example "9.2.0.1.0." Exceptions InvalidOperationException - The connection is closed. Remarks The default is an empty string. State This property specifies the current state of the connection. Declaration // C# public ConnectionState State {get;} Property Value The ConnectionState of the connection. Implements IDbConnection Remarks ODP.NET supports ConnectionState.Closed and ConnectionState.Open for this property. The default value is ConnectionState.Closed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Properties 4-70 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-71 OracleConnection Public Methods OracleConnection public methods are listed in Table 4–28. BeginTransaction BeginTransaction methods begin local transactions. Overload List ■ BeginTransaction() Table 4–28 OracleConnection Public Methods Public Method Description BeginTransaction Begins a local transaction (Overloaded) ChangeDatabase Not Supported Clone Creates a copy of an OracleConnection object Close Closes the database connection CreateCommand Creates and returns an OracleCommand object associated with the OracleConnection object CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component EnlistDistributedTransaction Enables applications to explicitly enlist in a specified distributed transaction Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetSessionInfo Returns or refreshes the property values of the OracleGlobalization object that represents the globalization settings of the session (Overloaded) GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Open Opens a database connection with the property settings specified by the ConnectionString OpenWithNewPassword Opens a new connection with the new password PurgeStatementCache Flushes the Statement Cache by closing all open cursors on the server, when Statement Caching is enabled SetSessionInfo Alters the session's globalization settings with the property values provided by the OracleGlobalization object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Public Methods 4-72 Oracle Data Provider for .NET Developer’s Guide This method begins a local transaction. ■ BeginTransaction(IsolationLevel) This method begins a local transaction with the specified isolation level. BeginTransaction() This method begins a local transaction. Declaration // C# public OracleTransaction BeginTransaction(); Return Value An OracleTransaction object representing the new transaction. Implements IDbConnection Exceptions InvalidOperationException - A transaction has already been started. Remarks The transaction is created with its isolation level set to its default value of IsolationLevel.ReadCommitted. All further operations related to the transaction must be performed on the returned OracleTransaction object. BeginTransaction(IsolationLevel) This method begins a local transaction with the specified isolation level. Declaration // C# public OracleTransaction BeginTransaction(IsolationLevel isolationLevel); Parameters ■ isolationLevel The isolation level for the new transaction. Return Value An OracleTransaction object representing the new transaction. Implements IDbConnection See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-73 Exceptions InvalidOperationException - A transaction has already been started. ArgumentException - The isolationLevel specified is invalid. Remarks The following two isolation levels are supported: ■ IsolationLevel.ReadCommitted ■ IsolationLevel.Serializable Requesting other isolation levels causes an exception. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class BeginTransactionSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand object using the connection object OracleCommand cmd = con.CreateCommand(); // Start a transaction OracleTransaction txn = con.BeginTransaction(IsolationLevel.ReadCommitted); // Update EMP table cmd.CommandText = "update emp set sal = sal + 100"; cmd.ExecuteNonQuery(); // Rollback transaction txn.Rollback(); Console.WriteLine("Transaction rolledback"); // Clean up txn.Dispose(); cmd.Dispose(); con.Dispose(); } } Clone This method creates a copy of an OracleConnection object. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Public Methods 4-74 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public object Clone(); Return Value An OracleConnection object. Implements ICloneable Remarks The cloned object has the same property values as that of the object being cloned. Example // C# using System; using Oracle.DataAccess.Client; class CloneSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Need a proper casting for the return value when cloned OracleConnection clonedCon = (OracleConnection)con.Clone(); // Cloned connection is always closed, regardless of its source, // But the connection string should be identical clonedCon.Open(); // Close and Dispose OracleConnection object clonedCon.Dispose(); } } Close This method closes the connection to the database. Declaration // C# public void Close(); Implements IDbConnection See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-75 Remarks Performs the following: ■ Rolls back any pending transactions. ■ Places the connection to the connection pool if connection pooling is enabled. Even if connection pooling is enabled, the connection can be closed if it exceeds the connection lifetime specified in the connection string. If connection pooling is disabled, the connection is closed. ■ Closes the connection to the database. The connection can be reopened using Open(). CreateCommand This method creates and returns an OracleCommand object associated with the OracleConnection object. Declaration // C# public OracleCommand CreateCommand(); Return Value The OracleCommand object. Implements IDbConnection Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class CreateCommandSample { static void Main() { // Connect string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Execute a SQL SELECT OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select * from emp"; OracleDataReader reader = cmd.ExecuteReader(); // Print all employee numbers while (reader.Read()) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Public Methods 4-76 Oracle Data Provider for .NET Developer’s Guide Console.WriteLine(reader.GetInt32(0)); // Clean up reader.Dispose(); cmd.Dispose(); con.Dispose(); } } EnlistDistributedTransaction This method enables applications to explicitly enlist in a specific distributed transaction after a connection has been opened. Declaration // C# public void EnlistDistributedTransaction(ITransaction transaction); Parameters ■ transaction An ITransaction interface Exception InvalidOperationException - The connection is part of a local transaction. Remarks EnlistDistributedTransaction enables objects to enlist in a specific transaction that is passed to the method. The ITransaction interface can be obtained by applying an (ITransaction) cast to the ContexUtil.Transaction property within the component that started the distributed transaction. The connection must be open before calling this method or an InvalidOperationException is thrown. If a connection is part of a local transaction that was started implicitly or explicitly while attempting to enlist in a distributed transaction, the local transaction is rolled back and an exception is thrown. By default, distributed transactions roll back, unless the method-level AutoComplete declaration is set. Invoking the commit on the ITranasction raises an exception. Invoking the rollback on the ITransaction method and calling ContextUtil.SetComplete on the same distributed transaction raises an exception. Example Application: See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-77 // C# // This is the class that will utilize the Enterprise Services // component. This module needs to be built as an executable. using System; using System.EnterpriseServices; using ConnectionSample_Comp; class EnlistDistributedTransactionSample_App { static void Main() { ESComponent comp = new ESComponent(); comp.DoWork(); } } Component: // C# // This module needs to be // 1) built as a component DLL/Library // 2) built with a strong name using System; using System.Data; using Oracle.DataAccess.Client; using System.EnterpriseServices; [Transaction(TransactionOption.RequiresNew)] public class EnlistDistributedTransactionSample_Comp : ServicedComponent { public void DoWork() { string constr = "User Id=scott;Password=tiger;Data Source=oracle;enlist=false"; OracleConnection con = new OracleConnection(constr); con.Open(); // Enlist in a distrubuted transaction con.EnlistDistributedTransaction((ITransaction)ContextUtil.Transaction); // Update EMP table OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "UPDATE emp set sal = sal + .01"; cmd.ExecuteNonQuery(); // Commit ContextUtil.SetComplete(); // Dispose OracleConnection object con.Dispose(); } } OracleConnection Public Methods 4-78 Oracle Data Provider for .NET Developer’s Guide GetSessionInfo GetSessionInfo returns or refreshes an OracleGlobalization object that represents the globalization settings of the session. Overload List: ■ GetSessionInfo() This method returns a new instance of the OracleGlobalization object that represents the globalization settings of the session. ■ GetSessionInfo(OracleGlobalization) This method refreshes the provided OracleGlobalization object with the globalization settings of the session. GetSessionInfo() This method returns a new instance of the OracleGlobalization object that represents the globalization settings of the session. Declaration // C# public OracleGlobalization GetSessionInfo(); Return Value The newly created OracleGlobalization object. Example // C# using System; using Oracle.DataAccess.Client; class GetSessionInfoSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ http://msdn.microsoft.com/library for detailed information about this Microsoft .NET Framework 1.1 feature See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-79 // Get session info from connection object OracleGlobalization info = con.GetSessionInfo(); // Execute SQL SELECT OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select TO_CHAR(hiredate) from emp"; Console.WriteLine("Hire Date ({0}): {1}", info.DateFormat, cmd.ExecuteScalar()); // Update session info info.DateFormat = "YYYY-MM-DD"; con.SetSessionInfo(info); // Execute SQL SELECT again Console.WriteLine("Hire Date ({0}): {1}", info.DateFormat, cmd.ExecuteScalar()); // Clean up cmd.Dispose(); con.Dispose(); } } GetSessionInfo(OracleGlobalization) This method refreshes the provided OracleGlobalization object with the globalization settings of the session. Declaration // C# public void GetSessionInfo(OracleGlobalization oraGlob); Parameters ■ oraGlob The OracleGlobalization object to be updated. Open This method opens a connection to an Oracle database. Declaration // C# public void Open(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Public Methods 4-80 Oracle Data Provider for .NET Developer’s Guide Implements IDbConnection Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The connection is already opened or the connection string is null or empty. Remarks The connection is obtained from the pool if connection pooling is enabled. Otherwise, a new connection is established. It is possible that the pool does not contain any unused connections when the Open() method is invoked. In this case, a new connection is established. If no connections are available within the specified connection timeout value, when the Max Pool Size is reached, an OracleException is thrown. OpenWithNewPassword This method opens a new connection with the new password. Declaration // C# public void OpenWithNewPassword(string newPassword); Parameters ■ newPassword A string that contains the new password. Remarks This method uses the ConnectionString property settings to establish a new connection. The old password must be provided in the connection string as the Password attribute value. This method can only be called on an OracleConnection in the closed state. PurgeStatementCache This method flushes the Statement Cache by closing all open cursors on the server, when Statement Caching is enabled. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "Password Expiration" on page 3-6 OracleConnection Class Oracle Data Provider for .NET Classes 4-81 Declaration // C# public void PurgeStatementCache(); Remarks Flushing the statement cache repetitively results in decreased performance and may negate the performance benefit gained by enabling the statement cache. Statement Caching remains enabled after the call to PurgeStatementCache. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class PurgeStatementCacheSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle;" + "Statement Cache Size=20"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand("select * from emp", con); cmd.CommandType = CommandType.Text; OracleDataReader reader = cmd.ExecuteReader(); // Purge Statement Cache con.PurgeStatementCache(); // Close and Dispose OracleConnection object Console.WriteLine("Statement Cache Flushed"); con.Close(); con.Dispose(); } } SetSessionInfo This method alters the session's globalization settings with all the property values specified in the provided OracleGlobalization object. Declaration // C# See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "Statement Caching" on page 3-21 ■ ConnectionString on page 4-62 OracleConnection Public Methods 4-82 Oracle Data Provider for .NET Developer’s Guide public void SetSessionInfo(OracleGlobalization oraGlob); Parameters ■ oraGlob An OracleGlobalization object. Remarks Calling this method is equivalent to calling an ALTER SESSION SQL on the session. Example // C# using System; using Oracle.DataAccess.Client; class SetSessionInfoSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Get session info from connection object OracleGlobalization info = con.GetSessionInfo(); // Execute SQL SELECT OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select TO_CHAR(hiredate) from emp"; Console.WriteLine("Hire Date ({0}): {1}", info.DateFormat, cmd.ExecuteScalar()); // Update session info info.DateFormat = "YYYY-MM-DD"; con.SetSessionInfo(info); // Execute SQL SELECT again Console.WriteLine("Hire Date ({0}): {1}", info.DateFormat, cmd.ExecuteScalar()); // Clean up cmd.Dispose(); con.Dispose(); } } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-83 OracleConnection Events OracleConnection events are listed in Table 4–29. Failover This event is triggered when an Oracle failover occurs. Declaration // C# public event OracleFailoverEventHandler Failover; Event Data The event handler receives an OracleFailoverEventArgs object which exposes the following properties containing information about the event. ■ FailoverType Indicates the type of the failover. ■ FailoverEvent Indicates the state of the failover. InfoMessage This event is triggered for any message or warning sent by the database. Declaration // C# public event OracleInfoMessageEventHandler InfoMessage; Table 4–29 OracleConnection Events Event Name Description Disposed Inherited from Component Failover An event that is triggered when an Oracle failover occurs InfoMessage An event that is triggered for any message or warning sent by the database StateChange An event that is triggered when the connection state changes See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "OracleFailoverEventArgs Properties" on page 7-6 OracleConnection Events 4-84 Oracle Data Provider for .NET Developer’s Guide Event Data The event handler receives an OracleInfoMessageEventArgs object which exposes the following properties containing information about the event. ■ Errors The collection of errors generated by the data source. ■ Message The error text generated by the data source. ■ Source The name of the object that generated the error. Remarks In order to respond to warnings and messages from the database, the client should create an OracleInfoMessageEventHandler delegate to listen to this event. StateChange This event is triggered when the connection state changes. Declaration // C# public event StateChangeEventHandler StateChange; Event Data The event handler receives a StateChangeEventArgs object which exposes the following properties containing information about the event. ■ CurrentState The new state of the connection. ■ OriginalState The original state of the connection. Remarks The StateChange event is raised after a connection changes state, whenever an explicit call is made to Open, Close or Dispose. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "OracleInfoMessageEventArgs Properties" on page 4-190 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members OracleConnection Class Oracle Data Provider for .NET Classes 4-85 OracleConnection Event Delegates OracleConnection event delegates are listed in Table 4–30. OracleFailoverEventHandler This event delegate handles the Failover event. OracleInfoMessageEventHandler This event delegate handles the InfoMessage event. StateChangeEventHandler This event delegate handles the StateChange event. Table 4–30 OracleConnection Event Delegates Event Delegate Name Description OracleFailoverEventHandler An event delegate that handles the Failover event OracleInfoMessageEventHandler An event delegate that handles the InfoMessage event StateChangeEventHandler An event delegate that handles the StateChange event See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "OracleTransaction Class" on page 4-266 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ "OracleInfoMessageEventHandler Delegate" on page 4-193 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleConnection Class ■ OracleConnection Members ■ Microsoft ADO.NET documentation for a description of StateChangeEventHandler OracleDataAdapter Class 4-86 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Class An OracleDataAdapter object represents a data provider object that populates the DataSet and updates changes in the DataSet to the Oracle database. Class Inheritance Object MarshalByRefObject Component DataAdapter DbDataAdapter OracleDataAdapter Declaration // C# public sealed class OracleDataAdapter : DbDataAdapter, IDbDataAdapter Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example The following example uses the OracleDataAdapter and the dataset to update the EMP table: // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleDataAdapterSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; string cmdstr = "SELECT empno, sal from emp"; // Create the adapter with the selectCommand txt and the // connection string OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr); // Create the builder for the adapter to automatically generate // the Command when needed OracleCommandBuilder builder = new OracleCommandBuilder(adapter); // Create and fill the DataSet using the EMP DataSet dataset = new DataSet(); adapter.Fill(dataset, "EMP"); // Get the EMP table from the dataset DataTable table = dataset.Tables["EMP"]; OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-87 // Indicate DataColumn EMPNO is unique // This is required by the OracleCommandBuilder to update the EMP table table.Columns["EMPNO"].Unique = true; // Get the first row from the EMP table DataRow row = table.Rows[0]; // Update the salary double sal = double.Parse(row["SAL"].ToString()); row["SAL"] = sal + .01; // Now update the EMP using the adapter // The OracleCommandBuilder will create the UpdateCommand for the // adapter to update the EMP table adapter.Update(dataset, "EMP"); Console.WriteLine("Row updated successfully"); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Members ■ OracleDataAdapter Constructors ■ OracleDataAdapter Static Methods ■ OracleDataAdapter Properties ■ OracleDataAdapter Public Methods ■ OracleDataAdapter Events ■ OracleDataAdapter Event Delegates OracleDataAdapter Members 4-88 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Members OracleDataAdapter members are listed in the following tables: OracleDataAdapter Constructors OracleDataAdapter constructors are listed in Table 4–31. OracleDataAdapter Static Methods OracleDataAdapter static methods are listed in Table 4–32. OracleDataAdapter Properties OracleDataAdapter properties are listed in Table 4–33. OracleDataAdapter Public Methods OracleDataAdapter public methods are listed in Table 4–34. Table 4–31 OracleDataAdapter Constructors Constructor Description OracleDataAdapter Constructors Instantiates a new instance of OracleDataAdapter class (Overloaded) Table 4–32 OracleDataAdapter Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–33 OracleDataAdapter Properties Name Description AcceptChangesDuringFill Inherited from DataAdapter Container Inherited from Component ContinueUpdateOnError Inherited from DataAdapter DeleteCommand A SQL statement or stored procedure to delete rows from an Oracle database InsertCommand A SQL statement or stored procedure to insert new rows into an Oracle database MissingMappingAction Inherited from DataAdapter MissingSchemaAction Inherited from DataAdapter Requery Determines whether the SelectCommand is reexecuted on the next call to Fill SafeMapping Creates a mapping between column names in the result set to .NET types, to preserve the data SelectCommand A SQL statement or stored procedure that returns a single or multiple result set Site Inherited from Component TableMappings Inherited from DataAdapter UpdateCommand A SQL statement or stored procedure to update rows from the DataSet to an Oracle database OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-89 OracleDataAdapter Events OracleDataAdapter events are listed in Table 4–35. OracleDataAdapter Event Delegates OracleDataAdapter event delegates are listed in Table 4–36. Table 4–34 OracleDataAdapter Public Methods Public Method Description CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component Equals Inherited from Object (Overloaded) Fill Adds or refreshes rows in the DataSet to match the data in the Oracle database (Overloaded) FillSchema Inherited from DbDataAdapter GetFillParameters Inherited from DbDataAdapter GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject ToString Inherited from Object Update Inherited from DbDataAdapter Table 4–35 OracleDataAdapter Events Event Delegate Name Description EventHandler Inherited from Component FillErrorEventHandler Inherited from DbDataAdapter OracleRowUpdatedEventHandler Event Delegate for the RowUpdated Event OracleRowUpdatingEventHandler Event Delegate for the RowUpdating Event Table 4–36 OracleDataAdapter Event Delegates Event Delegate Name Description EventHandler Inherited from Component FillErrorEventHandler Inherited from DbDataAdapter OracleRowUpdatedEventHandler Event Delegate for the RowUpdated Event OracleRowUpdatingEventHandler Event Delegate for the RowUpdating Event OracleDataAdapter Constructors 4-90 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Constructors OracleDataAdapter constructors create new instances of an OracleDataAdapter class. Overload List: ■ OracleDataAdapter() This constructor creates an instance of an OracleDataAdapter class. ■ OracleDataAdapter(OracleCommand) This constructor creates an instance of an OracleDataAdapter class with the provided OracleCommand as the SelectCommand. ■ OracleDataAdapter(string, OracleConnection) This constructor creates an instance of an OracleDataAdapter class with the provided OracleConnection object and the command text for the SelectCommand. ■ OracleDataAdapter(string, string) This constructor creates an instance of an OracleDataAdapter class with the provided connection string and the command text for the SelectCommand. OracleDataAdapter() This constructor creates an instance of an OracleDataAdapter class with no arguments. Declaration // C# public OracleDataAdapter(); Remarks Initial values are set for the following OracleDataAdapter properties as indicated: ■ MissingMappingAction = MissingMappingAction.Passthrough ■ MissingSchemaAction = MissingSchemaAction.Add OracleDataAdapter(OracleCommand) This constructor creates an instance of an OracleDataAdapter class with the provided OracleCommand as the SelectCommand. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-91 Declaration // C# public OracleDataAdapter(OracleCommand selectCommand); Parameters ■ selectCommand The OracleCommand that is to be set as the SelectCommand property. Remarks Initial values are set for the following OracleDataAdapter properties as indicated: ■ MissingMappingAction = MissingMappingAction.Passthrough ■ MissingSchemaAction = MissingSchemaAction.Add OracleDataAdapter(string, OracleConnection) This constructor creates an instance of an OracleDataAdapter class with the provided OracleConnection object and the command text for the SelectCommand. Declaration // C# public OracleDataAdapter(string selectCommandText, OracleConnection selectConnection); Parameters ■ selectCommandText The string that is set as the CommandText of the SelectCommand property of the OracleDataAdapter. ■ selectConnection The OracleConnection to connect to the Oracle database. Remarks The OracleDataAdapter opens and closes the connection, if it is not already open. If the connection is open, it must be explicitly closed. Initial values are set for the following OracleDataAdapter properties as indicated: ■ MissingMappingAction = MissingMappingAction.Passthrough ■ MissingSchemaAction = MissingSchemaAction.Add See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Constructors 4-92 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter(string, string) This constructor creates an instance of an OracleDataAdapter class with the provided connection string and the command text for the SelectCommand. Declaration // C# public OracleDataAdapter(string selectCommandText, string selectConnectionString); Parameters ■ selectCommandText The string that is set as the CommandText of the SelectCommand property of the OracleDataAdapter. ■ selectConnectionString The connection string. Remarks Initial values are set for the following OracleDataAdapter properties as indicated: ■ MissingMappingAction = MissingMappingAction.Passthrough ■ MissingSchemaAction = MissingSchemaAction.Add See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-93 OracleDataAdapter Static Methods OracleDataAdapter static methods are listed in Table 4–37. Table 4–37 OracleDataAdapter Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Properties 4-94 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Properties OracleDataAdapter properties are listed in Table 4–38. DeleteCommand This property is a SQL statement or stored procedure to delete rows from an Oracle database. Declaration // C# public OracleCommand DeleteCommand {get; set;} Property Value An OracleCommand used during the Update call to delete rows from tables in the Oracle database, corresponding to the deleted rows in the DataSet. Remarks Default = null Table 4–38 OracleDataAdapter Properties Name Description AcceptChangesDuringFill Inherited from DataAdapter Container Inherited from Component ContinueUpdateOnError Inherited from DataAdapter DeleteCommand A SQL statement or stored procedure to delete rows from an Oracle database InsertCommand A SQL statement or stored procedure to insert new rows into an Oracle database MissingMappingAction Inherited from DataAdapter MissingSchemaAction Inherited from DataAdapter Requery Determines whether the SelectCommand is reexecuted on the next call to Fill SafeMapping Creates a mapping between column names in the result set to .NET types, to preserve the data SelectCommand A SQL statement or stored procedure that returns a single or multiple result set Site Inherited from Component TableMappings Inherited from DataAdapter UpdateCommand A SQL statement or stored procedure to update rows from the DataSet to an Oracle database See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-95 If there is primary key information in the DataSet, the DeleteCommand can be automatically generated using the OracleCommandBuilder, if no command is provided for this. InsertCommand This property is a SQL statement or stored procedure to insert new rows into an Oracle database. Declaration // C# public OracleCommand InsertCommand {get; set;} Property Value An OracleCommand used during the Update call to insert rows into a table, corresponding to the inserted rows in the DataSet. Remarks Default = null If there is primary key information in the DataSet, the InsertCommand can be automatically generated using the OracleCommandBuilder, if no command is provided for this property. Requery This property determines whether the SelectCommand is reexecuted on the next call to Fill. Declaration // C# public Boolean Requery {get; set;} Property Value Returns true if the SelectCommand is reexecuted on the next call to Fill; otherwise, returns false. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Properties 4-96 Oracle Data Provider for .NET Developer’s Guide SafeMapping This property creates a mapping between column names in the result set to .NET types that represent column values in the DataSet, to preserve the data. Declaration // C# public Hashtable SafeMapping {get; set;} Property Value A hashtable. Remarks Default = null The SafeMapping property is used, when necessary, to preserve data in the following types: ■ DATE ■ TimeStamp (refers to all TimeStamp objects) ■ INTERVAL DAY TO SECOND ■ NUMBER Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class SafeMappingSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; // In this SELECT statement, EMPNO, HIREDATE and SALARY must be // preserved using safe type mapping. string cmdstr = "SELECT EMPNO, ENAME, HIREDATE, SAL FROM EMP"; // Create the adapter with the selectCommand txt and the connection string OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr); // Get the connection from the adapter OracleConnection connection = adapter.SelectCommand.Connection; // Create the safe type mapping for the adapter // which can safely map column data to byte arrays, where See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-97 // applicable. By executing the following statement, EMPNO, HIREDATE AND // SALARY columns will be mapped to byte[] adapter.SafeMapping.Add("*", typeof(byte[])); // Map HIREDATE to a string // If the column name in the EMP table is case-sensitive, // the safe type mapping column name must be case-sensitive. adapter.SafeMapping.Add("HIREDATE", typeof(string)); // Map EMPNO to a string // If the column name in the EMP table is case-sensitive, // the safe type mapping column name must also be case-sensitive. adapter.SafeMapping.Add("EMPNO", typeof(string)); adapter.SafeMapping.Add("SAL", typeof(string)); // Create and fill the DataSet using the EMP DataSet dataset = new DataSet(); adapter.Fill(dataset, "EMP"); // Get the EMP table from the dataset DataTable table = dataset.Tables["EMP"]; // Get the first row from the EMP table DataRow row = table.Rows[0]; // Print out the row info Console.WriteLine("EMPNO Column: type = " + row["EMPNO"].GetType() + "; value = " + row["EMPNO"]); Console.WriteLine("ENAME Column: type = " + row["ENAME"].GetType() + "; value = " + row["ENAME"]); Console.WriteLine("HIREDATE Column: type = " + row["HIREDATE"].GetType()+ "; value = " + row["HIREDATE"]); Console.WriteLine("SAL Column: type = " + row["SAL"].GetType() + "; value = " + row["SAL"]); } } SelectCommand This property is a SQL statement or stored procedure that returns single or multiple result sets. Declaration // C# public OracleCommand SelectCommand {get; set;} Property Value An OracleCommand used during the Fill call to populate the selected rows to the DataSet. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Safe Type Mapping" on page 3-49 OracleDataAdapter Properties 4-98 Oracle Data Provider for .NET Developer’s Guide Remarks Default = null If the SelectCommand does not return any rows, no tables are added to the dataset and no exception is raised. If the SELECT statement selects from a VIEW, no key information is retrieved when a FillSchema() or a Fill() with MissingSchemaAction.AddWithKey is invoked. UpdateCommand This property is a SQL statement or stored procedure to update rows from the DataSet to an Oracle database. Declaration // C# public OracleCommand UpdateCommand {get; set;} Property Value An OracleCommand used during the Update call to update rows in the Oracle database, corresponding to the updated rows in the DataSet. Remarks Default = null If there is primary key information in the DataSet, the UpdateCommand can be automatically generated using the OracleCommandBuilder, if no command is provided for this property. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-99 OracleDataAdapter Public Methods OracleDataAdapter public methods are listed in Table 4–39. Fill Fill populates or refreshes the specified DataTable or DataSet. Overload List: ■ Fill(DataTable, OracleRefCursor) This method adds or refreshes rows in the specified DataTable to match those in the provided OracleRefCursor object. ■ Fill(DataSet, OracleRefCursor) This method adds or refreshes rows in the DataSet to match those in the provided OracleRefCursor object. ■ Fill(DataSet, string, OracleRefCursor) This method adds or refreshes rows in the specified source table of the DataSet to match those in the provided OracleRefCursor object. ■ Fill(DataSet, int, int, string, OracleRefCursor) This method adds or refreshes rows in a specified range in the DataSet to match rows in the provided OracleRefCursor object. Table 4–39 OracleDataAdapter Public Methods Public Method Description CreateObjRef Inherited from MarshalByRefObject Dispose Inherited from Component Equals Inherited from Object (Overloaded) Fill Adds or refreshes rows in the DataSet to match the data in the Oracle database (Overloaded) FillSchema Inherited from DbDataAdapter GetFillParameters Inherited from DbDataAdapter GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject ToString Inherited from Object Update Inherited from DbDataAdapter See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Public Methods 4-100 Oracle Data Provider for .NET Developer’s Guide Fill(DataTable, OracleRefCursor) This method adds or refreshes rows in the specified DataTable to match those in the provided OracleRefCursor object. Declaration // C# public int Fill(DataTable dataTable, OracleRefCursor refCursor); Parameters ■ dataTable The DataTable object being populated. ■ refCursor The OracleRefCursor that rows are being retrieved from. Return Value The number of rows added to or refreshed in the DataTable. Exceptions ArgumentNullException - The dataTable or refCursor parameter is null. InvalidOperationException - The OracleRefCursor is already being used to fetch data. NotSupportedException - The SafeMapping type is not supported. Remarks No schema or key information is provided, even if the Fill method is called with MissingSchemaAction set to MissingSchemaAction.AddWithKey. Fill(DataSet, OracleRefCursor) This method adds or refreshes rows in the DataSet to match those in the provided OracleRefCursor object. Declaration // C# public int Fill(DataSet dataSet, OracleRefCursor refCursor); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-101 Parameters ■ dataSet The DataSet object being populated. ■ refCursor The OracleRefCursor that rows are being retrieved from. Return Value Returns the number of rows added or refreshed in the DataSet. Exceptions ArgumentNullException - The dataSet or refCursor parameter is null. InvalidOperationException - The OracleRefCursor is already being used to fetch data. InvalidOperationException - The OracleRefCursor is ready to fetch data. NotSupportedException - The SafeMapping type is not supported. Remarks If there is no DataTable to refresh, a new DataTable named Table is created and populated using the provided OracleRefCursor object. No schema or key information is provided, even if the Fill method is called with MissingSchemaAction set to MissingSchemaAction.AddWithKey. Fill(DataSet, string, OracleRefCursor) This method adds or refreshes rows in the specified source table of the DataSet to match those in the provided OracleRefCursor object. Declaration // C# public int Fill(DataSet dataSet, string srcTable, OracleRefCursor refCursor); Parameters ■ dataSet The DataSet object being populated. ■ srcTable The name of the source table used in the table mapping. ■ refCursor The OracleRefCursor that rows are being retrieved from. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Public Methods 4-102 Oracle Data Provider for .NET Developer’s Guide Return Value Returns the number of rows added or refreshed into the DataSet. Exceptions ArgumentNullException - The dataSet or refCursor parameter is null. InvalidOperationException - The OracleRefCursor is already being used to fetch data or the source table name is invalid. NotSupportedException - The SafeMapping type is not supported. Remarks No schema or key information is provided, even if the Fill method is called with MissingSchemaAction set to MissingSchemaAction.AddWithKey. Fill(DataSet, int, int, string, OracleRefCursor) This method adds or refreshes rows in a specified range in the DataSet to match rows in the provided OracleRefCursor object. Declaration // C# public int Fill(DataSet dataSet, int startRecord, int maxRecords, string srcTable, OracleRefCursor refCursor); Parameters ■ dataSet The DataSet object being populated. ■ startRecord The record number to start with. ■ maxRecords The maximum number of records to obtain. ■ srcTable The name of the source table used in the table mapping. ■ refCursor The OracleRefCursor that rows are being retrieved from. Return Value This method returns the number of rows added or refreshed in the DataSet. This does not include rows affected by statements that do not return rows. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-103 Exceptions ArgumentNullException - The dataSet or refCursor parameter is null. InvalidOperationException - The OracleRefCursor is already being used to fetch data or the source table name is invalid. NotSupportedException - The SafeMapping type is not supported. Remarks No schema or key information is provided, even if the Fill method is called with MissingSchemaAction set to MissingSchemaAction.AddWithKey. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleDataAdapter Requery Property" on page 3-51 OracleDataAdapter Events 4-104 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Events OracleDataAdapter events are listed in Table 4–40. RowUpdated This event is raised when row(s) have been updated by the Update() method. Declaration // C# public event OracleRowUpdatedEventHandler RowUpdated; Event Data The event handler receives an OracleRowUpdatedEventArgs object which exposes the following properties containing information about the event. ■ Command The OracleCommand executed during the Update. ■ Errors (inherited from RowUpdatedEventArgs) The exception, if any, is generated during the Update. ■ RecordsAffected (inherited from RowUpdatedEventArgs) The number of rows modified, inserted, or deleted by the execution of the Command. ■ Row (inherited from RowUpdatedEventArgs) The DataRow sent for Update. ■ StatementType (inherited from RowUpdatedEventArgs) The type of SQL statement executed. ■ Status (inherited from RowUpdatedEventArgs) The UpdateStatus of the Command. ■ TableMapping (inherited from RowUpdatedEventArgs) The DataTableMapping used during the Update. Table 4–40 OracleDataAdapter Events Event Name Description Disposed Inherited from Component FillError Inherited from DbDataAdapter RowUpdated This event is raised when row(s) have been updated by the Update() method RowUpdating This event is raised when row data are about to be updated to the database See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-105 Example The following example shows how to use the RowUpdating and RowUpdated events. // C# using System; using System.Data; using Oracle.DataAccess.Client; class RowUpdatedSample { // Event handler for RowUpdating event protected static void OnRowUpdating(object sender, OracleRowUpdatingEventArgs e) { Console.WriteLine("Row updating....."); Console.WriteLine("Event arguments:"); Console.WriteLine("Command Text: " + e.Command.CommandText); Console.WriteLine("Command Type: " + e.StatementType); Console.WriteLine("Status: " + e.Status); } // Event handler for RowUpdated event protected static void OnRowUpdated(object sender, OracleRowUpdatedEventArgs e) { Console.WriteLine("Row updated....."); Console.WriteLine("Event arguments:"); Console.WriteLine("Command Text: " + e.Command.CommandText); Console.WriteLine("Command Type: " + e.StatementType); Console.WriteLine("Status: " + e.Status); } static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; string cmdstr = "SELECT EMPNO, ENAME, SAL FROM EMP"; // Create the adapter with the selectCommand txt and the // connection string OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr); // Create the builder for the adapter to automatically generate // the Command when needed OracleCommandBuilder builder = new OracleCommandBuilder(adapter); // Create and fill the DataSet using the EMP DataSet dataset = new DataSet(); adapter.Fill(dataset, "EMP"); // Get the EMP table from the dataset DataTable table = dataset.Tables["EMP"]; // Indicate DataColumn EMPNO is unique // This is required by the OracleCommandBuilder to update the EMP table table.Columns["EMPNO"].Unique = true; // Get the first row from the EMP table DataRow row = table.Rows[0]; OracleDataAdapter Events 4-106 Oracle Data Provider for .NET Developer’s Guide // Update the salary double sal = double.Parse(row["SAL"].ToString()); row["SAL"] = sal + .01; // Set the event handlers for the RowUpdated and the RowUpdating event // the OnRowUpdating() method will be triggered before the update, and // the OnRowUpdated() method will be triggered after the update adapter.RowUpdating += new OracleRowUpdatingEventHandler(OnRowUpdating); adapter.RowUpdated += new OracleRowUpdatedEventHandler(OnRowUpdated); // Now update the EMP using the adapter // The OracleCommandBuilder will create the UpdateCommand for the // adapter to update the EMP table // The OnRowUpdating() and the OnRowUpdated() methods will be triggered adapter.Update(dataset, "EMP"); } } RowUpdating This event is raised when row data are about to be updated to the database. Declaration // C# public event OracleRowUpdatingEventHandler RowUpdating; Event Data The event handler receives an OracleRowUpdatingEventArgs object which exposes the following properties containing information about the event. ■ Command The OracleCommand executed during the Update. ■ Errors (inherited from RowUpdatingEventArgs) The exception, if any, is generated during the Update. ■ Row (inherited from RowUpdatingEventArgs) The DataRow sent for Update. ■ StatementType (inherited from RowUpdatingEventArgs) The type of SQL statement executed. ■ Status (inherited from RowUpdatingEventArgs) The UpdateStatus of the Command. ■ TableMapping (inherited from RowUpdatingEventArgs) The DataTableMapping used during the Update. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Class Oracle Data Provider for .NET Classes 4-107 Example The example for the RowUpdated event also shows how to use the RowUpdating event. See RowUpdated event "Example" on page 4-105. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members OracleDataAdapter Event Delegates 4-108 Oracle Data Provider for .NET Developer’s Guide OracleDataAdapter Event Delegates OracleDataAdapter event delegates are listed in Table 4–41. OracleRowUpdatedEventHandler This event delegate handles the RowUpdated Event. OracleRowUpdatingEventHandler This event delegate handles the RowUpdating Event. Table 4–41 OracleDataAdapter Event Delegates Event Delegate Name Description EventHandler Inherited from Component FillErrorEventHandler Inherited from DbDataAdapter OracleRowUpdatedEventHandler Event Delegate for the RowUpdated Event OracleRowUpdatingEventHandler Event Delegate for the RowUpdating Event See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ OracleRowUpdatedEventHandler Delegate on page 4-250 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataAdapter Class ■ OracleDataAdapter Members ■ "OracleRowUpdatingEventArgs Class" on page 4-258 OracleDataReader Class Oracle Data Provider for .NET Classes 4-109 OracleDataReader Class An OracleDataReader object represents a forward-only, read-only, in-memory result set. Unlike the DataSet, the OracleDataReader stays connected and fetches one row at a time. The following section contain related information: ■ "Obtaining LONG and LONG RAW Data" on page 3-27. ■ "Obtaining Data From an OracleDataReader" on page 3-23. Class Inheritance Object MarshalByRefObject OracleDataReader Declaration // C# public sealed class OracleDataReader : MarshalByRefObject, IEnumerable, IDataReader, IDisposable, IDataRecord Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks An OracleDataReader instance is constructed by a call to the ExecuteReader method of the OracleCommand object. The only properties that can be accessed after the DataReader is closed or has been disposed, are IsClosed and RecordsAffected. Example The following OracleDataReader example retrieves the data from the EMP table: /* Database Setup CREATE TABLE empInfo ( empno NUMBER(4) PRIMARY KEY, empName VARCHAR2(20) NOT NULL, hiredate DATE, salary NUMBER(7,2), jobDescription Clob, byteCodes BLOB ); Insert into empInfo(EMPNO,EMPNAME,JOBDESCRIPTION) values (1,'KING','SOFTWARE ENGR'); Insert into empInfo(EMPNO,EMPNAME,JOBDESCRIPTION) values (2,'SCOTT','MANAGER'); commit; */ OracleDataReader Class 4-110 Oracle Data Provider for .NET Developer’s Guide // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleDataReaderSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); string cmdstr = "SELECT * FROM EMPINFO"; OracleConnection connection = new OracleConnection(constr); OracleCommand cmd = new OracleCommand(cmdstr, con); OracleDataReader reader = cmd.ExecuteReader(); // Declare the variables to retrieve the data in EmpInfo short empNo; string empName; DateTime hireDate; double salary; string jobDesc; byte[] byteCodes = new byte[10]; // Read the next row until end of row while (reader.Read()) { empNo = reader.GetInt16(0); Console.WriteLine("Employee number: " + empNo); empName = reader.GetString(1); Console.WriteLine("Employee name: " + empName); // The following columns can have NULL value, so it // is important to call IsDBNull before getting the column data if (!reader.IsDBNull(2)) { hireDate = reader.GetDateTime(2); Console.WriteLine("Hire date: " + hireDate); } if (!reader.IsDBNull(3)) { salary = reader.GetDouble(3); Console.WriteLine("Salary: " + salary); } if (!reader.IsDBNull(4)) { jobDesc = reader.GetString(4); Console.WriteLine("Job Description: " + jobDesc); } if (!reader.IsDBNull(5)) { long len = reader.GetBytes(5, 0, byteCodes, 0, 10); OracleDataReader Class Oracle Data Provider for .NET Classes 4-111 Console.Write("Byte codes: "); for (int i = 0; i < len; i++) Console.Write(byteCodes[i].ToString("x")); Console.WriteLine(); } Console.WriteLine(); } // Clean up reader.Dispose(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Members ■ OracleDataReader Static Methods ■ OracleDataReader Properties ■ OracleDataReader Public Methods ■ OracleDataReader SchemaTable OracleDataReader Members 4-112 Oracle Data Provider for .NET Developer’s Guide OracleDataReader Members OracleDataReader members are listed in the following tables: OracleDataReader Static Methods OracleDataReader static methods are listed in Table 4–42. OracleDataReader Properties OracleDataReader properties are listed in Table 4–43. OracleDataReader Public Methods OracleDataReader public methods are listed in Table 4–44. Table 4–42 OracleDataReader Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–43 OracleDataReader Properties Property Description Depth Gets a value indicating the depth of nesting for the current row FetchSize Specifies the size of OracleDataReader's internal cache FieldCount Gets the number of columns in the result set HasRows Indicates whether the OracleDataReader has one or more rows IsClosed Indicates whether the data reader is closed Item Gets the value of the column (Overloaded) InitialLOBFetchSize Specifies the amount that the OracleDataReader initially fetches for LOB columns InitialLONGFetchSize Specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns RecordsAffected Gets the number of rows changed, inserted, or deleted by execution of the SQL statement Table 4–44 OracleDataReader Public Methods Public Method Description Close Closes the OracleDataReader CreateObjRef Inherited from MarshalByRefObject Dispose Releases any resources or memory allocated by the object Equals Inherited from Object (Overloaded) GetBoolean Not Supported GetByte Returns the byte value of the specified column GetBytes Populates the provided byte array with up to the maximum number of bytes, from the specified offset (in bytes) of the column OracleDataReader Class Oracle Data Provider for .NET Classes 4-113 GetChar Not Supported GetChars Populates the provided character array with up to the maximum number of characters, from the specified offset (in characters) of the column GetData Not Supported GetDataTypeName Returns the ODP.NET type name of the specified column GetDateTime Returns the DateTime value of the specified column GetDecimal Returns the decimal value of the specified NUMBER column GetDouble Returns the double value of the specified NUMBER column or BINARY_DOUBLE column GetFieldType Returns the Type of the specified column GetFloat Returns the float value of the specified NUMBER column or BINARY_FLOAT column GetGuid Not Supported GetHashCode Inherited from Object GetInt16 Returns the Int16 value of the specified NUMBER column GetInt32 Returns the Int32 value of the specified NUMBER column GetInt64 Returns the Int64 value of the specified NUMBER column GetLifetimeService Inherited by MarshalByRefObject GetName Returns the name of the specified column GetOracleBFile Returns an OracleBFile object of the specified BFILE column GetOracleBinary Returns an OracleBinary structure of the specified column GetOracleBlob Returns an OracleBlob object of the specified BLOB column GetOracleBlobForUpdate Returns an updatable OracleBlob object of the specified BLOB column GetOracleClob Returns an OracleClob object of the specified CLOB column GetOracleClobForUpdate Returns an updatable OracleClob object of the specified CLOB column GetOracleDate Returns an OracleDate structure of the specified DATE column GetOracleDecimal Returns an OracleDecimal structure of the specified NUMBER column GetOracleIntervalDS Returns an OracleIntervalDS structure of the specified INTERVAL DAY TO SECOND column GetOracleIntervalYM Returns an OracleIntervalYM structure of the specified INTERVAL YEAR TO MONTH column GetOracleString Returns an OracleString structure of the specified column Table 4–44 (Cont.) OracleDataReader Public Methods Public Method Description OracleDataReader Members 4-114 Oracle Data Provider for .NET Developer’s Guide GetOracleTimeStamp Returns an OracleTimeStamp structure of the Oracle TimeStamp column GetOracleTimeStampLTZ Returns an OracleTimeStampLTZ structure of the specified Oracle TimeStamp WITH LOCAL TIME ZONE column GetOracleTimeStampTZ Returns an OracleTimeStampTZ structure of the specified Oracle TimeStamp WITH TIME ZONE column GetOracleXmlType Returns an OracleXmlType object of the specified XMLType column GetOracleValue Returns the specified column value as a ODP.NET type GetOracleValues Gets all the column values as ODP.NET types GetOrdinal Returns the 0-based ordinal (or index) of the specified column name GetSchemaTable Returns a DataTable that describes the column metadata of the OracleDataReader GetString Returns the string value of the specified column GetTimeSpan Returns the TimeSpan value of the specified INTERVAL DAY TO SECOND column GetType Inherited from Object class GetValue Returns the column value as a .NET type GetValues Gets all the column values as .NET types GetXmlReader Returns the contents of an XMLType column as an instance of an .NET XmlTextReader object IsDBNull Indicates whether the column value is null NextResult Advances the data reader to the next result set when reading the results Read Reads the next row in the result set ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class Table 4–44 (Cont.) OracleDataReader Public Methods Public Method Description OracleDataReader Class Oracle Data Provider for .NET Classes 4-115 OracleDataReader Static Methods OracleDataReader static methods are listed in Table 4–45. Table 4–45 OracleDataReader Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Properties 4-116 Oracle Data Provider for .NET Developer’s Guide OracleDataReader Properties OracleDataReader properties are listed in Table 4–46. Depth This property gets a value indicating the depth of nesting for the current row. Declaration // C# public int Depth {get;} Property Value The depth of nesting for the current row. Implements IDataReader Exceptions InvalidOperationException - The reader is closed. Remarks Default = 0 This property always returns zero because Oracle does not support nesting. Table 4–46 OracleDataReader Properties Property Description Depth Gets a value indicating the depth of nesting for the current row FetchSize Specifies the size of OracleDataReader's internal cache FieldCount Gets the number of columns in the result set HasRows Indicates whether the OracleDataReader has one or more rows IsClosed Indicates whether the data reader is closed Item Gets the value of the column (Overloaded) InitialLOBFetchSize Specifies the amount that the OracleDataReader initially fetches for LOB columns InitialLONGFetchSize Specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns RecordsAffected Gets the number of rows changed, inserted, or deleted by execution of the SQL statement See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-117 FetchSize This property specifies the size of OracleDataReader's internal cache. Declaration // C# public long FetchSize {get; set;} Property Value A long that specifies the amount of memory (in bytes) that the OracleDataReader uses for its internal cache. Exceptions ArgumentException - The FetchSize value specified is invalid. Remarks Default = The OracleCommand's FetchSize property value. The FetchSize property is inherited by the OracleDataReader that is created by a command execution returning a result set. The FetchSize property on the OracleDataReader object determines the amount of data fetched into its internal cache for each server round-trip. FieldCount This property gets the number of columns in the result set. Declaration // C# public int FieldCount {get;} Property Value The number of columns in the result set if one exists, otherwise 0. Implements IDataRecord See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ OracleCommand "ExecuteReader()" on page 4-31 ■ OracleCommand "RowSize" on page 4-19 OracleDataReader Properties 4-118 Oracle Data Provider for .NET Developer’s Guide Exceptions InvalidOperationException - The reader is closed. Remarks Default = 0 This property has a value of 0 for queries that do not return result sets. HasRows This property indicates whether the OracleDataReader has one or more rows. Declaration // C# public bool HasRows (get;); Return Value bool Remarks HasRows indicates whether the OracleDataReader has any rows. The value of HasRows does not change based on the row position. For example, even if the application has read all the rows from the result set and the next Read method invocation will return false, the HasRows property still returns true since the result set was not empty to begin with. Rows are fetched to determined the emptiness of the OracleDataReader when HasRows property is accessed for the first time after the creation of the OracleDataReader object. Example // C# using System; using Oracle.DataAccess.Client; class HasRowsSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = new OracleCommand( "select * from emp where empno = 9999", con); OracleDataReader reader = cmd.ExecuteReader(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-119 if (!reader.HasRows) Console.WriteLine("The result set is empty."); else Console.WriteLine("The result set is not empty."); con.Dispose(); } } IsClosed This property indicates whether the data reader is closed. Declaration // C# public bool IsClosed {get;} Property Value If the OracleDataReader is in a closed state, returns true; otherwise, returns false. Implements IDataReader Remarks Default = true IsClosed and RecordsAffected are the only two properties that are accessible after the OracleDataReader is closed. Item This property gets the value of the column in .NET datatype. Overload List: ■ Item [index] This property gets the .NET Value of the column specified by the column index. ■ Item [string] This property gets the .NET Value of the column specified by the column name. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ http://msdn.microsoft.com/library for detailed information about this Microsoft .NET Framework 1.1 feature See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Properties 4-120 Oracle Data Provider for .NET Developer’s Guide Item [index] This property gets the .NET Value of the column specified by the column index. Declaration // C# public object this[int index] {get;} Parameters ■ index The zero-based index of the column. Property Value The .NET value of the specified column. Implements IDataRecord Remarks Default = Not Applicable In C#, this property is the indexer for this class. Item [string] This property gets the .NET Value of the column specified by the column name. Declaration // C# public object this[string columnName] {get;} Parameters ■ columnName The name of the column. Property Value The .NET Value of the specified column. Implements IDataRecord See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-121 Remarks Default = Not Applicable A case-sensitive search is made to locate the specified column by its name. If this fails, then a case-insensitive search is made. In C#, this property is the indexer for this class. InitialLOBFetchSize This property specifies the amount that the OracleDataReader initially fetches for LOB columns. Declaration // C# public int InitialLOBFetchSize {get;} Property Value The size of the chunk to retrieve. Exceptions InvalidOperationException - The reader is closed. Remarks The maximum value supported for InitialLOBFetchSize is 32767. If this property is set to a higher value, the provider resets it to 32767. Default is the OracleCommand.InitialLOBFetchSize, from which this value is inherited. InitialLONGFetchSize This property specifies the amount that the OracleDataReader initially fetches for LONG and LONG RAW columns. Declaration // C# public long InitialLONGFetchSize {get;} See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "InitialLOBFetchSize" on page 4-17 for further information on OracleCommand.InitialLOBFetchSize ■ "Obtaining LOB Data" on page 3-27 OracleDataReader Properties 4-122 Oracle Data Provider for .NET Developer’s Guide Property Value The size of the chunk to retrieve. The default is 0. Exceptions InvalidOperationException - The reader is closed. Remarks The maximum value supported for InitialLONGFetchSize is 32767. If this property is set to a higher value, the provider resets it to 32767. Default is OracleCommand.InitialLONGFetchSize, from which this value is inherited. This property is read-only for the OracleDataReader. RecordsAffected This property gets the number of rows changed, inserted, or deleted by execution of the SQL statement. Declaration // C# public int RecordsAffected {get;} Property Value The number of rows affected by execution of the SQL statement. Implements IDataReader Remarks Default = 0 The value of -1 is returned for SELECT statements. IsClosed and RecordsAffected are the only two properties that are accessible after the OracleDataReader is closed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "InitialLONGFetchSize" on page 4-18 for further information on OracleCommand.InitialLONGFetchSize ■ "Obtaining LONG and LONG RAW Data" on page 3-27 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-123 OracleDataReader Public Methods OracleDataReader public methods are listed in Table 4–47. Table 4–47 OracleDataReader Public Methods Public Method Description Close Closes the OracleDataReader CreateObjRef Inherited from MarshalByRefObject Dispose Releases any resources or memory allocated by the object Equals Inherited from Object (Overloaded) GetBoolean Not Supported GetByte Returns the byte value of the specified column GetBytes Populates the provided byte array with up to the maximum number of bytes, from the specified offset (in bytes) of the column GetChar Not Supported GetChars Populates the provided character array with up to the maximum number of characters, from the specified offset (in characters) of the column GetData Not Supported GetDataTypeName Returns the ODP.NET type name of the specified column GetDateTime Returns the DateTime value of the specified column GetDecimal Returns the decimal value of the specified NUMBER column GetDouble Returns the double value of the specified NUMBER column or BINARY_DOUBLE column GetFieldType Returns the Type of the specified column GetFloat Returns the float value of the specified NUMBER column or BINARY_FLOAT column GetGuid Not Supported GetHashCode Inherited from Object GetInt16 Returns the Int16 value of the specified NUMBER column GetInt32 Returns the Int32 value of the specified NUMBER column GetInt64 Returns the Int64 value of the specified NUMBER column GetLifetimeService Inherited by MarshalByRefObject GetName Returns the name of the specified column GetOracleBFile Returns an OracleBFile object of the specified BFILE column GetOracleBinary Returns an OracleBinary structure of the specified column GetOracleBlob Returns an OracleBlob object of the specified BLOB column GetOracleBlobForUpdate Returns an updatable OracleBlob object of the specified BLOB column OracleDataReader Public Methods 4-124 Oracle Data Provider for .NET Developer’s Guide GetOracleClob Returns an OracleClob object of the specified CLOB column GetOracleClobForUpdate Returns an updatable OracleClob object of the specified CLOB column GetOracleDate Returns an OracleDate structure of the specified DATE column GetOracleDecimal Returns an OracleDecimal structure of the specified NUMBER column GetOracleIntervalDS Returns an OracleIntervalDS structure of the specified INTERVAL DAY TO SECOND column GetOracleIntervalYM Returns an OracleIntervalYM structure of the specified INTERVAL YEAR TO MONTH column GetOracleString Returns an OracleString structure of the specified column GetOracleTimeStamp Returns an OracleTimeStamp structure of the Oracle TimeStamp column GetOracleTimeStampLTZ Returns an OracleTimeStampLTZ structure of the specified Oracle TimeStamp WITH LOCAL TIME ZONE column GetOracleTimeStampTZ Returns an OracleTimeStampTZ structure of the specified Oracle TimeStamp WITH TIME ZONE column GetOracleXmlType Returns an OracleXmlType object of the specified XMLType column GetOracleValue Returns the specified column value as a ODP.NET type GetOracleValues Gets all the column values as ODP.NET types GetOrdinal Returns the 0-based ordinal (or index) of the specified column name GetSchemaTable Returns a DataTable that describes the column metadata of the OracleDataReader GetString Returns the string value of the specified column GetTimeSpan Returns the TimeSpan value of the specified INTERVAL DAY TO SECOND column GetType Inherited from Object class GetValue Returns the column value as a .NET type GetValues Gets all the column values as .NET types GetXmlReader Returns the value of an XMLType column as an instance of an .NET XmlTextReader IsDBNull Indicates whether the column value is null NextResult Advances the data reader to the next result set when reading the results Read Reads the next row in the result set ToString Inherited from Object Table 4–47 (Cont.) OracleDataReader Public Methods Public Method Description OracleDataReader Class Oracle Data Provider for .NET Classes 4-125 Close This method closes the OracleDataReader. Declaration // C# public void Close(); Implements IDataReader Remarks The Close method frees all resources associated with the OracleDataReader. Example The code example for the OracleDataReader class includes the Close method. See OracleDataReader Overview "Example" on page 4-109. Dispose This method releases any resources or memory allocated by the object. Declaration // C# public void Dispose(); Implements IDisposable Remarks The Dispose method also closes the OracleDataReader. GetByte This method returns the byte value of the specified column. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-126 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public byte GetByte(int index); Parameters ■ index The zero-based column index. Return Value The value of the column as a byte. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetBytes This method populates the provided byte array with up to the maximum number of bytes, from the specified offset (in bytes) of the column. Declaration // C# public long GetBytes(int index, long fieldOffset, byte[] buffer, int bufferOffset, int length); Parameters ■ index The zero-based column index. ■ fieldOffset The offset within the column from which reading begins (in bytes). ■ buffer The byte array that the data is read into. ■ bufferOffset See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-127 The offset within the buffer to begin reading data into (in bytes). ■ length The maximum number of bytes to read (in bytes). Return Value The number of bytes read. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks This method returns the number of bytes read into the buffer. This may be less than the actual length of the field if the method has been called previously for the same column. If a null reference is passed for buffer, the length of the field in bytes is returned. IsDBNull should be called to check for NULL values before calling this method. GetChars This method populates the provided character array with up to the maximum number of characters, from the specified offset (in characters) of the column. Declaration // C# public long GetChars(int index, long fieldOffset, char[] buffer, int bufferOffset, int length); Parameters ■ index The zero based column index. ■ fieldOffset The index within the column from which to begin reading (in characters). ■ buffer The character array that the data is read into. ■ bufferOffset See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-128 Oracle Data Provider for .NET Developer’s Guide The index within the buffer to begin reading data into (in characters). ■ length The maximum number of characters to read (in characters). Return Value The number of characters read. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks This method returns the number of characters read into the buffer. This may be less than the actual length of the field, if the method has been called previously for the same column. If a null reference is passed for buffer, the length of the field in characters is returned. IsDBNull should be called to check for NULL values before calling this method. GetDataTypeName This method returns the ODP.NET type name of the specified column. Declaration // C# public string GetDataTypeName(int index); Parameters ■ index The zero-based column index. Return Value The name of the ODP.NET type of the column. Implements IDataRecord See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-129 Exceptions InvalidOperationException - The reader is closed. IndexOutOfRangeException - The column index is invalid. GetDateTime This method returns the DateTime value of the specified column. Declaration // C# public DateTime GetDateTime(int index); Parameters ■ index The zero-based column index. Return Value The DateTime value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetDecimal This method returns the decimal value of the specified NUMBER column. Declaration // C# public decimal GetDecimal(int index); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-130 Oracle Data Provider for .NET Developer’s Guide Parameters ■ index The zero-based column index. Return Value The decimal value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetDouble This method returns the double value of the specified NUMBER column or BINARY_ DOUBLE column. Declaration // C# public double GetDouble(int index); Parameters ■ index The zero-based column index. Return Value The double value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-131 InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. Starting with Oracle Database 10g, GetDouble now supports retrieval of data from BINARY_DOUBLE columns. GetFieldType This method returns the Type of the specified column. Declaration // C# public Type GetFieldType(int index); Parameters ■ index The zero-based column index. Return Value The Type of the default .NET type of the column. Implements IDataRecord Exceptions InvalidOperationException - The reader is closed. IndexOutOfRangeException - The column index is invalid. GetFloat This method returns the float value of the specified NUMBER column or BINARY_ FLOAT column. Declaration // C# public float GetFloat(int index); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-132 Oracle Data Provider for .NET Developer’s Guide Parameters ■ index The zero-based column index. Return Value The float value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. Starting with Oracle Database 10g, GetFloat now supports retrieval of data from BINARY_FLOAT columns. GetInt16 This method returns the Int16 value of the specified NUMBER column. Declaration // C# public short GetInt16(int index); Parameters ■ index The zero-based column index. Return Value The Int16 value of the column. Implements IDataRecord See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members Note: short is equivalent to Int16. OracleDataReader Class Oracle Data Provider for .NET Classes 4-133 Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetInt32 This method returns the Int32 value of the specified NUMBER column. Declaration // C# public int GetInt32(int index); Parameters ■ index The zero-based column index. Return Value The Int32 value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members Note: int is equivalent to Int32. OracleDataReader Public Methods 4-134 Oracle Data Provider for .NET Developer’s Guide GetInt64 This method returns the Int64 value of the specified NUMBER column. Declaration // C# public long GetInt64(int index); Parameters ■ index The zero-based column index. Return Value The Int64 value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetName This method returns the name of the specified column. Declaration // C# public string GetName(int index); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members Note: long is equivalent to Int64. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-135 Parameters ■ index The zero-based column index. Return Value The name of the column. Implements IDataRecord Exceptions InvalidOperationException - The reader is closed. IndexOutOfRangeException - The column index is invalid. GetOracleBFile This method returns an OracleBFile object of the specified BFILE column. Declaration // C# public OracleBFile GetOracleBFile(int index); Parameters ■ index The zero-based column index. Return Value The OracleBFile value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-136 Oracle Data Provider for .NET Developer’s Guide GetOracleBinary This method returns an OracleBinary structure of the specified column. Declaration // C# public OracleBinary GetOracleBinary(int index); Parameters ■ index The zero-based column index. Return Value The OracleBinary value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleBinary is used on the following Oracle types: ■ BFILE ■ BLOB ■ LONG RAW ■ RAW GetOracleBlob This method returns an OracleBlob object of the specified BLOB column. Declaration // C# public OracleBlob GetOracleBlob(int index); Parameters ■ index The zero-based column index. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-137 Return Value The OracleBlob value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleBlobForUpdate GetOracleBlobForUpdate returns an updatable OracleBlob object of the specified BLOB column. Overload List: ■ GetOracleBlobForUpdate(int) This method returns an updatable OracleBlob object of the specified BLOB column. ■ GetOracleBlobForUpdate(int, int) This method returns an updatable OracleBlob object of the specified BLOB column using a WAIT clause. GetOracleBlobForUpdate(int) This method returns an updatable OracleBlob object of the specified BLOB column. Declaration // C# public OracleBlob GetOracleBlobForUpdate(int index); Parameters ■ index The zero-based column index. Return Value An updatable OracleBlob object. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-138 Oracle Data Provider for .NET Developer’s Guide IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks When the OracleCommand's ExecuteReader() method is invoked, all the data fetched by the OracleDataReader is from a particular snapshot. Therefore, calling an accessor method on the same column always returns the same value. However, the GetOracleBlobForUpdate() method incurs a server round-trip to obtain a reference to the current BLOB data while also locking the row using the FOR UPDATE clause. This means that the OracleBlob obtained from GetOracleBlob() can have a different value than the OracleBlob obtained from GetOracleBlobForUpdate() since it is not obtained from the original snapshot. The returned OracleBlob object can be used to safely update the BLOB because the BLOB column has been locked after a call to this method. Invoking this method internally executes a SELECT..FOR UPDATE statement without a WAIT clause. Therefore, the statement can wait indefinitely until a lock is acquired for that row. IsDBNull should be called to check for NULL values before calling this method. Example The following example gets the OracleBlob object for update from the reader, updates the OracleBlob object, and then commits the transaction. // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class GetOracleBlobForUpdateSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Get the ByteCodes for empno = 1 string cmdstr = "SELECT BYTECODES, EMPNO FROM EMPINFO where EMPNO = 1"; OracleCommand cmd = new OracleCommand(cmdstr, con); // Since we are going to update the OracleBlob object, we will //have to create a transaction OracleTransaction txn = con.BeginTransaction(); // Get the reader OracleDataReader reader = cmd.ExecuteReader(); // Declare the variables to retrieve the data in EmpInfo OracleBlob byteCodesBlob; // Read the first row reader.Read(); if (!reader.IsDBNull(0)) OracleDataReader Class Oracle Data Provider for .NET Classes 4-139 { byteCodesBlob = reader.GetOracleBlobForUpdate(0); // Close the reader reader.Close(); // Update the ByteCodes object byte[] addedBytes = new byte[2] {0, 0}; byteCodesBlob.Append(addedBytes, 0, addedBytes.Length); // Now commit the transaction txn.Commit(); Console.WriteLine("Blob Column successfully updated"); } else reader.Dispose(); // Close the connection con.Dispose(); } } GetOracleBlobForUpdate(int, int) This method returns an updatable OracleBlob object of the specified BLOB column using a WAIT clause. Declaration // C# public OracleBlob GetOracleBlobForUpdate(int index, int wait); Parameters ■ index The zero-based column index. ■ wait The number of seconds the method waits to acquire a lock. Return Value An updatable OracleBlob object. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 OracleDataReader Public Methods 4-140 Oracle Data Provider for .NET Developer’s Guide Remarks When the OracleCommand's ExecuteReader() method is invoked, all the data fetched by the OracleDataReader is from a particular snapshot. Therefore, calling an accessor method on the same column always returns the same value. However, the GetOracleBlobForUpdate() method incurs a server round-trip to obtain a reference to the current BLOB data while also locking the row using the FOR UPDATE clause. This means that the OracleBlob obtained from GetOracleBlob() can have a different value than the OracleBlob obtained from GetOracleBlobForUpdate() since it is not obtained from the original snapshot. IsDBNull should be called to check for NULL values before calling this method. The returned OracleBlob object can be used to safely update the BLOB because the BLOB column has been locked after a call to this method. Invoking this method internally executes a SELECT..FOR UPDATE statement which locks the row. Different WAIT clauses are appended to the statement, depending on the wait value. If the wait value is: ■ 0 "NOWAIT" is appended at the end of a SELECT..FOR UPDATE statement. The statement executes immediately whether the lock is acquired or not. If the lock is not acquired, an exception is thrown. ■ n "WAIT n" is appended at the end of a SELECT..FOR UPDATE statement. The statement executes as soon as the lock is acquired. However, if the lock cannot be acquired by n seconds, this method call throws an exception. The WAIT n" feature is only available for Oracle9i or later. For any version lower than Oracle9i, n is implicitly treated as -1 and nothing is appended at the end of a SELECT..FOR UPDATE statement. ■ -1 Nothing is appended at the end of the SELECT..FOR UPDATE. The statement execution waits indefinitely until a lock can be acquired. Example The GetOracleBlobForUpdate methods are comparable. See "Example" on page 4-138 for a code example demonstrating usage. GetOracleClob This method returns an OracleClob object of the specified CLOB column. Declaration // C# public OracleClob GetOracleClob(int index); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 OracleDataReader Class Oracle Data Provider for .NET Classes 4-141 Parameters ■ index The zero-based column index. Return Value The OracleClob value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleClobForUpdate GetOracleClobForUpdate returns an updatable OracleClob object of the specified CLOB column. Overload List: ■ GetOracleClobForUpdate(int) This method returns an updatable OracleClob object of the specified CLOB column. ■ GetOracleClobForUpdate(int, int) This method returns an updatable OracleClob object of the specified CLOB column using a WAIT clause. GetOracleClobForUpdate(int) This method returns an updatable OracleClob object of the specified CLOB column. Declaration // C# public OracleClob GetOracleClobForUpdate(int index); Parameters ■ index The zero-based column index. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 OracleDataReader Public Methods 4-142 Oracle Data Provider for .NET Developer’s Guide Return Value An updatable OracleClob. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks When the OracleCommand's ExecuteReader() method is invoked, all the data fetched by the OracleDataReader is from a particular snapshot. Therefore, calling an accessor method on the same column always returns the same value. However, the GetOracleClobForUpdate() method incurs a server round-trip to obtain a reference to the current CLOB data while also locking the row using the FOR UPDATE clause. This means that the OracleClob obtained from GetOracleClob() can have a different value than the OracleClob obtained from GetOracleClobForUpdate() since it is not obtained from the original snapshot. The returned OracleClob object can be used to safely update the CLOB because the CLOB column is locked after a call to this method. Invoking this method internally executes a SELECT..FOR UPDATE statement without a WAIT clause. Therefore, the statement can wait indefinitely until a lock is acquired for that row. IsDBNull should be called to check for NULL values before calling this method. Example The following example gets the OracleClob object for update from the reader, updates the OracleClob object, and then commits the transaction. // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class GetOracleClobForUpdateSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Get the job description for empno = 1 string cmdStr = "SELECT JOBDESCRIPTION, EMPNO FROM EMPINFO where EMPNO = 1"; OracleCommand cmd = new OracleCommand(cmdStr, con); // Since we are going to update the OracleClob object, we will // have to create a transaction OracleTransaction txn = con.BeginTransaction(); // Get the reader OracleDataReader Class Oracle Data Provider for .NET Classes 4-143 OracleDataReader reader = cmd.ExecuteReader(); // Declare the variables to retrieve the data in EmpInfo OracleClob jobDescClob; // Read the first row reader.Read(); if (!reader.IsDBNull(0)) { jobDescClob = reader.GetOracleClobForUpdate(0); // Close the reader reader.Close(); // Update the job description Clob object char[] jobDesc = "-SALES".ToCharArray(); jobDescClob.Append(jobDesc, 0, jobDesc.Length); // Now commit the transaction txn.Commit(); Console.WriteLine("Clob Column successfully updated"); } else reader.Close(); // Close the connection con.Close(); } } GetOracleClobForUpdate(int, int) This method returns an updatable OracleClob object of the specified CLOB column using a WAIT clause. Declaration // C# public OracleClob GetOracleClobForUpdate(int index, int wait); Parameters ■ index The zero-based column index. ■ wait The number of seconds the method waits to acquire a lock. Return Value An updatable OracleClob. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 OracleDataReader Public Methods 4-144 Oracle Data Provider for .NET Developer’s Guide Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks When the OracleCommand's ExecuteReader() method is invoked, all the data fetched by the OracleDataReader is from a particular snapshot. Therefore, calling an accessor method on the same column always returns the same value. However, the GetOracleClobForUpdate() method incurs a server round-trip to obtain a reference to the current CLOB data while also locking the row using the FOR UPDATE clause. This means that the OracleClob obtained from GetOracleClob() can have a different value than the OracleClob obtained from GetOracleClobForUpdate() since it is not obtained from the original snapshot. Invoking this method internally executes a SELECT..FOR UPDATE statement which locks the row. The returned OracleClob object can be used to safely update the CLOB because the CLOB column is locked after a call to this method. Different WAIT clauses are appended to the statement, depending on the wait value. If the wait value is: ■ 0 "NOWAIT" is appended at the end of a SELECT..FOR UPDATE statement. The statement executes immediately whether the lock is acquired or not. If the lock is not acquired, an exception is thrown. ■ n "WAIT n" is appended at the end of a SELECT..FOR UPDATE statement. The statement executes as soon as the lock is acquired. However, if the lock cannot be acquired by n seconds, this method call throws an exception. The WAIT n" feature is only available for Oracle9i or later. For any version lower than Oracle9i, n is implicitly treated as -1 and nothing is appended at the end of a SELECT..FOR UPDATE statement. ■ -1 Nothing is appended at the end of the SELECT..FOR UPDATE. The statement execution waits indefinitely until a lock can be acquired. IsDBNull should be called to check for NULL values before calling this method. Example The GetOracleClobForUpdate methods are comparable. See "Example" on page 4-142 for a code example demonstrating usage. OracleDataReader Class Oracle Data Provider for .NET Classes 4-145 GetOracleDate This method returns an OracleDate structure of the specified DATE column. Declaration // C# public OracleDate GetOracleDate(int index); Parameters ■ index The zero-based column index. Return Value The OracleDate value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleDecimal This method returns an OracleDecimal structure of the specified NUMBER column. Declaration // C# public OracleDecimal GetOracleDecimal(int index); Parameters ■ index The zero-based column index. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 OracleDataReader Public Methods 4-146 Oracle Data Provider for .NET Developer’s Guide Return Value The OracleDecimal value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleIntervalDS This method returns an OracleIntervalDS structure of the specified INTERVAL DAY TO SECOND column. Declaration // C# public OracleIntervalDS GetOracleIntervalDS(int index); Parameters ■ index The zero-based column index. Return Value The OracleIntervalDS value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-147 GetOracleIntervalYM This method returns an OracleIntervalYM structure of the specified INTERVAL YEAR TO MONTH column. Declaration // C# public OracleIntervalYM GetOracleIntervalYM(int index); Parameters ■ index The zero-based column index. Return Value The OracleIntervalYM value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleString This method returns an OracleString structure of the specified column. The string is stored as a Unicode string. Declaration // C# public OracleString GetOracleString(int index); Parameters ■ index The zero-based column index. Return Value The OracleString value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-148 Oracle Data Provider for .NET Developer’s Guide IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetOracleString is used on the following Oracle column types: ■ CHAR ■ CLOB ■ LONG ■ NCLOB ■ NCHAR ■ NVARCHAR2 ■ ROWID ■ UROWID ■ VARCHAR2 ■ XMLType GetOracleTimeStamp This method returns an OracleTimeStamp structure of the Oracle TimeStamp column. Declaration // C# public OracleTimeStamp GetOracleTimeStamp(int index); Parameters ■ index The zero-based column index. Return Value The OracleTimeStamp value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-149 Remarks GetOracleTimeStamp is used with the Oracle Type TimeStamp. IsDBNull should be called to check for NULL values before calling this method. GetOracleTimeStampLTZ This method returns an OracleTimeStampLTZ structure of the specified Oracle TimeStamp WITH LOCAL TIME ZONE column. Declaration // C# public OracleTimeStampLTZ GetOracleTimeStampLTZ(int index); Parameters ■ index The zero-based column index. Return Value The OracleTimeStampLTZ value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks GetOracleTimeStampLTZ is used with the Oracle Type TimeStamp with Local Time Zone columns. IsDBNull should be called to check for NULL values before calling this method. GetOracleTimeStampTZ This method returns an OracleTimeStampTZ structure of the specified Oracle TimeStamp WITH TIME ZONE column. Declaration // C# See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-150 Oracle Data Provider for .NET Developer’s Guide public OracleTimeStampTZ GetOracleTimeStampTZ(int index); Parameters ■ index The zero-based column index. Return Value The OracleTimeStampTZ value of the column. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks Used with the Oracle Type TimeStamp with Local Time Zone columns IsDBNull should be called to check for NULL values before calling this method. GetOracleXmlType This method returns an OracleXmlType object of the specified XMLType column. Declaration // C# public OracleXmlType GetOracleXmlType(int index); Parameters ■ index The zero-based column index. Return Value The OracleXmlType value of the column. Exceptions InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. Requirements This property can only be used with Oracle9i Release 2 (9.2) or higher. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-151 GetOracleValue This method returns the specified column value as an ODP.NET type. Declaration // C# public object GetOracleValue(int index); Parameters ■ index The zero-based column index. Return Value The value of the column as an ODP.NET type. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. GetOracleValues This method gets all the column values as ODP.NET types. Declaration // C# public int GetOracleValues(object[] values); Parameters ■ values An array of objects to hold the ODP.NET types as the column values. Return Value The number of ODP.NET types in the values array. Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-152 Oracle Data Provider for .NET Developer’s Guide Remarks This method provides a way to retrieve all column values rather than retrieving each column value individually. The number of column values retrieved is the minimum of the length of the values array and the number of columns in the result set. GetOrdinal This method returns the 0-based ordinal (or index) of the specified column name. Declaration // C# public int GetOrdinal(string name); Parameters ■ name The specified column name. Return Value The index of the column. Implements IDataRecord Exceptions InvalidOperationException - The reader is closed. IndexOutOfRangeException - The column index is invalid. Remarks A case-sensitive search is made to locate the specified column by its name. If this fails, then a case-insensitive search is made. GetSchemaTable This method returns a DataTable that describes the column metadata of the OracleDataReader. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members ■ "LOB Support" on page 3-32 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-153 Declaration // C# public DataTable GetSchemaTable(); Return Value A DataTable that contains the metadata of the result set. Implements IDataReader Exceptions InvalidOperationException - The connection is closed or the reader is closed. Remarks OracleDataReader.GetSchemaTable()returns the SchemaTable. OracleDataReader SchemaTable The OracleDataReader SchemaTable is a DataTable that describes the column metadata of the OracleDataReader. The columns of the SchemaTable are in the order shown. Table 4–48 OracleDataReader SchemaTable Name Name Type Description ColumnNameTB System.String The name of the column. ColumnOrdinal System.Int32 The 0-based ordinal of the column. ColumnSize System.Int64 The maximum possible length of a value in the column. ColumnSize value is determined as follows: ■ CHAR and VARCHAR2 types: in bytes - if IsByteSemantic boolean value is true in characters - if IsByteSemantic boolean value is false ■ All other types: in bytes See "IsByteSemantic" on page 4-155 for more information. NumericPrecision System.Int16 The maximum precision of the column, if the column is a numeric datatype. This column has valid values for Oracle NUMBER, Oracle INTERVAL YEAR TO MONTH, and Oracle INTERVAL DAY TO SECOND columns. For all other columns, the value is null. NumericScale System.Int16 The scale of the column. This column has valid values for Oracle NUMBER, Oracle INTERVAL DAY TO SECOND, and the Oracle TIMESTAMP columns. For all other columns, the value is null. OracleDataReader Public Methods 4-154 Oracle Data Provider for .NET Developer’s Guide IsUnique System.Boolean Indicates whether the column is unique. true if no two rows in the base table can have the same value in this column, where the base table is the table returned in BaseTableName. IsUnique is guaranteed to be true if one of the following applies: ■ the column constitutes a key by itself ■ there is a unique constraint or a unique index that applies only to this column and a NOT NULL constraint has been defined on the column ■ the column is an explicitly selected ROWID IsUnique is false if the column can contain duplicate values in the base table. The default is false. The value of this property is the same for each occurrence of the base table column in the select list. IsKey System.Boolean Indicates whether the column is a key column. true if the column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with IsKey set to true must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns can be generated from one of the following in descending order of priority: ■ A base table primary key. ■ Any of the unique constraints or unique indexes with the following condition: A NOT NULL constraint must be defined on the column or on all of the columns, in the case of a composite unique constraint or composite unique index. ■ Any of the composite unique constraints or composite unique indexes with the following condition: A NULL constraint must be defined on at least one, but not all, of the columns. An explicitly selected ROWID. False if the column is not required to uniquely identify the row. The value of this property is the same for each occurrence of the base table column in the select list. IsRowID System.Boolean true if the column is a ROWID, otherwise false. BaseColumnName System.String The name of the column in the database if an alias is used for the column. BaseSchemaName System.String The name of the schema in the database that contains the column. BaseTableName System.String The name of the table or view in the database that contains the column. DataType System.RuntimeType Maps to the common language runtime type. ProviderType Oracle.DataAccess. Client.OracleDbType The database column type (OracleDbType) of the column. AllowDBNull System.Boolean true if null values are allowed, otherwise false. Table 4–48 (Cont.) OracleDataReader SchemaTable Name Name Type Description OracleDataReader Class Oracle Data Provider for .NET Classes 4-155 Example This example creates and uses the SchemaTable from the reader. // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class GetSchemaTableSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); string cmdstr = "SELECT EMPNO,EMPNAME FROM EMPINFO where EMPNO = 1"; OracleCommand cmd = new OracleCommand(cmdstr, con); //get the reader OracleDataReader reader = cmd.ExecuteReader(); //get the schema table DataTable schemaTable = reader.GetSchemaTable(); //retrieve the first column info. DataRow row = schemaTable.Rows[0]; //print out the column info Console.WriteLine("Column name: " + row["COLUMNNAME"]); Console.WriteLine("Precision: " + row["NUMERICPRECISION"]); Console.WriteLine("Scale: " + row["NUMERICSCALE"]); reader.Close(); // Close the connection con.Close(); } } IsAliased System.Boolean true if the column is an alias; otherwise false. IsByteSemantic System.Boolean IsByteSemantic is: ■ true if the ColumnSize value uses bytes semantics ■ false if ColumnSize uses character semantics This value is always true when connected to a database version earlier than Oracle9i. IsExpression System.Boolean true if the column is an expression; otherwise false. IsHidden System.Boolean true if the column is hidden; otherwise false. IsReadOnly System.Boolean true if the column is read-only; otherwise false. IsLong System.Boolean true if the column is a LONG, LONG RAW, BLOB, CLOB, or BFILE; otherwise false. Table 4–48 (Cont.) OracleDataReader SchemaTable Name Name Type Description OracleDataReader Public Methods 4-156 Oracle Data Provider for .NET Developer’s Guide GetString This method returns the string value of the specified column. Declaration // C# public string GetString(int index); Parameters ■ index The zero-based column index. Return Value The string value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetTimeSpan This method returns the TimeSpan value of the specified INTERVAL DAY TO SECOND column. Declaration // C# public TimeSpan GetTimeSpan(int index); Parameters ■ index See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-157 The zero-based column index. Return Value The TimeSpan value of the column. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. GetValue This method returns the column value as a .NET type. Declaration // C# public object GetValue(int index); Parameters ■ index The zero-based column index. Return Value The value of the column as a .NET type. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. Remarks When this method is invoked for a NUMBER column, the .NET type returned depends on the precision and scale of the column. For example, if a column is defined as See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-158 Oracle Data Provider for .NET Developer’s Guide NUMBER(4,0) then values in this column are retrieved as a System.Int16.If the precision and scale is such that no .NET type can represent all the possible values that could exist in that column, the value is returned as a System.Decimal, if possible. If the value cannot be represented by a System.Decimal, an exception is raised. For example, if a column is defined as NUMBER (20,10) then a value in this column is retrieved as a System.Decimal. GetValues This method gets all the column values as .NET types. Declaration // C# public int GetValues(object[ ] values); Parameters ■ values An array of objects to hold the .NET types as the column values. Return Value The number of objects in the values array. Implements IDataRecord Exceptions InvalidOperationException - The connection is closed, the reader is closed, Read() has not been called, or all rows have been read. Remarks This method provides a way to retrieve all column values rather than retrieving each column value individually. The number of column values retrieved is the minimum of the length of the values array and the number of columns in the result set. GetXmlReader This method returns the contents of an XMLType column as an instance of an .NET XmlTextReader object. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-159 Declaration // C# public XmlReader GetXmlReader(int index); Parameters ■ index The zero-based column index. Return Value A .NET XmlTextReader. Exceptions InvalidCastException - The accessor method is invalid for this column type or the column value is NULL. Remarks IsDBNull should be called to check for NULL values before calling this method. IsDBNull This method indicates whether the column value is NULL. Declaration // C# public bool IsDBNull(int index); Parameters ■ index The zero-based column index. Return Value Returns true if the column is a NULL value; otherwise, returns false. Implements IDataRecord Exceptions InvalidOperationException - The reader is closed, Read() has not been called, or all rows have been read. IndexOutOfRangeException - The column index is invalid. Remarks This method should be called to check for NULL values before calling the other accessor methods. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Public Methods 4-160 Oracle Data Provider for .NET Developer’s Guide Example The code example for the OracleDataReader class includes the IsDBNull method. See "Example" on page 4-109. NextResult This method advances the data reader to the next result set. Declaration // C# public bool NextResult(); Return Value Returns true if another result set exists; otherwise, returns false. Implements IDataReader Exceptions InvalidOperationException - The connection is closed or the reader is closed. Remarks NextResult is used when reading results from stored procedure execution that return more than one result set. Read This method reads the next row in the result set. Declaration // C# public bool Read(); Return Value Returns true if another row exists; otherwise, returns false. Implements IDataReader Exceptions InvalidOperationException - The connection is closed or the reader is closed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleDataReader Class Oracle Data Provider for .NET Classes 4-161 Remarks The initial position of the data reader is before the first row. Therefore, the Read method must be called to fetch the first row. The row that was just read is considered the current row. If the OracleDataReader has no more rows to read, it returns false. Example The code example for the OracleDataReader class includes the Read method. See "Example" on page 4-109. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleDataReader Class ■ OracleDataReader Members OracleError Class 4-162 Oracle Data Provider for .NET Developer’s Guide OracleError Class The OracleError class represents an error reported by Oracle. Class Inheritance Object OracleError Declaration // C# public sealed class OracleError Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks The OracleError class represents a warning or an error reported by Oracle. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleErrorsSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand object using the connection object OracleCommand cmd = con.CreateCommand(); try { cmd.CommandText = "insert into notable values (99, 'MyText')"; cmd.ExecuteNonQuery(); } catch (OracleException ex) { Console.WriteLine("Record is not inserted into the database table."); foreach (OracleError error in ex.Errors) { Console.WriteLine("Error Message: " + error.Message); Console.WriteLine("Error Source: " + error.Source); } } } } OracleError Class Oracle Data Provider for .NET Classes 4-163 Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Members ■ OracleError Static Methods ■ OracleError Properties ■ OracleError Methods OracleError Members 4-164 Oracle Data Provider for .NET Developer’s Guide OracleError Members OracleError members are listed in the following tables: OracleError Static Methods OracleError static methods are listed in Table 4–49. OracleError Properties OracleError properties are listed in Table 4–50. OracleError Methods OracleError methods are listed in Table 4–51. Table 4–49 OracleError Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–50 OracleError Properties Properties Description ArrayBindIndex Specifies the row number of errors that occurred during the Array Bind execution DataSource Specifies the Oracle service name (TNS name) that identifies the Oracle database Message Specifies the message describing the error Number Specifies the Oracle error number Procedure Specifies the stored procedure that causes the error Source Specifies the name of the data provider that generates the error Table 4–51 OracleError Methods Methods Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Returns a string representation of the OracleError See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class OracleError Class Oracle Data Provider for .NET Classes 4-165 OracleError Static Methods OracleError static methods are listed in Table 4–52. Table 4–52 OracleError Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members OracleError Properties 4-166 Oracle Data Provider for .NET Developer’s Guide OracleError Properties OracleError properties are listed in Table 4–53. ArrayBindIndex This property specifies the row number of errors that occurred during the Array Bind execution. Declaration // C# public int ArrayBindIndex {get;} Property Value An int value that specifies the row number for errors that occurred during the Array Bind execution. Remarks Default = 0. This property is used for Array Bind operations only. ArrayBindIndex represents the zero-based row number at which the error occurred during an Array Bind operation. For example, if an array bind execution causes two errors on the 2nd and 4th operations, two OracleError objects appear in the OracleErrorCollection with the ArrayBindIndex property values 2 and 4 respectively. Table 4–53 OracleError Properties Properties Description ArrayBindInde x Specifies the row number of errors that occurred during the Array Bind execution DataSource Specifies the Oracle service name (TNS name) that identifies the Oracle database Message Specifies the message describing the error Number Specifies the Oracle error number Procedure Specifies the stored procedure that causes the error Source Specifies the name of the data provider that generates the error See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members OracleError Class Oracle Data Provider for .NET Classes 4-167 DataSource This property specifies the Oracle service name (TNS name) that identifies the Oracle database. Declaration // C# public string DataSource {get;} Property Value A string. Message This property specifies the message describing the error. Declaration // C# public string Message {get;} Property Value A string. Number This property specifies the Oracle error number. Declaration // C# public int Number {get;} Property Value An int. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members ■ "Array Binding" on page 3-18 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members OracleError Properties 4-168 Oracle Data Provider for .NET Developer’s Guide Procedure This property specifies the stored procedure that causes the error. Declaration // C# public string Procedure {get;} Property Value The stored procedure name. Remarks Represents the stored procedure which creates this OracleError object. Source This property specifies the name of the data provider that generates the error. Declaration // C# public string Source {get;} Property Value A string. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members OracleError Class Oracle Data Provider for .NET Classes 4-169 OracleError Methods OracleError methods are listed in Table 4–54. ToString Overrides Object This method returns a string representation of the OracleError. Declaration // C# public override string ToString(); Return Value Returns a string with the format Ora- error number: Class.Method name error message stack trace information. Example ORA-24333: zero iteration count Table 4–54 OracleError Methods Methods Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Returns a string representation of the OracleError See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleError Class ■ OracleError Members OracleErrorCollection Class 4-170 Oracle Data Provider for .NET Developer’s Guide OracleErrorCollection Class An OracleErrorCollection class represents a collection of all errors that are thrown by the Oracle Data Provider for .NET. Class Inheritance Object ArrayList OracleErrorCollection Declaration // C# public sealed class OracleErrorCollection : ArrayList Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks A simple ArrayList that holds a list of OracleErrors. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleErrorCollectionSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand object using the connection object OracleCommand cmd = con.CreateCommand(); try { cmd.CommandText = "insert into notable values (99, 'MyText')"; cmd.ExecuteNonQuery(); } catch (OracleException ex) { Console.WriteLine("Record is not inserted into the database table."); foreach (OracleError error in ex.Errors) { Console.WriteLine("Error Message: " + error.Message); Console.WriteLine("Error Source: " + error.Source); } } OracleErrorCollection Class Oracle Data Provider for .NET Classes 4-171 } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleErrorCollection Members ■ OracleErrorCollection Static Methods ■ OracleErrorCollection Properties ■ OracleErrorCollection Public Methods OracleErrorCollection Members 4-172 Oracle Data Provider for .NET Developer’s Guide OracleErrorCollection Members OracleErrorCollection members are listed in the following tables: OracleErrorCollection Static Methods OracleErrorCollection static methods are listed in Table 4–55. OracleErrorCollection Properties OracleErrorCollection properties are listed in Table 4–56. OracleErrorCollection Public Methods OracleErrorCollection public methods are listed in Table 4–57. Table 4–55 OracleErrorCollection Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–56 OracleErrorCollection Properties Name Description Capacity Inherited from ArrayList Count Inherited from ArrayList IsReadOnly Inherited from ArrayList IsSynchronized Inherited from ArrayList Item Inherited from ArrayList Table 4–57 OracleErrorCollection Public Methods Public Method Description CopyTo Inherited from ArrayList Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleErrorCollection Class OracleErrorCollection Class Oracle Data Provider for .NET Classes 4-173 OracleErrorCollection Static Methods OracleErrorCollection static methods are listed in Table 4–58. Table 4–58 OracleErrorCollection Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleErrorCollection Class ■ OracleErrorCollection Members OracleErrorCollection Properties 4-174 Oracle Data Provider for .NET Developer’s Guide OracleErrorCollection Properties OracleErrorCollection properties are listed in Table 4–59. Table 4–59 OracleErrorCollection Properties Name Description Capacity Inherited from ArrayList Count Inherited from ArrayList IsReadOnly Inherited from ArrayList IsSynchronized Inherited from ArrayList Item Inherited from ArrayList See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleErrorCollection Class ■ OracleErrorCollection Members OracleErrorCollection Class Oracle Data Provider for .NET Classes 4-175 OracleErrorCollection Public Methods OracleErrorCollection public methods are listed in Table 4–60. Table 4–60 OracleErrorCollection Public Methods Public Method Description CopyTo Inherited from ArrayList Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleErrorCollection Class ■ OracleErrorCollection Members OracleException Class 4-176 Oracle Data Provider for .NET Developer’s Guide OracleException Class The OracleException class represents an exception that is thrown when the Oracle Data Provider for .NET encounters an error. Each OracleException object contains at least one OracleError object in the Error property that describes the error or warning. Class Inheritance Object Exception SystemException OracleException Declaration // C# public sealed class OracleException : SystemException Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleExceptionSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand object using the connection object OracleCommand cmd = con.CreateCommand(); try { cmd.CommandText = "insert into notable values (99, 'MyText')"; cmd.ExecuteNonQuery(); } catch (OracleException ex) { Console.WriteLine("Record is not inserted into the database table."); Console.WriteLine("Exception Message: " + ex.Message); Console.WriteLine("Exception Source: " + ex.Source); } } } OracleException Class Oracle Data Provider for .NET Classes 4-177 Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Members ■ OracleException Methods ■ OracleException Static Methods ■ OracleException Static Methods ■ OracleException Properties ■ OracleException Methods OracleException Members 4-178 Oracle Data Provider for .NET Developer’s Guide OracleException Members OracleException members are listed in the following tables: OracleException Static Methods OracleException static methods are listed in Table 4–61. OracleException Properties OracleException properties are listed in Table 4–62. OracleException Methods OracleException methods are listed in Table 4–63. Table 4–61 OracleException Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–62 OracleException Properties Properties Description DataSource Specifies the TNS name that contains the information for connecting to an Oracle instance Errors Specifies a collection of one or more OracleError objects that contain information about exceptions generated by the Oracle database HelpLink Inherited from Exception InnerException Inherited from Exception Message Specifies the error messages that occur in the exception Number Specifies the Oracle error number Procedure Specifies the stored procedure that cause the exception Source Specifies the name of the data provider that generates the error StackTrace Inherited from Exception TargetSite Inherited from Exception Table 4–63 OracleException Methods Methods Description Equals Inherited from Object (Overloaded) GetBaseException Inherited from Exception GetHashCode Inherited from Object GetObjectData Sets the serializable info object with information about the exception GetType Inherited from Object ToString Returns the fully qualified name of this exception OracleException Class Oracle Data Provider for .NET Classes 4-179 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class OracleException Static Methods 4-180 Oracle Data Provider for .NET Developer’s Guide OracleException Static Methods OracleException static methods are listed in Table 4–64. Table 4–64 OracleException Static Methods Method Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleException Class Oracle Data Provider for .NET Classes 4-181 OracleException Properties OracleException properties are listed in Table 4–65. DataSource This property specifies the TNS name that contains the information for connecting to an Oracle instance. Declaration // C# public string DataSource {get;} Property Value The TNS name containing the connect information. Errors This property specifies a collection of one or more OracleError objects that contain information about exceptions generated by the Oracle database. Table 4–65 OracleException Properties Properties Description DataSource Specifies the TNS name that contains the information for connecting to an Oracle instance Errors Specifies a collection of one or more OracleError objects that contain information about exceptions generated by the Oracle database HelpLink Inherited from Exception InnerException Inherited from Exception Message Specifies the error messages that occur in the exception Number Specifies the Oracle error number Procedure Specifies the stored procedure that cause the exception Source Specifies the name of the data provider that generates the error StackTrace Inherited from Exception TargetSite Inherited from Exception See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleException Properties 4-182 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public OracleErrorCollection Errors {get;} Property Value An OracleErrorCollection. Remarks The Errors property contains at least one instance of OracleError objects. Message Overrides Exception This property specifies the error messages that occur in the exception. Declaration // C# public override string Message {get;} Property Value A string. Remarks Message is a concatenation of all errors in the Errors collection. Each error message is concatenated and is followed by a carriage return, except the last one. Number This property specifies the Oracle error number. Declaration // C# public int Number {get;} Property Value The error number. Remarks This error number can be the topmost level of error generated by Oracle and can be a provider-specific error number. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleException Class Oracle Data Provider for .NET Classes 4-183 Procedure This property specifies the stored procedure that caused the exception. Declaration // C# public string Procedure {get;} Property Value The stored procedure name. Source Overrides Exception This property specifies the name of the data provider that generates the error. Declaration // C# public override string Source {get;} Property Value The name of the data provider. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleException Methods 4-184 Oracle Data Provider for .NET Developer’s Guide OracleException Methods OracleException methods are listed in Table 4–66. GetObjectData Overrides Exception This method sets the serializable info object with information about the exception. Declaration // C# public override void GetObjectData(SerializationInfo info, StreamingContext context); Parameters ■ info A SerializationInfo object. ■ context A StreamingContext object. Remarks The information includes DataSource, Message, Number, Procedure, Source, and StackTrace. Table 4–66 OracleException Methods Methods Description Equals Inherited from Object (Overloaded) GetBaseException Inherited from Exception GetHashCode Inherited from Object GetObjectData Sets the serializable info object with information about the exception GetType Inherited from Object ToString Returns the fully qualified name of this exception See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleException Class Oracle Data Provider for .NET Classes 4-185 ToString Overrides Exception This method returns the fully qualified name of this exception, the error message in the Message property, the InnerException.ToString() message, and the stack trace. Declaration // C# public override string ToString(); Return Value The string representation of the exception. Example // C# using System; using Oracle.DataAccess.Client; class ToStringSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand object using the connection object OracleCommand cmd = con.CreateCommand(); try { cmd.CommandText = "insert into notable values (99, 'MyText')"; cmd.ExecuteNonQuery(); // This will throw an exception } catch (OracleException ex) { Console.WriteLine("Record is not inserted into the database table."); Console.WriteLine("ex.ToString() : " + ex.ToString()); } } } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleException Class ■ OracleException Members OracleInfoMessageEventArgs Class 4-186 Oracle Data Provider for .NET Developer’s Guide OracleInfoMessageEventArgs Class The OracleInfoMessageEventArgs class provides event data for the OracleConnection.InfoMessage event. When any warning occurs in the database, the OracleConnection.InfoMessage event is triggered along with the OracleInfoMessageEventArgs object that stores the event data. Class Inheritance Object EventArgs OracleInfoMessageEventArgs Declaration // C# public sealed class OracleInfoMessageEventArgs Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class InfoMessageSample { public static void WarningHandler(object src, OracleInfoMessageEventArgs args) { Console.WriteLine("Source object is: " + src.GetType().Name); Console.WriteLine("InfoMessageArgs.Message is " + args.Message); Console.WriteLine("InfoMessageArgs.Source is " + args.Source); } static void Main() { OracleConnection con = new OracleConnection("User Id=scott;" + "Password=tiger;Data Source=oracle;"); con.Open(); OracleCommand cmd = con.CreateCommand(); //Register to the InfoMessageHandler cmd.Connection.InfoMessage += new OracleInfoMessageEventHandler(WarningHandler); cmd.CommandText = "create or replace procedure SelectWithNoInto( " + " empname in VARCHAR2) AS " + OracleInfoMessageEventArgs Class Oracle Data Provider for .NET Classes 4-187 "BEGIN " + " select * from emp where ename = empname; " + "END SelectWithNoInto;"; // Execute the statement that produces a warning cmd.ExecuteNonQuery(); // Clean up cmd.Dispose(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Members ■ OracleInfoMessageEventArgs Static Methods ■ OracleInfoMessageEventArgs Properties ■ OracleInfoMessageEventArgs Public Methods ■ "OracleConnection Class" on page 4-54 OracleInfoMessageEventArgs Members 4-188 Oracle Data Provider for .NET Developer’s Guide OracleInfoMessageEventArgs Members OracleInfoMessageEventArgs members are listed in the following tables: OracleInfoMessageEventArgs Static Methods The OracleInfoMessageEventArgs static methods are listed in Table 4–67. OracleInfoMessageEventArgs Properties The OracleInfoMessageEventArgs properties are listed in Table 4–68. OracleInfoMessageEventArgs Public Methods The OracleInfoMessageEventArgs methods are listed in Table 4–69. Table 4–67 OracleInfoMessageEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–68 OracleInfoMessageEventArgs Properties Name Description Errors Specifies the collection of errors generated by the data source Message Specifies the error text generated by the data source Source Specifies the name of the object that generated the error Table 4–69 OracleInfoMessageEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class OracleInfoMessageEventArgs Class Oracle Data Provider for .NET Classes 4-189 OracleInfoMessageEventArgs Static Methods The OracleInfoMessageEventArgs static methods are listed in Table 4–70. Table 4–70 OracleInfoMessageEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members OracleInfoMessageEventArgs Properties 4-190 Oracle Data Provider for .NET Developer’s Guide OracleInfoMessageEventArgs Properties The OracleInfoMessageEventArgs properties are listed in Table 4–71. Errors This property specifies the collection of errors generated by the data source. Declaration // C# public OracleErrorCollection Errors {get;} Property Value The collection of errors. Message This property specifies the error text generated by the data source. Declaration // C# public string Message {get;} Property Value The error text. Table 4–71 OracleInfoMessageEventArgs Properties Name Description Errors Specifies the collection of errors generated by the data source Message Specifies the error text generated by the data source Source Specifies the name of the object that generated the error See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members OracleInfoMessageEventArgs Class Oracle Data Provider for .NET Classes 4-191 Source This property specifies the name of the object that generated the error. Declaration // C# public string Source {get;} Property Value The object that generated the error. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members OracleInfoMessageEventArgs Public Methods 4-192 Oracle Data Provider for .NET Developer’s Guide OracleInfoMessageEventArgs Public Methods The OracleInfoMessageEventArgs methods are listed in Table 4–72. Table 4–72 OracleInfoMessageEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleInfoMessageEventArgs Class ■ OracleInfoMessageEventArgs Members OracleInfoMessageEventHandler Delegate Oracle Data Provider for .NET Classes 4-193 OracleInfoMessageEventHandler Delegate The OracleInfoMessageEventHandler represents the signature of the method that handles the OracleConnection.InfoMessage event. Declaration // C# public delegate void OracleInfoMessageEventHandler(object sender, OracleInfoMessageEventArgs eventArgs); Parameter ■ sender The source of the event. ■ eventArgs The OracleInfoMessageEventArgs object that contains the event data. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleConnection Class" on page 4-54 OracleParameter Class 4-194 Oracle Data Provider for .NET Developer’s Guide OracleParameter Class An OracleParameter object represents a parameter for an OracleCommand or a DataSet column. Class Inheritance Object MarshalByRefObject OracleParameter Declaration // C# public sealed class OracleParameter : MarshalByRefObject, IDBDataParameter, IDataParameter, IDisposable, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Exceptions ArgumentException - The type binding is invalid. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleParameterSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleParameter[] prm = new OracleParameter[3]; // Create OracleParameter objects through OracleParameterCollection OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select max(empno) from emp"; int maxno = int.Parse(cmd.ExecuteScalar().ToString()); prm[0] = cmd.Parameters.Add("paramEmpno", OracleDbType.Decimal, maxno + 10, ParameterDirection.Input); prm[1] = cmd.Parameters.Add("paramEname", OracleDbType.Varchar2, "Client", ParameterDirection.Input); prm[2] = cmd.Parameters.Add("paramDeptNo", OracleDbType.Decimal, 10, ParameterDirection.Input); cmd.CommandText = "insert into emp(empno, ename, deptno) values(:1, :2, :3)"; cmd.ExecuteNonQuery(); OracleParameter Class Oracle Data Provider for .NET Classes 4-195 Console.WriteLine("Record for employee id {0} has been inserted.", maxno); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Members ■ OracleParameter Constructors ■ OracleParameter Static Methods ■ OracleParameter Properties ■ OracleParameter Public Methods OracleParameter Members 4-196 Oracle Data Provider for .NET Developer’s Guide OracleParameter Members OracleParameter members are listed in the following tables: OracleParameter Constructors OracleParameter constructors are listed in Table 4–73. OracleParameter Static Methods OracleParameter static methods are listed in Table 4–74. OracleParameter Properties OracleParameter properties are listed in Table 4–75. Table 4–73 OracleParameter Constructors Constructor Description OracleParameter Constructors Instantiates a new instance of OracleParameter class (Overloaded) Table 4–74 OracleParameter Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–75 OracleParameter Properties Name Description ArrayBindSize Specifies the input or output size of a parameter before or after an Array Bind or PL/SQL Associative Array Bind execution ArrayBindStatus Specifies the input or output status of a parameter before or after an Array Bind or PL/SQL Associative Array Bind execution CollectionType Specifies whether the OracleParameter represents a collection, and if so, specifies the collection type DbType Specifies the datatype of the parameter using the Data.DbType enumeration type Direction Specifies whether the parameter is input-only, output-only, bi-directional, or a stored function return value parameter IsNullable This method is a no-op Offset Specifies the offset to the Value property or offset to the elements in the Value property OracleDbType Specifies the Oracle datatype ParameterName Specifies the name of the parameter Precision Specifies the maximum number of digits used to represent the Value property Scale Specifies the number of decimal places to which Value property is resolved OracleParameter Class Oracle Data Provider for .NET Classes 4-197 OracleParameter Public Methods OracleParameter public methods are listed in Table 4–76. Size Specifies the maximum size, in bytes or characters, of the data transmitted to or from the server. For PL/SQL Associative Array Bind, Size specifies the maximum number of elements in PL/SQL Associative Array. SourceColumn Specifies the name of the DataTable Column of the DataSet SourceVersion Specifies the DataRowVersion value to use when loading the Value property of the parameter Status Indicates the status of the execution related to the data in the Value property Value Specifies the value of the Parameter Table 4–76 OracleParameter Public Methods Public Method Description Clone Creates a shallow copy of an OracleParameter object CreateObjRef Inherited from MarshalByRefObject Dispose Releases allocated resources Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject ToString Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class Table 4–75 (Cont.) OracleParameter Properties Name Description OracleParameter Constructors 4-198 Oracle Data Provider for .NET Developer’s Guide OracleParameter Constructors OracleParameter constructors instantiate new instances of the OracleParameter class. Overload List: ■ OracleParameter() This constructor instantiates a new instance of OracleParameter class. ■ OracleParameter (string, OracleDbType) This constructor instantiates a new instance of OracleParameter class using the supplied parameter name and Oracle datatype. ■ OracleParameter(string, object) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name and parameter value. ■ OracleParameter(string, OracleDbType, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, and parameter direction. ■ OracleParameter(string, OracleDbType, object, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, value, and direction. ■ OracleParameter(string, OracleDbType, int) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, and size. ■ OracleParameter(string, OracleDbType, int, string) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, and source column. ■ OracleParameter(string, OracleDbType, int, ParameterDirection, bool, byte, byte, string, DataRowVersion, object) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, direction, null indicator, precision, scale, source column, source version and parameter value. ■ OracleParameter(string, OracleDbType, int, object, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, value, and direction. OracleParameter() This constructor instantiates a new instance of OracleParameter class. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Class Oracle Data Provider for .NET Classes 4-199 Declaration // C# public OracleParameter(); Remarks Default Values: ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter (string, OracleDbType) This constructor instantiates a new instance of OracleParameter class using the supplied parameter name and Oracle datatype. Declaration // C# public OracleParameter(string parameterName, OracleDbType oraType); Parameters ■ parameterName Specifies the parameter name. ■ oraType Specifies the datatype of the OracleParameter. Remarks Changing the DbType implicitly changes the OracleDbType. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Constructors 4-200 Oracle Data Provider for .NET Developer’s Guide Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, object) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name and parameter value. Declaration // C# public OracleParameter(string parameterName, object obj); Parameters ■ parameterName Specifies parameter name. ■ obj Specifies value of the OracleParameter. Remarks Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Class Oracle Data Provider for .NET Classes 4-201 ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, OracleDbType, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, and parameter direction. Declaration // C# public OracleParameter(string parameterName, OracleDbType type, ParameterDirection direction); Parameters ■ parameterName Specifies the parameter name. ■ type Specifies the datatype of the OracleParameter. ■ direction Specifies the direction of the OracleParameter. Remarks Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String ■ ParameterDirection - Input See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Constructors 4-202 Oracle Data Provider for .NET Developer’s Guide ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, OracleDbType, object, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, value, and direction. Declaration // C# public OracleParameter(string parameterName, OracleDbType type, object obj, ParameterDirection direction); Parameters ■ parameterName Specifies the parameter name. ■ type Specifies the datatype of the OracleParameter. ■ obj Specifies the value of the OracleParameter. ■ direction Specifies one of the ParameterDirection values. Remarks Changing the DbType implicitly changes the OracleDbType. Unless explicitly set in the constructor, all the properties have the default values. Default Values: See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Class Oracle Data Provider for .NET Classes 4-203 ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, OracleDbType, int) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, and size. Declaration // C# public OracleParameter(string parameterName, OracleDbType type, int size); Parameters ■ parameterName Specifies the parameter name. ■ type Specifies the datatype of the OracleParameter. ■ size Specifies the size of the OracleParameter value. Remarks Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Constructors 4-204 Oracle Data Provider for .NET Developer’s Guide ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, OracleDbType, int, string) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, and source column. Declaration // C# public OracleParameter(string parameterName, OracleDbType type, int size, string srcColumn); Parameters ■ parameterName Specifies the parameter name. ■ type Specifies the datatype of the OracleParameter. ■ size Specifies the size of the OracleParameter value. ■ srcColumn Specifies the name of the source column. Remarks Unless explicitly set in the constructor, all the properties have the default values. Default Values: See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Class Oracle Data Provider for .NET Classes 4-205 ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter(string, OracleDbType, int, ParameterDirection, bool, byte, byte, string, DataRow- Version, object) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, direction, null indicator, precision, scale, source column, source version and parameter value. Declaration // C# public OracleParameter(string parameterName, OracleDbType oraType, int size, ParameterDirection direction, bool isNullable, byte precision, byte scale, string srcColumn, DataRowVersion srcVersion, object obj); Parameters ■ parameterName Specifies the parameter name. ■ oraType Specifies the datatype of the OracleParameter. ■ size Specifies the size of the OracleParameter value. ■ direction Specifies ParameterDirection value. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 OracleParameter Constructors 4-206 Oracle Data Provider for .NET Developer’s Guide ■ isNullable Specifies if the parameter value can be null. ■ precision Specifies the precision of the parameter value. ■ scale Specifies the scale of the parameter value. ■ srcColumn Specifies the name of the source column. ■ srcVersion Specifies one of the DataRowVersion values. ■ obj Specifies the parameter value. Exceptions ArgumentException - The supplied value does not belong to the type of Value property in any of the OracleTypes. Remarks Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 OracleParameter Class Oracle Data Provider for .NET Classes 4-207 OracleParameter(string, OracleDbType, int, object, ParameterDirection) This constructor instantiates a new instance of the OracleParameter class using the supplied parameter name, datatype, size, value, and direction. Declaration // C# public OracleParameter(string parameterName, OracleDbType type, int size, object obj, ParameterDirection direction); Parameters ■ parameterName Specifies the parameter name. ■ type Specifies the datatype of the OracleParameter. ■ size Specifies the size of the OracleParameter value. ■ obj Specifies the value of the OracleParameter. ■ direction Specifies one of the ParameterDirection values. Remarks Changing the DbType implicitly changes the OracleDbType. Unless explicitly set in the constructor, all the properties have the default values. Default Values: ■ DbType - String ■ ParameterDirection - Input ■ isNullable - true ■ offset - 0 ■ OracleDbType - Varchar2 ■ ParameterAlias - Empty string ■ ParameterName - Empty string ■ Precision - 0 ■ Size - 0 ■ SourceColumn - Empty string ■ SourceVersion - Current ■ ArrayBindStatus - Success ■ Value - null OracleParameter Constructors 4-208 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "OracleParameterCollection Class" on page 4-225 OracleParameter Class Oracle Data Provider for .NET Classes 4-209 OracleParameter Static Methods OracleParameter static methods are listed in Table 4–77. Table 4–77 OracleParameter Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Properties 4-210 Oracle Data Provider for .NET Developer’s Guide OracleParameter Properties OracleParameter properties are listed in Table 4–78. ArrayBindSize This property specifies the maximum size, in bytes or characters, of the data for each array element transmitted to or from the server. This property is used for Array Bind or PL/SQL Associative Array execution. Table 4–78 OracleParameter Properties Name Description ArrayBindSize Specifies the input or output size of elements in Value property of a parameter before or after an Array Bind or PL/SQL Associative Array Bind execution ArrayBindStatus Specifies the input or output status of elements in Value property of a parameter before or after an Array Bind or PL/SQL Associative Array Bind execution CollectionType Specifies whether the OracleParameter represents a collection, and if so, specifies the collection type DbType Specifies the datatype of the parameter using the Data.DbType enumeration type Direction Specifies whether the parameter is input-only, output-only, bi-directional, or a stored function return value parameter IsNullable This method is a no-op Offset Specifies the offset to the Value property or offset to the elements in the Value property OracleDbType Specifies the Oracle datatype ParameterName Specifies the name of the parameter Precision Specifies the maximum number of digits used to represent the Value property Scale Specifies the number of decimal places to which Value property is resolved Size Specifies the maximum size, in bytes or characters, of the data transmitted to or from the server. For PL/SQL Associative Array Bind, Size specifies the maximum number of elements in PL/SQL Associative Array SourceColumn Specifies the name of the DataTable Column of the DataSet SourceVersion Specifies the DataRowVersion value to use when loading the Value property of the parameter Status Indicates the status of the execution related to the data in the Value property Value Specifies the value of the Parameter See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Class Oracle Data Provider for .NET Classes 4-211 Declaration // C# public int[] ArrayBindSize {get; set; } Property Value An array of int values specifying the size. Remarks Default = null. This property is only used for variable size element types for an Array Bind or PL/SQL Associative Array. For fixed size element types, this property is ignored. Each element in the ArrayBindSize corresponds to the bind size of an element in the Value property. Before execution, ArrayBindSize specifies the maximum size of each element to be bound in the Value property. After execution, it contains the size of each element returned in the Value property. For binding a PL/SQL Associative Array, whose elements are of a variable-length element type, as an InputOutput , Out, or ReturnValue parameter, this property must be set properly. The number of elements in ArrayBindSize must be equal to the value specified in the OracleParameter.Size property. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class ArrayBindSizeSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleParameter[] prm = new OracleParameter[3]; // Create OracleParameter objects through OracleParameterCollection OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select max(empno) from emp"; int maxno = int.Parse(cmd.ExecuteScalar().ToString()); // Set the ArrayBindCount for Array Binding cmd.ArrayBindCount = 2; prm[0] = cmd.Parameters.Add("paramEmpno", OracleDbType.Decimal, new int[2] {maxno + 10, maxno + 11}, ParameterDirection.Input); prm[1] = cmd.Parameters.Add("paramEname", OracleDbType.Varchar2, new string[2] {"Client1xxx", "Client2xxx"}, ParameterDirection.Input); prm[2] = cmd.Parameters.Add("paramDeptNo", OracleDbType.Decimal, new int[2] {10, 10}, ParameterDirection.Input); // Set the ArrayBindSize for prm[1] // These sizes indicate the maximum size of the elements in Value property prm[1].ArrayBindSize = new int[2]; OracleParameter Properties 4-212 Oracle Data Provider for .NET Developer’s Guide prm[1].ArrayBindSize[0] = 7; // Set ename = "Client1" prm[1].ArrayBindSize[1] = 7; // Set ename = "Client2" cmd.CommandText = "insert into emp(empno, ename, deptno) values(:1, :2, :3)"; cmd.ExecuteNonQuery(); Console.WriteLine("Record for employee id {0} has been inserted.", maxno + 10); Console.WriteLine("Record for employee id {0} has been inserted.", maxno + 11); prm[0].Dispose(); prm[1].Dispose(); prm[2].Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } ArrayBindStatus This property specifies the input or output status of each element in the Value property before or after an Array Bind or PL/SQL Associative Array execution. Declaration // C# public OracleParameterStatus[] ArrayBindStatus { get; set; } Property Value An array of OracleParameterStatus enumerated values. Exceptions ArgumentOutofRangeException - The Status value specified is invalid. Remarks Default = null. ArrayBindStatus is used for Array Bind and PL/SQL Associative Array execution only. Before execution, ArrayBindStatus indicates the bind status of each element in the Value property. After execution, it contains the execution status of each element in the Value property. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "ArrayBindCount" on page 4-12 ■ "Size" on page 4-217 and "Value" on page 4-221 for more information on binding Associative Arrays ■ "ArrayBindStatus" on page 4-212 OracleParameter Class Oracle Data Provider for .NET Classes 4-213 CollectionType This property specifies whether the OracleParameter represents a collection, and if so, specifies the collection type. Declaration // C# public OracleCollectionType CollectionType { get; set; } Property Value An OracleCollectionType enumerated value. Exceptions ArgumentException - The OracleCollectionType value specified is invalid. Remarks Default = OracleCollectionType.None. If OracleParameter is used to bind a PL/SQL Associative Array, then CollectionType must be set to OracleCollectionType.PLSQLAssociativeArray. DbType This property specifies the datatype of the parameter using the Data.DbType enumeration type. Declaration // C# public DbType DbType {get; set; } Property Value A DbType enumerated value. Implements IDataParameter See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "ArrayBindCount" on page 4-12 ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "Value" on page 4-221 for more information on binding Associative Arrays ■ "ArrayBindSize" on page 4-210 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Properties 4-214 Oracle Data Provider for .NET Developer’s Guide Exceptions ArgumentException - The DbType value specified is invalid. Remarks Default = DbType.String DbType is the datatype of each element in the array if the OracleParameter object is used for Array Bind or PL/SQL Associative Array Bind execution. Due to the link between DbType and OracleDbType properties, if the DbType property is set, the OracleDbType property is inferred from DbType. Direction This property specifies whether the parameter is input-only, output-only, bi-directional, or a stored function return value parameter. Declaration // C# public ParameterDirection Direction { get; set; } Property Value A ParameterDirection enumerated value. Implements IDataParameter Exceptions ArgumentOutOfRangeException - The ParameterDirection value specified is invalid. Remarks Default = ParameterDirection.Input Possible values: Input, InputOutput, Output, and ReturnValue. Offset This property specifies the offset to the Value property. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "Inference of OracleDbType from DbType" on page 3-13 ■ "CollectionType" on page 4-213 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Class Oracle Data Provider for .NET Classes 4-215 Declaration // C# public int Offset { get; set; } Property Value An int that specifies the offset. Exceptions ArgumentOutOfRangeException - The Offset value specified is invalid. Remarks Default = 0 For Array Bind and PL/SQL Associative Array Bind, Offset applies to every element in the Value property. The Offset property is used for binary and string data types. The Offset property represents the number of bytes for binary types and the number of characters for strings. The count for strings does not include the terminating character if a null is referenced. The Offset property is used by parameters of the following types: ■ OracleDbType.BFile ■ OracleDbType.Blob ■ OracleDbType.LongRaw ■ OracleDbType.Raw ■ OracleDbType.Char ■ OracleDbType.Clob ■ OracleDbType.NClob ■ OracleDbType.NChar ■ OracleDbType.NVarchar2 ■ OracleDbType.Varchar2 OracleDbType This property specifies the Oracle datatype. Declaration // C# public OracleDbType OracleDbType { get; set; } Property Value An OracleDbType enumerated value. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Properties 4-216 Oracle Data Provider for .NET Developer’s Guide Remarks Default = OracleDbType.Varchar2 If the OracleParameter object is used for Array Bind or PL/SQL Associative Array Bind execution, OracleDbType is the datatype of each element in the array. The OracleDbType property and DbType property are linked. Therefore, setting the OracleDbType property changes the DbType property to a supporting DbType. ParameterName This property specifies the name of the parameter. Declaration // C# public string ParameterName { get; set; } Property Value String Implements IDataParameter Remarks Default = null Oracle supports ParameterName up to 30 characters. Precision This property specifies the maximum number of digits used to represent the Value property. Declaration // C# Public byte Precision { get; set; } Property Value byte See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleDbType Enumeration" on page 4-282 ■ "Inference of DbType from OracleDbType" on page 3-12 ■ "CollectionType" on page 4-213 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Class Oracle Data Provider for .NET Classes 4-217 Remarks Default = 0 The Precision property is used by parameters of type OracleDbType.Decimal. Oracle supports Precision range from 0 to 38. For Array Bind and PL/SQL Associative Array Bind, Precision applies to each element in the Value property. Scale This property specifies the number of decimal places to which Value property is resolved. Declaration // C# public byte Scale { get; set; } Property Value byte Remarks Default = 0. Scale is used by parameters of type OracleDbType.Decimal. Oracle supports Scale between -84 and 127. For Array Bind and PL/SQL Associative Array Bind, Scale applies to each element in the Value property. Size This property specifies the maximum size, in bytes or characters, of the data transmitted to or from the server. Declaration // C# public int Size { get; set;} See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ "Value" on page 4-221 ■ OracleParameter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "Value" on page 4-221 OracleParameter Properties 4-218 Oracle Data Provider for .NET Developer’s Guide Property Value int Exceptions ArgumentOutOfRangeException - The Size value specified is invalid. InvalidOperationException - The Size = 0 when the OracleParameter object is used to bind a PL/SQL Associative Array. Remarks For PL/SQL Associative Array Bind, Size specifies the maximum number of elements in PL/SQL Associative Array. If Size is not explicitly set, it is inferred from the actual size of the specified parameter value when binding only for input parameters. Output parameters must have their size defined explicitly. The default value is 0. Before execution, this property specifies the maximum size to be bound in the Value property. After execution, it contains the size of the type in the Value property. Size is used for parameters of the following types: ■ OracleDbType.Blob ■ OracleDbType.Char ■ OracleDbType.Clob ■ OracleDbType.LongRaw ■ OracleDbType.NChar ■ OracleDbType.NClob ■ OracleDbType.NVarchar2 ■ OracleDbType.Raw ■ OracleDbType.Varchar2 The value of Size is handled as follows: ■ Fixed length datatypes: ignored ■ Variable length datatypes: describes the maximum amount of data transmitted to or from the server. For character data, Size is in number of characters and for binary data, it is in number of bytes. If the Size is not explicitly set, it is inferred from the actual size of the specified parameter value when binding. If the OracleParameter object is used to bind a PL/SQL Associative Array, Size specifies the maximum number of elements in the PL/SQL Associative Array. Before the execution, this property specifies the maximum number of elements in the PL/SQL Associative Array. After the execution, it specifies the current number of elements returned in the PL/SQL Associative Array. For Output and InputOutput Note: Size does not include the null terminating character for the string data. OracleParameter Class Oracle Data Provider for .NET Classes 4-219 parameters and return values, Size specifies the maximum number of elements in the PL/SQL Associative Array. ODP.NET does not support binding an empty PL/SQL Associative Array. Therefore, Size cannot be set to 0 when the OracleParameter object is used to bind a PL/SQL Associative Array. SourceColumn This property specifies the name of the DataTable Column of the DataSet. Declaration // C# public string SourceColumn { get; set; } Property Value A string. Implements IDataParameter Remarks Default = empty string SourceVersion This property specifies the DataRowVersion value to use when loading the Value property of the parameter. Declaration // C# public DataRowVersion SourceVersion { get; set; } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleDbType Enumeration" on page 4-282 ■ "CollectionType" on page 4-213 ■ "ArrayBindSize" on page 4-210 ■ "ArrayBindStatus" on page 4-212 ■ "Value" on page 4-221 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Properties 4-220 Oracle Data Provider for .NET Developer’s Guide Property Value DataRowVersion Implements IDataParameter Exceptions ArgumentOutOfRangeException - The DataRowVersion value specified is invalid. Remarks Default = DataRowVersion.Current SourceVersion is used by the OracleDataAdapter.UpdateCommand() during the OracleDataAdapter.Update to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the OracleDataAdapter.InsertCommand() and the OracleDataAdapter.DeleteCommand(). Status This property indicates the status of the execution related to the data in the Value property. Declaration // C# public OracleParameterStatus Status { get; set; } Property Value An OracleParameterStatus enumerated value. Exceptions ArgumentOutOfRangeException - The Status value specified is invalid. Remarks Default = OracleParameterStatus.Success Before execution, this property indicates the bind status related to the Value property. After execution, it returns the status of the execution. Status indicates whether: ■ A NULL is fetched from a column. ■ Truncation has occurred during the fetch; then Value was not big enough to hold the data. ■ A NULL is to be inserted into a database column; then Value is ignored, and a NULL is inserted into a database column. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Class Oracle Data Provider for .NET Classes 4-221 This property is ignored for Array Bind and PL/SQL Associative Array Bind. Instead, ArrayBindStatus property is used. Value This property specifies the value of the Parameter. Declaration // C# public object Value { get; set; } Property Value An object. Implements IDataParameter Exceptions ArgumentException - The Value property specified is invalid. InvalidArgumentException- The Value property specified is invalid. Remarks Default = null If the OracleParameter object is used for Array Bind or PL/SQL Associative Array, Value is an array of parameter values. The Value property can be overwritten by OracleDataAdapter.Update(). The provider attempts to convert any type of value if it supports the IConvertible interface. Conversion errors occur if the specified type is not compatible with the value. When sending a null parameter value to the database, the user must specify DBNull, not null. The null value in the system is an empty object that has no value. DBNull is used to represent null values. The user can also specify a null value by setting Status to OracleParameterStatus.NullValue. In this case, the provider sends a null value to the database. If neither OracleDbType nor DbType are set, their values can be inferred by Value. Please see the following for related information: ■ Tables in section "Inference of DbType and OracleDbType from Value" on page 3-14 ■ "ArrayBindCount" on page 4-12 ■ "ArrayBindSize" on page 4-210 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "OracleParameterStatus Enumeration" on page 4-284 ■ "ArrayBindStatus" on page 4-212 OracleParameter Properties 4-222 Oracle Data Provider for .NET Developer’s Guide ■ "ArrayBindStatus" on page 4-212 ■ "OracleDbType Enumeration" on page 4-282 For input parameters the value is: ■ Bound to the OracleCommand that is sent to the server. ■ Converted to the datatype specified in OracleDbType or DbType when the provider sends the data to the server. For output parameters the value is: ■ Set on completion of the OracleCommand (true for return value parameters also). ■ Set to the data from the server, to the datatype specified in OracleDbType or DbType. When array binding is used with: ■ Input parameter - Value should be set to an array of values. OracleCommand.ArrayBindCount should be set to a value that is greater than zero to indicate the number of elements to be bound. The number of elements in the array should be equal to the OracleCommand.ArrayBindCount property; otherwise, their minimum value is used to bind the elements in the array. ■ Output parameter - OracleCommand.ArrayBindCount should be set to a value that is greater than zero to indicate the number of elements to be retrieved (for SELECT statements). When PL/SQL Associative Array binding is used with: ■ Input parameter – Value should be set to an array of values. CollectionType should be set to OracleCollection.PLSQLAssociativeArray.Size should be set to specify the possible maximum number of array elements in the PL/SQL Associative Array. If Size is smaller than the number of elements in Value, then Size specifies the number of elements in the Value property to be bound. ■ Output parameter - CollectionType should be set to OracleCollection.PLSQLAssociativeArray. Size should be set to specify the maximum number of array elements in PL/SQL Associative Array. Each parameter should have a value. To bind a parameter with a null value, set Value to DBNull.Value, or set Status to OracleParameterStatus. NullInsert. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members ■ "ArrayBindCount" on page 4-12 ■ "OracleParameterStatus Enumeration" on page 4-284 OracleParameter Class Oracle Data Provider for .NET Classes 4-223 OracleParameter Public Methods OracleParameter public methods are listed in Table 4–79. Clone This method creates a shallow copy of an OracleParameter object. Declaration // C# public object Clone(); Return Value An OracleParameter object. Implements ICloneable Remarks The cloned object has the same property values as that of the object being cloned. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class CloneSample { Table 4–79 OracleParameter Public Methods Public Method Description Clone Creates a shallow copy of an OracleParameter object CreateObjRef Inherited from MarshalByRefObject Dispose Releases allocated resources Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject ToString Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameter Public Methods 4-224 Oracle Data Provider for .NET Developer’s Guide static void Main() { OracleParameter prm1 = new OracleParameter(); // Prints "prm1.ParameterName = " Console.WriteLine("prm1.ParameterName = " + prm1.ParameterName); // Set the ParameterName before cloning prm1.ParameterName = "MyParam"; // Clone the OracleParameter OracleParameter prm2 = (OracleParameter) prm1.Clone(); // Prints "prm2.ParameterName = MyParam" Console.WriteLine("prm2.ParameterName = " + prm2.ParameterName); prm1.Dispose(); prm2.Dispose(); } } Dispose This method releases resources allocated for an OracleParameter object. Declaration // C# public void Dispose(); Implements IDisposable See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameter Class ■ OracleParameter Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-225 OracleParameterCollection Class An OracleParameterCollection class represents a collection of all parameters relevant to an OracleCommand object and their mappings to DataSet columns. Class Inheritance Object MarshalByRefObject OracleParameterCollection Declaration // C# public sealed class OracleParameterCollection : MarshalByRefObject, IDataParameterCollection, IList, ICollection, IEnumerable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks The position of an OracleParameter added into the OracleParameterCollection is the binding position in the SQL statement. Position is 0-based and is used only for positional binding. If named binding is used, the position of an OracleParameter in the OracleParameterCollection is ignored. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleParameterCollectionSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleParameter[] prm = new OracleParameter[3]; // Create OracleParameter objects through OracleParameterCollection OracleCommand cmd = con.CreateCommand(); cmd.CommandText = "select max(empno) from emp"; int maxno = int.Parse(cmd.ExecuteScalar().ToString()); prm[0] = cmd.Parameters.Add("paramEmpno", OracleDbType.Decimal, maxno + 10, ParameterDirection.Input); prm[1] = cmd.Parameters.Add("paramEname", OracleDbType.Varchar2, "Client", ParameterDirection.Input); OracleParameterCollection Class 4-226 Oracle Data Provider for .NET Developer’s Guide prm[2] = cmd.Parameters.Add("paramDeptNo", OracleDbType.Decimal, 10, ParameterDirection.Input); cmd.CommandText = "insert into emp(empno, ename, deptno) values(:1, :2, :3)"; cmd.ExecuteNonQuery(); Console.WriteLine("Record for employee id {0} has been inserted.", maxno + 10); // Remove all parametmers from OracleParameterCollection cmd.Parameters.Clear(); prm[0].Dispose(); prm[1].Dispose(); prm[2].Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Members ■ OracleParameterCollection Static Methods ■ OracleParameterCollection Properties ■ OracleParameterCollection Public Methods OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-227 OracleParameterCollection Members OracleParameterCollection members are listed in the following tables: OracleParameterCollection Static Methods OracleParameterCollection static methods are listed in Table 4–80. OracleParameterCollection Properties OracleParameterCollection properties are listed in Table 4–81. OracleParameterCollection Public Methods OracleParameterCollection public methods are listed in Table 4–82. Table 4–80 OracleParameterCollection Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–81 OracleParameterCollection Properties Name Description Count Specifies the number of OracleParameters in the collection Item Gets and sets the OracleParameter object (Overloaded) Table 4–82 OracleParameterCollection Public Methods Public Method Description Add Adds objects to the collection (Overloaded) Clear Removes all the OracleParameter objects from the collection Contains Indicates whether objects exist in the collection (Overloaded) CopyTo Copies OracleParameter objects from the collection, starting with the supplied index to the supplied array CreateObjRef Inherited from MarshalByRefObject Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IndexOf Returns the index of the objects in the collection (Overloaded) Insert Inserts the supplied OracleParameter to the collection at the specified index Remove Removes objects from the collection OracleParameterCollection Members 4-228 Oracle Data Provider for .NET Developer’s Guide RemoveAt Removes objects from the collection by location (Overloaded) ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class Table 4–82 (Cont.) OracleParameterCollection Public Methods Public Method Description OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-229 OracleParameterCollection Static Methods OracleParameterCollection static methods are listed in Table 4–83. Table 4–83 OracleParameterCollection Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Properties 4-230 Oracle Data Provider for .NET Developer’s Guide OracleParameterCollection Properties OracleParameterCollection properties are listed in Table 4–84. Count This property specifies the number of OracleParameter objects in the collection. Declaration // C# public int Count {get;} Property Value The number of OracleParameter objects. Implements ICollection Remarks Default = 0 Item Item gets and sets the OracleParameter object. Overload List: ■ Item[int] This property gets and sets the OracleParameter object at the index specified by the supplied parameterIndex. ■ Item[string] This property gets and sets the OracleParameter object using the parameter name specified by the supplied parameterName. Table 4–84 OracleParameterCollection Properties Name Description Count Specifies the number of OracleParameters in the collection Item Gets and sets the OracleParameter object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-231 Item[int] This property gets and sets the OracleParameter object at the index specified by the supplied parameterIndex. Declaration // C# public object Item[int parameterIndex] {get; set;} Property Value An object. Implements IList Exceptions IndexOutOfRangeException - The supplied index does not exist. Remarks The OracleParameterCollection class is a zero-based index. Item[string] This property gets and sets the OracleParameter object using the parameter name specified by the supplied parameterName. Declaration // C# public OracleParameter Item[string parameterName] {get; set;}; Property Value An OracleParameter. Implements IDataParameterCollection Exceptions IndexOutOfRangeException - The supplied parameter name does not exist. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Properties 4-232 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-233 OracleParameterCollection Public Methods OracleParameterCollection public methods are listed in Table 4–85. Add Add adds objects to the collection. Overload List: ■ Add(object) This method adds the supplied object to the collection. ■ Add(OracleParameter) This method adds the supplied OracleParameter object to the collection. ■ Add(string, object) Table 4–85 OracleParameterCollection Public Methods Public Method Description Add Adds objects to the collection (Overloaded) Clear Removes all the OracleParameter objects from the collection Contains Indicates whether objects exist in the collection (Overloaded) CopyTo Copies OracleParameter objects from the collection, starting with the supplied index to the supplied array CreateObjRef Inherited from MarshalByRefObject Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IndexOf Returns the index of the objects in the collection (Overloaded) Insert Inserts the supplied OracleParameter to the collection at the specified index Remove Removes objects from the collection RemoveAt Removes objects from the collection by location (Overloaded) ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-234 Oracle Data Provider for .NET Developer’s Guide This method adds an OracleParameter object to the collection using the supplied name and object value. ■ Add(string, OracleDbType) This method adds an OracleParameter object to the collection using the supplied name and database type. ■ Add(string, OracleDbType, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, and direction. ■ Add(string, OracleDbType, object, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, parameter value, and direction. ■ Add(string, OracleDbType, int, object, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, size, parameter value, and direction. ■ Add(string, OracleDbType, int) This method adds an OracleParameter object to the collection using the supplied name, database type, and size. ■ Add (string, OracleDbType, int, string) This method adds an OracleParameter object to the collection using the supplied name, database type, size, and source column. ■ Add(string, OracleDbType, int, ParameterDirection, bool, byte, byte, string, DataRowVersion, object) This method adds an OracleParameter object to the collection using the supplied name, database type, size, direction, null indicator, precision, scale, source column, source version, and parameter value. Add(object) This method adds the supplied object to the collection. Declaration // C# public int Add(object obj); Parameters ■ obj Specifies the supplied object. Return Value The index at which the new OracleParameter is added. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-235 Implements IList Remarks InvalidCastException - The supplied obj cannot be cast to an OracleParameter object. Add(OracleParameter) This method adds the supplied OracleParameter object to the collection. Declaration // C# public OracleParameter Add(OracleParameter paramObj); Parameters ■ paramObj Specifies the supplied OracleParameter object. Return Value The newly created OracleParameter object which was added to the collection. Add(string, object) This method adds an OracleParameter object to the collection using the supplied name and object value Declaration // C# public OracleParameter Add(string name, object val); Parameters ■ name Specifies the parameter name. ■ val Specifies the OracleParameter value. Return Value The newly created OracleParameter object which was added to the collection. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-236 Oracle Data Provider for .NET Developer’s Guide Add(string, OracleDbType) This method adds an OracleParameter object to the collection using the supplied name and database type. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType); Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. Return Value The newly created OracleParameter object which was added to the collection. Add(string, OracleDbType, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, and direction. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, ParameterDirection direction); Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ direction Specifies the OracleParameter direction. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-237 Return Value The newly created OracleParameter object which was added to the collection. Add(string, OracleDbType, object, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, parameter value, and direction. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, object val, ParameterDirection dir); Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ val Specifies the OracleParameter value. ■ dir Specifies one of the ParameterDirection values. Return Value The newly created OracleParameter object which was added to the collection. Example // C# using System; using System.Data; using Oracle.DataAccess.Client; class AddSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add parameter to the OracleParameterCollection OracleParameter prm = cmd.Parameters.Add( "MyParam", OracleDbType.Decimal, 1, ParameterDirection.Input); // Prints "cmd.Parameters.Count = 1" Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members ■ "OracleDbType Enumeration" on page 4-282 OracleParameterCollection Public Methods 4-238 Oracle Data Provider for .NET Developer’s Guide prm.Dispose(); cmd.Dispose(); } } Add(string, OracleDbType, int, object, ParameterDirection) This method adds an OracleParameter object to the collection using the supplied name, database type, size, parameter value, and direction. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, int size, object val, ParameterDirection dir; Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ size Specifies the size of OracleParameter. ■ val Specifies the OracleParameter value. ■ dir Specifies one of the ParameterDirection values. Return Value The newly created OracleParameter object which was added to the collection. Add(string, OracleDbType, int) This method adds an OracleParameter object to the collection using the supplied name, database type, and size. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members ■ "OracleDbType Enumeration" on page 4-282 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members ■ "OracleDbType Enumeration" on page 4-282 OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-239 Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, int size); Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ size Specifies the size of OracleParameter. Return Value The newly created OracleParameter object which was added to the collection. Example // C# using System; using Oracle.DataAccess.Client; class AddSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add parameter to the OracleParameterCollection OracleParameter prm = cmd.Parameters.Add( "MyParam", OracleDbType.Varchar2, 10); // Prints "cmd.Parameters.Count = 1" Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); prm.Dispose(); cmd.Dispose(); } } Add (string, OracleDbType, int, string) This method adds an OracleParameter object to the collection using the supplied name, database type, size, and source column. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, int size, string srcColumn); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-240 Oracle Data Provider for .NET Developer’s Guide Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ size Specifies the size of OracleParameter. ■ srcColumn Specifies the name of the source column. Return Value An OracleParameter. Add(string, OracleDbType, int, ParameterDirection, bool, byte, byte, string, DataRowVersion, object) This method adds an OracleParameter object to the collection using the supplied name, database type, size, direction, null indicator, precision, scale, source column, source version, and parameter value. Declaration // C# public OracleParameter Add(string name, OracleDbType dbType, int size, ParameterDirection dir, bool isNullable, byte precision, byte scale, string srcColumn, DataRowVersion version, object val); Parameters ■ name Specifies the parameter name. ■ dbType Specifies the datatype of the OracleParameter. ■ size Specifies the size of OracleParameter. ■ dir Specifies one of the ParameterDirection values. ■ isNullable Specifies if the parameter value can be null. ■ precision Specifies the precision of the parameter value. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-241 ■ scale Specifies the scale of the parameter value. ■ srcColumn Specifies the name of the source column. ■ version Specifies one of the DataRowVersion values. ■ val Specifies the parameter value. Return Value The newly created OracleParameter object which was added to the collection. Exceptions ArgumentException - The type of supplied val does not belong to the type of Value property in any of the ODP.NET Types. Clear This method removes all the OracleParameter objects from the collection. Declaration // C# public void Clear(); Implements IList Example // C# using System; using Oracle.DataAccess.Client; class ClearSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add parameter to the OracleParameterCollection OracleParameter prm = cmd.Parameters.Add("MyParam", OracleDbType.Decimal); // Prints "cmd.Parameters.Count = 1" Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); // Clear all parameters in the OracleParameterCollection See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-242 Oracle Data Provider for .NET Developer’s Guide cmd.Parameters.Clear(); // Prints "cmd.Parameters.Count = 0" Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); prm.Dispose(); cmd.Dispose(); } } Contains Contains indicates whether the supplied object exists in the collection. Overload List: ■ Contains(object) This method indicates whether the supplied object exists in the collection. ■ Contains(string) This method indicates whether an OracleParameter object exists in the collection using the supplied string. Contains(object) This method indicates whether the supplied object exists in the collection. Declaration // C# public bool Contains(object obj) Parameters ■ obj Specifies the object. Return Value A bool that indicates whether or not the OracleParameter specified is inside the collection. Implements IList See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-243 Exceptions InvalidCastException - The supplied obj is not an OracleParameter object. Remarks Returns true if the collection contains the OracleParameter object; otherwise, returns false. Example // C# using System; using Oracle.DataAccess.Client; class ContainsSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add parameter to the OracleParameterCollection OracleParameter prm1 = cmd.Parameters.Add("MyParam", OracleDbType.Decimal); // Check if the OracleParameterCollection contains prm1 bool bContains = cmd.Parameters.Contains(prm1); // Prints "bContains = True" Console.WriteLine("bContains = " + bContains); OracleParameter prm2 = new OracleParameter(); // Check if the OracleParameterCollection contains prm2 bContains = cmd.Parameters.Contains(prm2); // Prints "bContains = False" Console.WriteLine("bContains = " + bContains); prm1.Dispose(); prm2.Dispose(); cmd.Dispose(); } } Contains(string) This method indicates whether an OracleParameter object exists in the collection using the supplied string. Declaration // C# public bool Contains(string name); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-244 Oracle Data Provider for .NET Developer’s Guide Parameters ■ name Specifies the name of OracleParameter object. Return Value Returns true if the collection contains the OracleParameter object with the specified parameter name; otherwise, returns false. Implements IDataParameterCollection Example // C# using System; using Oracle.DataAccess.Client; class ContainsSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add parameter to the OracleParameterCollection OracleParameter prm = cmd.Parameters.Add("MyParam", OracleDbType.Decimal); // Check if the OracleParameterCollection contains "MyParam" bool bContains = cmd.Parameters.Contains("MyParam"); // Prints "bContains = True" Console.WriteLine("bContains = " + bContains); // Check if the OracleParameterCollection contains "NoParam" bContains = cmd.Parameters.Contains("NoParam"); // Prints "bContains = False" Console.WriteLine("bContains = " + bContains); prm.Dispose(); cmd.Dispose(); } } CopyTo This method copies OracleParameter objects from the collection, starting with the supplied index to the supplied array. Declaration // C# See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-245 public void CopyTo(Array array, int index); Parameters ■ array Specifies the array. ■ index Specific the index to array. Implements ICollection IndexOf IndexOf returns the index of the OracleParameter object in the collection. Overload List: ■ IndexOf(object) This method returns the index of the OracleParameter object in the collection. ■ IndexOf(String) This method returns the index of the OracleParameter object with the specified name in the collection. IndexOf(object) This method returns the index of the OracleParameter object in the collection. Declaration // C# public int IndexOf(object obj); Parameters ■ obj Specifies the object. Return Value Returns the index of the OracleParameter object in the collection. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-246 Oracle Data Provider for .NET Developer’s Guide Implements IList Exceptions InvalidCastException - The supplied obj cannot be cast to an OracleParameter object. Remarks Returns the index of the supplied OracleParameter obj in the collection. IndexOf(String) This method returns the index of the OracleParameter object with the specified name in the collection. Declaration // C# public int IndexOf(String name); Parameters ■ name Specifies the name of parameter. Return Value Returns the index of the supplied OracleParameter in the collection. Implements IDataParameterCollection Insert This method inserts the supplied OracleParameter object to the collection at the specified index. Declaration // C# public void Insert(int index, object obj); Parameters ■ index See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-247 Specifies the index. ■ obj Specifies the OracleParameter object. Implements IList Remarks An InvalidCastException is thrown if the supplied obj cannot be cast to an OracleParameter object. Remove This method removes the supplied OracleParameter from the collection. Declaration // C# public void Remove(object obj); Parameters ■ obj Specifies the object to remove. Implements IList Exceptions InvalidCastException - The supplied obj cannot be cast to an OracleParameter object. Example // C# using System; using Oracle.DataAccess.Client; class RemoveSample { static void Main() { OracleCommand cmd = new OracleCommand(); // Add 2 parameters to the OracleParameterCollection OracleParameter prm1 = cmd.Parameters.Add("MyParam1", OracleDbType.Decimal); OracleParameter prm2 = cmd.Parameters.Add("MyParam2", OracleDbType.Decimal); // Prints "cmd.Parameters.Count = 2" See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Public Methods 4-248 Oracle Data Provider for .NET Developer’s Guide Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); // Remove the 1st parameter from the OracleParameterCollection cmd.Parameters.Remove(prm1); // Prints "cmd.Parameters.Count = 1" Console.WriteLine("cmd.Parameters.Count = " + cmd.Parameters.Count); // Prints "cmd.Parameters[0].ParameterName = MyParam2" Console.WriteLine("cmd.Parameters[0].ParameterName = " + cmd.Parameters[0].ParameterName); prm1.Dispose(); prm2.Dispose(); cmd.Dispose(); } } RemoveAt RemoveAt removes the OracleParameter object from the collection by location. Overload List: ■ RemoveAt(int) This method removes from the collection the OracleParameter object located at the index specified by the supplied index. ■ RemoveAt(String) This method removes from the collection the OracleParameter object specified by the supplied name. RemoveAt(int) This method removes from the collection the OracleParameter object located at the index specified by the supplied index. Declaration // C# public void RemoveAt(int index); Parameters ■ index See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleParameterCollection Class Oracle Data Provider for .NET Classes 4-249 Specifies the index from which the OracleParameter is to be removed. Implements IList RemoveAt(String) This method removes from the collection the OracleParameter object specified by the supplied name. Declaration // C# public void RemoveAt(String name); Parameters ■ name The name of the OracleParameter object to be removed from the collection. Implements IDataParameterCollection See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleParameterCollection Class ■ OracleParameterCollection Members OracleRowUpdatedEventHandler Delegate 4-250 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatedEventHandler Delegate The OracleRowUpdatedEventHandler delegate represents the signature of the method that handles the OracleDataAdapter.RowUpdated event. Declaration // C# public delegate void OracleRowUpdatedEventHandler(object sender, OracleRowUpdatedEventArgs eventArgs); Parameters ■ sender The source of the event. ■ eventArgs The OracleRowUpdatedEventArgs object that contains the event data. Remarks Event callbacks can be registered through this event delegate for applications that wish to be notified after a row is updated. In the .NET framework, the convention of an event delegate requires two parameters: the object that raises the event and the event data. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleDataAdapter Class" on page 4-86 OracleRowUpdatedEventArgs Class Oracle Data Provider for .NET Classes 4-251 OracleRowUpdatedEventArgs Class The OracleRowUpdatedEventArgs class provides event data for the OracleDataAdapter.RowUpdated event. Class Inheritance Object EventArgs RowUpdatedEventArgs OracleRowUpdatedEventArgs Declaration // C# public sealed class OracleRowUpdatedEventArgs : RowUpdatedEventArgs Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example The example for the RowUpdated event shows how to use OracleRowUpdatedEventArgs. See "Example" on page 4-105. Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Members ■ OracleRowUpdatedEventArgs Constructor ■ OracleRowUpdatedEventArgs Static Methods ■ OracleRowUpdatedEventArgs Properties ■ OracleRowUpdatedEventArgs Public Methods ■ OracleDataAdapter Class on page 4-86 OracleRowUpdatedEventArgs Members 4-252 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatedEventArgs Members OracleRowUpdatedEventArgs members are listed in the following tables: OracleRowUpdatedEventArgs Constructors OracleRowUpdatedEventArgs constructors are listed in Table 4–86. OracleRowUpdatedEventArgs Static Methods The OracleRowUpdatedEventArgs static methods are listed in Table 4–87. OracleRowUpdatedEventArgs Properties The OracleRowUpdatedEventArgs properties are listed in Table 4–88. OracleRowUpdatedEventArgs Public Methods The OracleRowUpdatedEventArgs properties are listed in Table 4–89. Table 4–86 OracleRowUpdatedEventArgs Constructors Constructor Description OracleRowUpdatedEventArgs Constructor Instantiates a new instance of OracleRowUpdatedEventArgs class Table 4–87 OracleRowUpdatedEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–88 OracleRowUpdatedEventArgs Properties Name Description Command Specifies the OracleCommand that is used when OracleDataAdapter.Update() is called Errors Inherited from RowUpdatedEventArgs RecordsAffected Inherited from RowUpdatedEventArgs Row Inherited from RowUpdatedEventArgs StatementType Inherited from RowUpdatedEventArgs Status Inherited from RowUpdatedEventArgs TableMapping Inherited from RowUpdatedEventArgs Table 4–89 OracleRowUpdatedEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object OracleRowUpdatedEventArgs Class Oracle Data Provider for .NET Classes 4-253 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class OracleRowUpdatedEventArgs Constructor 4-254 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatedEventArgs Constructor The OracleRowUpdatedEventArgs constructor creates a new OracleRowUpdatedEventArgs instance. Declaration // C# public OracleRowUpdatedEventArgs(DataRow row,IDbCommand command, StatementType statementType, DataTableMapping tableMapping); Parameters ■ row The DataRow sent for Update. ■ command The IDbCommand executed during the Update. ■ statementType The StatementType Enumeration value indicating the type of SQL statement executed. ■ tableMapping The DataTableMapping used for the Update. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventArgs Members OracleRowUpdatedEventArgs Class Oracle Data Provider for .NET Classes 4-255 OracleRowUpdatedEventArgs Static Methods The OracleRowUpdatedEventArgs static methods are listed in Table 4–90. Table 4–90 OracleRowUpdatedEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventArgs Members OracleRowUpdatedEventArgs Properties 4-256 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatedEventArgs Properties The OracleRowUpdatedEventArgs properties are listed in Table 4–91. Command This property specifies the OracleCommand that is used when OracleDataAdapter.Update() is called. Declaration // C# public new OracleCommand Command {get;} Property Value The OracleCommand executed when Update is called. Table 4–91 OracleRowUpdatedEventArgs Properties Name Description Command Specifies the OracleCommand that is used when OracleDataAdapter.Update() is called Errors Inherited from RowUpdatedEventArgs RecordsAffected Inherited from RowUpdatedEventArgs Row Inherited from RowUpdatedEventArgs StatementType Inherited from RowUpdatedEventArgs Status Inherited from RowUpdatedEventArgs TableMapping Inherited from RowUpdatedEventArgs See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventArgs Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventArgs Members OracleRowUpdatedEventArgs Class Oracle Data Provider for .NET Classes 4-257 OracleRowUpdatedEventArgs Public Methods The OracleRowUpdatedEventArgs properties are listed in Table 4–92. Table 4–92 OracleRowUpdatedEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatedEventArgs Class ■ OracleRowUpdatedEventArgs Members OracleRowUpdatingEventArgs Class 4-258 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatingEventArgs Class The OracleRowUpdatingEventArgs class provides event data for the OracleDataAdapter.RowUpdating event. Class Inheritance Object EventArgs RowUpdatingEventArgs OracleRowUpdatingEventArgs Declaration // C# public sealed class OracleRowUpdatingEventArgs : RowUpdatingEventArgs Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example The example for the RowUpdated event shows how to use OracleRowUpdatingEventArgs. See "Example" on page 4-105. Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Members ■ OracleRowUpdatingEventArgs Constructor ■ OracleRowUpdatingEventArgs Static Methods ■ OracleRowUpdatingEventArgs Properties ■ OracleRowUpdatingEventArgs Public Methods ■ "OracleDataAdapter Class" on page 4-86 OracleRowUpdatingEventArgs Class Oracle Data Provider for .NET Classes 4-259 OracleRowUpdatingEventArgs Members OracleRowUpdatingEventArgs members are listed in the following tables: OracleRowUpdatingEventArgs Constructors OracleRowUpdatingEventArgs constructors are listed in Table 4–93. OracleRowUpdatingEventArgs Static Methods The OracleRowUpdatingEventArgs static methods are listed in Table 4–94. OracleRowUpdatingEventArgs Properties The OracleRowUpdatingEventArgs properties are listed in Table 4–95. OracleRowUpdatingEventArgs Public Methods The OracleRowUpdatingEventArgs public methods are listed in Table 4–96. Table 4–93 OracleRowUpdatingEventArgs Constructors Constructor Description OracleRowUpdatingEventArgs Constructor Instantiates a new instance of OracleRowUpdatingEventArgs class (Overloaded) Table 4–94 OracleRowUpdatingEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–95 OracleRowUpdatingEventArgs Properties Name Description Command Specifies the OracleCommand that is used when the OracleDataAdapter.Update() is called Errors Inherited from RowUpdatingEventArgs Row Inherited from RowUpdatingEventArgs StatementType Inherited from RowUpdatingEventArgs Status Inherited from RowUpdatingEventArgs TableMapping Inherited from RowUpdatingEventArgs Table 4–96 OracleRowUpdatingEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object OracleRowUpdatingEventArgs Members 4-260 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class OracleRowUpdatingEventArgs Class Oracle Data Provider for .NET Classes 4-261 OracleRowUpdatingEventArgs Constructor The OracleRowUpdatingEventArgs constructor creates a new instance of the OracleRowUpdatingEventArgs class using the supplied data row, IDbCommand, type of SQL statement, and table mapping. Declaration // C# public OracleRowUpdatingEventArgs(DataRow row, IDbCommand command, StatementType statementType, DataTableMapping tableMapping); Parameters ■ row The DataRow sent for Update. ■ command The IDbCommand executed during the Update. ■ statementType The StatementType enumeration value indicating the type of SQL statement executed. ■ tableMapping The DataTableMapping used for the Update. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventArgs Members OracleRowUpdatingEventArgs Static Methods 4-262 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatingEventArgs Static Methods The OracleRowUpdatingEventArgs static methods are listed in Table 4–97. Table 4–97 OracleRowUpdatingEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventArgs Members OracleRowUpdatingEventArgs Class Oracle Data Provider for .NET Classes 4-263 OracleRowUpdatingEventArgs Properties The OracleRowUpdatingEventArgs properties are listed in Table 4–98. Command This property specifies the OracleCommand that is used when the OracleDataAdapter.Update() is called. Declaration // C# public new OracleCommand Command {get; set;} Property Value The OracleCommand executed when Update is called. Table 4–98 OracleRowUpdatingEventArgs Properties Name Description Command Specifies the OracleCommand that is used when the OracleDataAdapter.Update() is called Errors Inherited from RowUpdatingEventArgs Row Inherited from RowUpdatingEventArgs StatementType Inherited from RowUpdatingEventArgs Status Inherited from RowUpdatingEventArgs TableMapping Inherited from RowUpdatingEventArgs See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventArgs Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventArgs Members OracleRowUpdatingEventArgs Public Methods 4-264 Oracle Data Provider for .NET Developer’s Guide OracleRowUpdatingEventArgs Public Methods The OracleRowUpdatingEventArgs public methods are listed in Table 4–99. Table 4–99 OracleRowUpdatingEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleRowUpdatingEventArgs Class ■ OracleRowUpdatingEventArgs Members OracleRowUpdatingEventHandler Delegate Oracle Data Provider for .NET Classes 4-265 OracleRowUpdatingEventHandler Delegate The OracleRowUpdatingEventHandler delegate represents the signature of the method that handles the OracleDataAdapter.RowUpdating event. Declaration // C# public delegate void OracleRowUpdatingEventHandler (object sender, OracleRowUpdatingEventArgs eventArgs); Parameters ■ sender The source of the event. ■ eventArgs The OracleRowUpdatingEventArgs object that contains the event data. Remarks Event callbacks can be registered through this event delegate for applications that wish to be notified after a row is updated. In the .NET framework, the convention of an event delegate requires two parameters: the object that raises the event and the event data. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleDataAdapter Class" on page 4-86 OracleTransaction Class 4-266 Oracle Data Provider for .NET Developer’s Guide OracleTransaction Class An OracleTransaction object represents a local transaction. Class Inheritance Object MarshalByRefObject OracleTransaction Declaration // C# public sealed class OracleTransaction : MarshalByRefObject, IDbTransaction, IDisposable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks The application calls BeginTransaction on the OracleConnection object to create an OracleTransaction object. The OracleTransaction object can be created in one of the following two modes: ■ Read Committed (default) ■ Serializable Any other mode results in an exception. The execution of a DDL statement in the context of a transaction is not recommended since it results in an implicit commit that is not reflected in the state of the OracleTransaction object. All operations related to savepoints pertain to the current local transaction. Operations like commit and rollback performed on the transaction have no effect on data in any existing DataSet. Example // Database Setup /* DROP TABLE MyTable; CREATE TABLE MyTable (MyColumn NUMBER); --CREATE TABLE MyTable (MyColumn NUMBER PRIMARY KEY); */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class OracleTransactionSample { static void Main() OracleTransaction Class Oracle Data Provider for .NET Classes 4-267 { // Drop & Create MyTable as indicated above in Database Setup // This sample starts a transaction and inserts two records with the same // value for MyColumn into MyTable. // If MyColumn is not a primary key, the transaction will commit. // If MyColumn is a primary key, the second insert will violate the // unique constraint and the transaction will rollback. string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = con.CreateCommand(); // Check the number of rows in MyTable before transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; int myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Print the number of rows in MyTable Console.WriteLine("myTableCount = " + myTableCount); // Start a transaction OracleTransaction txn = con.BeginTransaction( IsolationLevel.ReadCommitted); try { // Insert the same row twice into MyTable cmd.CommandText = "INSERT INTO MyTable VALUES (1)"; cmd.ExecuteNonQuery(); cmd.ExecuteNonQuery(); // This may throw an exception txn.Commit(); } catch (Exception e) { // Print the exception message Console.WriteLine("e.Message = " + e.Message); // Rollback the transaction txn.Rollback(); } // Check the number of rows in MyTable after transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Prints the number of rows // If MyColumn is not a PRIMARY KEY, the value should increase by two. // If MyColumn is a PRIMARY KEY, the value should remain same. Console.WriteLine("myTableCount = " + myTableCount); txn.Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } OracleTransaction Class 4-268 Oracle Data Provider for .NET Developer’s Guide Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Members ■ OracleTransaction Static Methods ■ OracleTransaction Properties OracleTransaction Class Oracle Data Provider for .NET Classes 4-269 OracleTransaction Members OracleTransaction members are listed in the following tables: OracleTransaction Static Methods OracleTransaction static methods are listed in Table 4–100. OracleTransaction Properties OracleTransaction properties are listed in Table 4–101. OracleTransaction Public Methods OracleTransaction public methods are listed in Table 4–102. Table 4–100 OracleTransaction Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 4–101 OracleTransaction Properties Name Description IsolationLevel Specifies the isolation level for the transaction Connection Specifies the connection that is associated with the transaction Table 4–102 OracleTransaction Public Methods Public Method Description Commit Commits the database transaction CreateObjRef Inherited from MarshalByRefObject Dispose Frees the resources used by the OracleTransaction object Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Rollback Rolls back a database transaction (Overloaded) Save Creates a savepoint within the current transaction ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class OracleTransaction Static Methods 4-270 Oracle Data Provider for .NET Developer’s Guide OracleTransaction Static Methods OracleTransaction static methods are listed in Table 4–103. Table 4–103 OracleTransaction Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Class Oracle Data Provider for .NET Classes 4-271 OracleTransaction Properties OracleTransaction properties are listed in Table 4–104. IsolationLevel This property specifies the isolation level for the transaction. Declaration // C# public IsolationLevel IsolationLevel {get;} Property Value IsolationLevel Implements IDbTransaction Exceptions InvalidOperationException - The transaction has already completed. Remarks Default = IsolationLevel.ReadCommitted Connection This property specifies the connection that is associated with the transaction. Declaration // C# public OracleConnection Connection {get;} Property Value Connection Table 4–104 OracleTransaction Properties Name Description IsolationLevel Specifies the isolation level for the transaction Connection Specifies the connection that is associated with the transaction See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Properties 4-272 Oracle Data Provider for .NET Developer’s Guide Implements IDbTransaction Remarks This property indicates the OracleConnection object that is associated with the transaction. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Class Oracle Data Provider for .NET Classes 4-273 OracleTransaction Public Methods OracleTransaction public methods are listed in Table 4–105. Commit This method commits the database transaction. Declaration // C# public void Commit(); Implements IDbTransaction Exceptions InvalidOperationException - The transaction has already been completed successfully, has been rolled back, or the associated connection is closed. Remarks Upon a successful commit, the transaction enters a completed state. Example // Database Setup /* DROP TABLE MyTable; CREATE TABLE MyTable (MyColumn NUMBER); Table 4–105 OracleTransaction Public Methods Public Method Description Commit Commits the database transaction CreateObjRef Inherited from MarshalByRefObject Dispose Frees the resources used by the OracleTransaction object Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Rollback Rolls back a database transaction (Overloaded) Save Creates a savepoint within the current transaction ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Public Methods 4-274 Oracle Data Provider for .NET Developer’s Guide --CREATE TABLE MyTable (MyColumn NUMBER PRIMARY KEY); */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class CommitSample { static void Main() { // Drop & Create MyTable as indicated above in Database Setup // This sample starts a transaction and inserts two records with the same // value for MyColumn into MyTable. // If MyColumn is not a primary key, the transaction will commit. // If MyColumn is a primary key, the second insert will violate the // unique constraint and the transaction will rollback. string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = con.CreateCommand(); // Check the number of rows in MyTable before transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; int myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Print the number of rows in MyTable Console.WriteLine("myTableCount = " + myTableCount); // Start a transaction OracleTransaction txn = con.BeginTransaction( IsolationLevel.ReadCommitted); try { // Insert the same row twice into MyTable cmd.CommandText = "INSERT INTO MyTable VALUES (1)"; cmd.ExecuteNonQuery(); cmd.ExecuteNonQuery(); // This may throw an exception txn.Commit(); } catch (Exception e) { // Print the exception message Console.WriteLine("e.Message = " + e.Message); // Rollback the transaction txn.Rollback(); } // Check the number of rows in MyTable after transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); OracleTransaction Class Oracle Data Provider for .NET Classes 4-275 // Prints the number of rows // If MyColumn is not a PRIMARY KEY, the value should increase by two. // If MyColumn is a PRIMARY KEY, the value should remain same. Console.WriteLine("myTableCount = " + myTableCount); txn.Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } Dispose This method frees the resources used by the OracleTransaction object. Declaration // C# public void Dispose(); Implements IDisposable Remarks This method releases both the managed and unmanaged resources held by the OracleTransaction object. If the transaction is not in a completed state, an attempt to rollback the transaction is made. Rollback Rollback rolls back a database transaction. Overload List: ■ Rollback() This method rolls back a database transaction. ■ Rollback(string) This method rolls back a database transaction to a savepoint within the current transaction. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Public Methods 4-276 Oracle Data Provider for .NET Developer’s Guide Rollback() This method rolls back a database transaction. Declaration // C# public void Rollback(); Implements IDbTransaction Exceptions InvalidOperationException - The transaction has already been completed successfully, has been rolled back, or the associated connection is closed. Remarks After a Rollback(), the OracleTransaction object can no longer be used because the Rollback ends the transaction. Example // Database Setup /* DROP TABLE MyTable; CREATE TABLE MyTable (MyColumn NUMBER); */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class RollbackSample { static void Main() { // Drop & Create MyTable as indicated above in Database Setup // This sample starts a transaction and inserts one record into MyTable. // It then rollsback the transaction, the number of rows remains the same string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = con.CreateCommand(); // Check the number of rows in MyTable before transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Class Oracle Data Provider for .NET Classes 4-277 int myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Print the number of rows in MyTable Console.WriteLine("myTableCount = " + myTableCount); // Start a transaction OracleTransaction txn = con.BeginTransaction( IsolationLevel.ReadCommitted); // Insert a row into MyTable cmd.CommandText = "INSERT INTO MyTable VALUES (1)"; cmd.ExecuteNonQuery(); // Rollback the transaction txn.Rollback(); // Check the number of rows in MyTable after transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Prints the number of rows, should remain the same Console.WriteLine("myTableCount = " + myTableCount); txn.Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } Rollback(string) This method rolls back a database transaction to a savepoint within the current transaction. Declaration // C# public void Rollback(string savepointName); Parameters ■ savepointName The name of the savepoint to rollback to, in the current transaction. Exceptions InvalidOperationException - The transaction has already been completed successfully, has been rolled back, or the associated connection is closed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Public Methods 4-278 Oracle Data Provider for .NET Developer’s Guide Remarks After a rollback to a savepoint, the current transaction remains active and can be used for further operations. The savepointName specified does not have to match the case of the savepointName created using the Save method, since savepoints are created in the database in a case-insensitive manner. Save This method creates a savepoint within the current transaction. Declaration // C# public void Save(string savepointName); Parameters ■ savepointName The name of the savepoint being created in the current transaction. Exceptions InvalidOperationException - The transaction has already been completed. Remarks After creating a savepoint, the transaction does not enter a completed state and can be used for further operations. The savepointName specified is created in the database in a case-insensitive manner. Calling the Rollback method rolls back to savepointName. This allows portions of a transaction to be rolled back, instead of the entire transaction. Example // Database Setup /* DROP TABLE MyTable; CREATE TABLE MyTable (MyColumn NUMBER); */ // C# using System; using System.Data; using Oracle.DataAccess.Client; class SaveSample { static void Main() { // Drop & Create MyTable as indicated above in Database Setup See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleTransaction Class Oracle Data Provider for .NET Classes 4-279 // This sample starts a transaction and creates a savepoint after // inserting one record into MyTable. // After inserting the second record it rollsback to the savepoint // and commits the transaction. Only the first record will be inserted string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleCommand cmd = con.CreateCommand(); // Check the number of rows in MyTable before transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; int myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Print the number of rows in MyTable Console.WriteLine("myTableCount = " + myTableCount); // Start a transaction OracleTransaction txn = con.BeginTransaction( IsolationLevel.ReadCommitted); // Insert a row into MyTable cmd.CommandText = "INSERT INTO MyTable VALUES (1)"; cmd.ExecuteNonQuery(); // Create a savepoint txn.Save("MySavePoint"); // Insert another row into MyTable cmd.CommandText = "insert into mytable values (2)"; cmd.ExecuteNonQuery(); // Rollback to the savepoint txn.Rollback("MySavePoint"); // Commit the transaction txn.Commit(); // Check the number of rows in MyTable after transaction cmd.CommandText = "SELECT COUNT(*) FROM MyTable"; myTableCount = int.Parse(cmd.ExecuteScalar().ToString()); // Prints the number of rows, should have increased by 1 Console.WriteLine("myTableCount = " + myTableCount); txn.Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } OracleTransaction Public Methods 4-280 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleTransaction Class ■ OracleTransaction Members OracleCollectionType Enumeration Oracle Data Provider for .NET Classes 4-281 OracleCollectionType Enumeration OracleCollectionType enumerated values specify whether the OracleParameter object represents a collection, and if so, specifies the collection type. Table 4–106 lists all the OracleCollectionType enumeration values with a description of each enumerated value. Table 4–106 OracleCollectionType Enumeration Values Member Name Description None Is not a collection type PLSQLAssociativeArray Indicates that the collection type is a PL/SQL Associative Array (or PL/SQL Index-By Table) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleParameter Class" on page 4-194 ■ "CollectionType" on page 4-213 OracleDbType Enumeration 4-282 Oracle Data Provider for .NET Developer’s Guide OracleDbType Enumeration OracleDbType enumerated values are used to explicitly specify the OracleDbType of an OracleParameter. Table 4–107 lists all the OracleDbType enumeration values with a description of each enumerated value. Table 4–107 OracleDbType Enumeration Values Member Name Description BFile Oracle BFILE type Blob Oracle BLOB type Byte byte type Char Oracle CHAR type Clob Oracle CLOB type Date Oracle DATE type Decimal Oracle NUMBER type Double 8-byte FLOAT type Int16 2-byte INTEGER type Int32 4-byte INTEGER type Int64 8-byte INTEGER type IntervalDS Oracle INTERVAL DAY TO SECOND type IntervalYM Oracle INTERVAL YEAR TO MONTH type Long Oracle LONG type LongRaw Oracle LONG RAW type NChar Oracle NCHAR type NClob Oracle NCLOB type NVarchar2 Oracle NVARCHAR2 type Raw Oracle RAW type RefCursor Oracle REF CURSOR type Single 4-byte FLOAT type TimeStamp Oracle TIMESTAMP type TimeStampLTZ Oracle TIMESTAMP WITH LOCAL TIME ZONE type TimeStampTZ Oracle TIMESTAMP WITH TIME ZONE type Varchar2 Oracle VARCHAR2 type XmlType Oracle XMLType type OracleDbType Enumeration Oracle Data Provider for .NET Classes 4-283 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleParameter Class" on page 4-194 ■ "OracleParameterCollection Class" on page 4-225 ■ OracleParameter "OracleDbType" on page 4-215 OracleParameterStatus Enumeration 4-284 Oracle Data Provider for .NET Developer’s Guide OracleParameterStatus Enumeration The OracleParameterStatus enumeration type indicates whether a NULL value 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. Table 4–108 lists all the OracleParameterStatus enumeration values with a description of each enumerated value. Table 4–108 OracleParameterStatus Members Member Name Description Success Indicates that (for input parameters) the input value has been assigned to the column. For output parameter, it indicates that the provider assigned an intact value to the parameter. NullFetched Indicates that a NULL value has been fetched from a column or an OUT parameter NullInsert Indicates that a NULL value is to be inserted into a column Truncation Indicates that truncation has occurred when fetching the data from the column See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ "OracleParameter Class" on page 4-194 ■ OracleParameter "ArrayBindStatus" on page 4-212 ■ OracleParameter "Value" on page 4-221 Oracle Data Provider for .NET XML-Related Classes 5-1 5 Oracle Data Provider for .NET XML-Related Classes This chapter describes ODP.NET XML-related classes and enumerations. This chapter contains these topics: ■ OracleXmlCommandType Enumeration ■ OracleXmlQueryProperties Class ■ OracleXmlSaveProperties Class ■ OracleXmlStream Class ■ OracleXmlType Class All offsets are 0-based for OracleXmlStream object parameters. OracleXmlCommandType Enumeration 5-2 Oracle Data Provider for .NET Developer’s Guide OracleXmlCommandType Enumeration The OracleXmlCommandType enumeration specifies the values that are allowed for the XmlCommandType property of the OracleCommand class. It is used to specify the type of XML operation. Table 5–1 lists all the OracleXmlCommandType enumeration values with a description of each enumerated value. Table 5–1 OracleXmlCommandType Members Member Name Description None No XML operation is desired Query The command text is a SQL query and the result of the query is an XML document. The SQL query needs to be a select statement Insert The command text is an XML document containing rows to insert. Update The command text is an XML document containing rows to update. Delete The command text is an XML document containing rows to delete. See Also: "Oracle.DataAccess.Client Namespace" on page 1-1 OracleXmlQueryProperties Class Oracle Data Provider for .NET XML-Related Classes 5-3 OracleXmlQueryProperties Class An OracleXmlQueryProperties object represents the XML properties used by the OracleCommand class when the XmlCommandType property is Query. Class Inheritance Object OracleXmlQueryProperties Declaration public sealed class OracleXmlQueryProperties : ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleXmlQueryProperties can be accessed, and modified using the XmlQueryProperties property of the OracleCommand class. Each OracleCommand object has its own instance of the OracleXmlQueryProperties class in the XmlQueryProperties property. Use the default constructor to get a new instance of the OracleXmlQueryProperties. Use the OracleXmlQueryProperties.Clone() method to get a copy of an OracleXmlQueryProperties instance. Example This example retrieves relational data as XML. // C# using System; using Oracle.DataAccess.Client; class OracleXmlSavePropertiesSample { static void Main() { string[] KeyColumnsList = null; string[] UpdateColumnsList = null; int rows = 0; // Create the connection. string constr = "User Id=hr;Password=hr;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create the command. OracleCommand cmd = new OracleCommand("", con); // Set the XML command type to insert. cmd.XmlCommandType = OracleXmlCommandType.Insert; // Set the XML document. OracleXmlQueryProperties Class 5-4 Oracle Data Provider for .NET Developer’s Guide cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " Smith\n" + " Smith@Oracle.com\n" + " 1982-01-23T00:00:00.000\n" + " IT_PROG\n" + " \n" + " \n" + " 1235\n" + " Barney\n" + " Barney@Oracle.com\n" + " 1982-01-23T00:00:00.000\n" + " IT_PROG\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList = new string[5]; UpdateColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList[1] = "LAST_NAME"; UpdateColumnsList[2] = "EMAIL"; UpdateColumnsList[3] = "HIRE_DATE"; UpdateColumnsList[4] = "JOB_ID"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.RowTag = "MYROW"; cmd.XmlSaveProperties.Table = "employees"; cmd.XmlSaveProperties.UpdateColumnsList = UpdateColumnsList; cmd.XmlSaveProperties.Xslt = null; cmd.XmlSaveProperties.XsltParams = null; // Do the inserts. rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); // Set the XML command type to update. cmd.XmlCommandType = OracleXmlCommandType.Update; // Set the XML document. cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " Adams\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList = new string[1]; UpdateColumnsList[0] = "LAST_NAME"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.UpdateColumnsList = UpdateColumnsList; rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); OracleXmlQueryProperties Class Oracle Data Provider for .NET XML-Related Classes 5-5 // Set the XML command type to delete. cmd.XmlCommandType = OracleXmlCommandType.Delete; // Set the XML document. cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " \n" + " \n" + " 1235\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.UpdateColumnsList = null; // Do the deletes. rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); // Clean up. cmd.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Members ■ OracleXmlQueryProperties Constructor ■ OracleXmlQueryProperties Properties ■ OracleXmlQueryProperties Public Methods OracleXmlQueryProperties Members 5-6 Oracle Data Provider for .NET Developer’s Guide OracleXmlQueryProperties Members OracleXmlQueryProperties members are listed in the following tables: OracleXmlQueryProperties Constructors The OracleXmlQueryProperties constructors are listed in Table 5–2. OracleXmlQueryProperties Properties The OracleXmlQueryProperties properties are listed in Table 5–3. OracleXmlQueryProperties Public Methods The OracleXmlQueryProperties public methods are listed in Table 5–4. Table 5–2 OracleXmlQueryProperties Constructors Constructor Description OracleXmlQueryProperties Constructor Instantiates a new instance of the OracleXmlQueryProperties class Table 5–3 OracleXmlQueryProperties Properties Name Description MaxRows Specifies the maximum number of rows from the result set of the query that can be represented in the result XML document RootTag Specifies the root element of the result XML document RowTag Specifies the value of the XML element which identifies a row of data from the result set in an XML document Xslt Specifies the XSL document used for XML transformation using XSLT XsltParams Specifies parameters for the XSL document Table 5–4 OracleXmlQueryProperties Public Methods Name Description Clone Creates a copy of an OracleXmlQueryProperties object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class OracleXmlQueryProperties Class Oracle Data Provider for .NET XML-Related Classes 5-7 OracleXmlQueryProperties Constructor The OracleXmlQueryProperties constructor instantiates a new instance of the OracleXmlQueryProperties class. Declaration // C# public OracleXmlQueryProperties(); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members OracleXmlQueryProperties Properties 5-8 Oracle Data Provider for .NET Developer’s Guide OracleXmlQueryProperties Properties The OracleXmlQueryProperties properties are listed in Table 5–5. MaxRows This property specifies the maximum number of rows from the result set of the query that can be represented in the result XML document. Declaration // C# public int MaxRows {get; set;} Property Value The maximum number of rows. Exceptions ArgumentException - The new value for MaxRows is not valid. Remarks Default value is -1. Possible values are: ■ -1 (all rows). ■ A number greater than or equal to 0. Table 5–5 OracleXmlQueryProperties Properties Name Description MaxRows Specifies the maximum number of rows from the result set of the query that can be represented in the result XML document RootTag Specifies the root element of the result XML document RowTag Specifies the value of the XML element which identifies a row of data from the result set in an XML document Xslt Specifies the XSL document used for XML transformation using XSLT XsltParams Specifies parameters for the XSL document See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members OracleXmlQueryProperties Class Oracle Data Provider for .NET XML-Related Classes 5-9 RootTag This property specifies the root element of the result XML document. Declaration // C# public string RootTag {get; set;} Property Value The root element of the result XML document. Remarks The default root tag is ROWSET. To indicate that no root tag is be used in the result XML document, set this property to null or "" or String.Empty. If both RootTag and RowTag are set to null, an XML document is returned only if the result set returns one row and one column. RowTag This property specifies the value of the XML element which identifies a row of data from the result set in an XML document. Declaration // C# public string RowTag {get; set;} Property Value The value of the XML element. Remarks The default is ROW. To indicate that no row tag is be used in the result XML document, set this property to null or "" or String.Empty. If both RootTag and RowTag are set to null, an XML document is returned only if the result set returns one row and one column. Xslt This property specifies the XSL document used for XML transformation using XSLT. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members OracleXmlQueryProperties Properties 5-10 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public string Xslt {get; set;} Property Value The XSL document used for XML transformation. Remarks Default value is null. The XSL document is used for XML transformation of the XML document generated from the result set of the query. XsltParams This property specifies parameters for the XSL document. Declaration // C# public string XsltParams {get; set;} Property Value The parameters for the XSL document. Remarks Default value is null. The parameters are specified as a string of "name=value" pairs of the form "param1=value1; param2=value2; …" delimited by semicolons. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members OracleXmlQueryProperties Class Oracle Data Provider for .NET XML-Related Classes 5-11 OracleXmlQueryProperties Public Methods The OracleXmlQueryProperties public methods are listed in Table 5–6. Clone This method creates a copy of an OracleXmlQueryProperties object. Declaration // C# public object Clone(); Return Value An OracleXmlQueryProperties object Implements ICloneable Table 5–6 OracleXmlQueryProperties Public Methods Name Description Clone Creates a copy of an OracleXmlQueryProperties object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlQueryProperties Class ■ OracleXmlQueryProperties Members OracleXmlSaveProperties Class 5-12 Oracle Data Provider for .NET Developer’s Guide OracleXmlSaveProperties Class An OracleXmlSaveProperties object represents the XML properties used by the OracleCommand class when the XmlCommandType property is Insert, Update, or Delete. Class Inheritance Object OracleXmlSaveProperties Declaration public sealed class OracleXmlSaveProperties : ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleXmlSaveProperties can be accessed and modified using the XmlSaveProperties property of the OracleCommand class. Each OracleCommand object has its own instance of the OracleXmlSaveProperties class in the XmlSaveProperties property. Use the default constructor to get a new instance of OracleXmlSaveProperties. Use the OracleXmlSaveProperties.Clone() method to get a copy of an OracleXmlSaveProperties instance. Example This sample demonstrates how to do inserts, updates, and deletes to a relational table or view using an XML document. // C# using System; using Oracle.DataAccess.Client; class OracleXmlSavePropertiesSample { static void Main() { string[] KeyColumnsList = null; string[] UpdateColumnsList = null; int rows = 0; // Create the connection. string constr = "User Id=hr;Password=hr;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create the command. OracleCommand cmd = new OracleCommand("", con); // Set the XML command type to insert. OracleXmlSaveProperties Class Oracle Data Provider for .NET XML-Related Classes 5-13 cmd.XmlCommandType = OracleXmlCommandType.Insert; // Set the XML document. cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " Smith\n" + " Smith@Oracle.com\n" + " 1982-01-23T00:00:00.000\n" + " IT_PROG\n" + " \n" + " \n" + " 1235\n" + " Barney\n" + " Barney@Oracle.com\n" + " 1982-01-23T00:00:00.000\n" + " IT_PROG\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList = new string[5]; UpdateColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList[1] = "LAST_NAME"; UpdateColumnsList[2] = "EMAIL"; UpdateColumnsList[3] = "HIRE_DATE"; UpdateColumnsList[4] = "JOB_ID"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.RowTag = "MYROW"; cmd.XmlSaveProperties.Table = "employees"; cmd.XmlSaveProperties.UpdateColumnsList = UpdateColumnsList; cmd.XmlSaveProperties.Xslt = null; cmd.XmlSaveProperties.XsltParams = null; // Do the inserts. rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); // Set the XML command type to update. cmd.XmlCommandType = OracleXmlCommandType.Update; // Set the XML document. cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " Adams\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; UpdateColumnsList = new string[1]; UpdateColumnsList[0] = "LAST_NAME"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.UpdateColumnsList = UpdateColumnsList; OracleXmlSaveProperties Class 5-14 Oracle Data Provider for .NET Developer’s Guide rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); // Set the XML command type to delete. cmd.XmlCommandType = OracleXmlCommandType.Delete; // Set the XML document. cmd.CommandText = "\n" + "\n" + " \n" + " 1234\n" + " \n" + " \n" + " 1235\n" + " \n" + "\n"; // Set the XML save properties. KeyColumnsList = new string[1]; KeyColumnsList[0] = "EMPLOYEE_ID"; cmd.XmlSaveProperties.KeyColumnsList = KeyColumnsList; cmd.XmlSaveProperties.UpdateColumnsList = null; // Do the deletes. rows = cmd.ExecuteNonQuery(); Console.WriteLine("rows: " + rows); // Clean up. cmd.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Members ■ OracleXmlSaveProperties Constructor ■ OracleXmlSaveProperties Properties ■ OracleXmlSaveProperties Public Methods OracleXmlSaveProperties Class Oracle Data Provider for .NET XML-Related Classes 5-15 OracleXmlSaveProperties Members OracleXmlSaveProperties members are listed in the following tables: OracleXmlSaveProperties Constructor OracleXmlSaveProperties constructors are listed in Table 5–7 OracleXmlSaveProperties Properties The OracleXmlSaveProperties properties are listed in Table 5–8. OracleXmlSaveProperties Public Methods The OracleXmlSaveProperties public methods are listed in Table 5–9. Table 5–7 OracleXmlSaveProperties Constructor Constructor Description OracleXmlSaveProperties Constructor Instantiates a new instance of the OracleXmlSaveProperties class Table 5–8 OracleXmlSaveProperties Properties Name Description KeyColumnsList Specifies the list of columns used as a key to locate existing rows for update or delete using an XML document RowTag Specifies the value for the XML element that identifies a row of data in an XML document Table Specifies the name of the table or view to which changes are saved UpdateColumnsList Specifies the list of columns to update or insert Xslt Specifies the XSL document used for XML transformation using XSLT XsltParams Specifies the parameters for the XSLT document specified in the Xslt property Table 5–9 OracleXmlSaveProperties Public Methods Name Description Clone Creates a copy of an OracleXmlSaveProperties object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Constructor 5-16 Oracle Data Provider for .NET Developer’s Guide OracleXmlSaveProperties Constructor The OracleXmlSaveProperties constructor instantiates a new instance of OracleXmlSaveProperties class. Declaration // C# public OracleXmlSaveProperties; See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Class Oracle Data Provider for .NET XML-Related Classes 5-17 OracleXmlSaveProperties Properties The OracleXmlSaveProperties properties are listed in Table 5–10. KeyColumnsList This property specifies the list of columns used as a key to locate existing rows for update or delete using an XML document. Declaration // C# public string[] KeyColumnsList {get; set;} Property Value The list of columns. Remarks Default value is null. The first null value (if any) terminates the list. KeyColumnsList usage with XMLCommandType property values: ■ Insert - KeyColumnsList is ignored and can be null. ■ Update - KeyColumnsList must be specified; it identifies the columns to use to find the rows to be updated. ■ Delete - If KeyColumnsList is null, all the column values in each row element in the XML document are used to locate the rows to delete. Otherwise, KeyColumnsList specifies the columns used to identify the rows to delete. Table 5–10 OracleXmlSaveProperties Properties Name Description KeyColumnsList Specifies the list of columns used as a key to locate existing rows for update or delete using an XML document RowTag Specifies the value for the XML element that identifies a row of data in an XML document Table Specifies the name of the table or view to which changes are saved UpdateColumnsList Specifies the list of columns to update or insert Xslt Specifies the XSL document used for XML transformation using XSLT XsltParams Specifies the parameters for the XSLT document specified in the Xslt property See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Properties 5-18 Oracle Data Provider for .NET Developer’s Guide RowTag This property specifies the value for the XML element that identifies a row of data in an XML document. Declaration // C# public string RowTag {get; set;} Property Value An XML element name. Remarks The default value is ROW. Each element in the XML document identifies one row in a table or view. If RowTag is set to "" or null, no row tag is used in the XML document. In this case, the XML document is assumed to contain only one row. Table This property specifies the name of the table or view to which changes are saved. Declaration // C# public string Table {get; set;} Property Value A table name. Remarks Default value is null. The property must be set to a valid table or view name. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Class Oracle Data Provider for .NET XML-Related Classes 5-19 UpdateColumnsList This property specifies the list of columns to update or insert. Declaration // C# public string[] UpdateColumnsList {get; set;} Property Value A list of columns. Remarks Default value is null. The first null value (if any) terminates the list. UpdateColumnList usage with XMLCommandType property values: ■ Insert - UpdateColumnList indicates which columns are assigned values when a new row is created. If UpdateColumnList is null, then all columns are assigned values. If a column is on the UpdateColumnList, but no value is specified for the row in the XML file, then NULL is used. If a column is not on the UpdateColumnList, then the default value for that column is used. ■ Update - UpdateColumnList specifies columns to modify for each row of data in the XML document. If UpdateColumnList is null, all the values in each XML element in the XML document are used to modify the columns. ■ Delete - UpdateColumnsList is ignored and can be null. Xslt This property specifies the XSL document used for XML transformation using XSLT. Declaration // C# public string Xslt {get; set;} Property Value The XSL document used for XML transformation. Remarks Default = null. The XSL document is used for XSLT transformation of a given XML document. The transformed XML document is used to save changes to the table or view. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Properties 5-20 Oracle Data Provider for .NET Developer’s Guide XsltParams This property specifies the parameters for the XSLT document specified in the Xslt property. Declaration // C# public string XsltParams {get; set;} Property Value The parameters for the XSLT document . Remarks Default is null. This property is a string delimited by semicolons in "name=value" pairs of the form "param1=value1; param2=value2; …". See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlSaveProperties Class Oracle Data Provider for .NET XML-Related Classes 5-21 OracleXmlSaveProperties Public Methods The OracleXmlSaveProperties public methods are listed in Table 5–11. Clone This method creates a copy of an OracleXmlSaveProperties object. Declaration // C# public object Clone(); Return Value An OracleXmlSaveProperties object Implements ICloneable Table 5–11 OracleXmlSaveProperties Public Methods Name Description Clone Creates a copy of an OracleXmlSaveProperties object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleXmlSaveProperties Class ■ OracleXmlSaveProperties Members OracleXmlStream Class 5-22 Oracle Data Provider for .NET Developer’s Guide OracleXmlStream Class An OracleXmlStream object represents a read-only stream of XML data stored in an OracleXmlType object. Class Inheritance Object MarshalByRefObject Stream OracleXmlStream Declaration // C# public sealed class OracleXmlStream : IDisposable, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll This class can only be used with Oracle9i Release 2 (9.2) and later. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Members ■ OracleXmlStream Constructor ■ OracleXmlStream Static Methods ■ OracleXmlStream Instance Properties ■ OracleXmlStream Instance Methods OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-23 OracleXmlStream Members OracleXmlStream members are listed in the following tables: OracleXmlStream Constructors The OracleXmlStream constructors are listed in Table 5–12. OracleXmlStream Static Methods The OracleXmlStream static methods are listed in Table 5–13. OracleXmlStream Instance Properties The OracleXmlStream instance properties are listed in Table 5–14. OracleXmlStream Instance Methods The OracleXmlStream instance methods are listed in Table 5–15. Table 5–12 OracleXmlStream Constructors Constructor Description OracleXmlStream Constructor Creates an instance of an OracleXmlStream object which provides a Stream representation of the XML data stored in an OracleXmlType Table 5–13 OracleXmlStream Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 5–14 OracleXmlStream Instance Properties Properties Description CanRead Indicates whether the XML stream can be read CanSeek Indicates whether forward and backward seek operation can be performed CanWrite Not Supported Connection Indicates the OracleConnection that is used to retrieve the XML data Length Indicates the number of bytes in the XML stream Position Gets or sets the byte position within the stream Value Returns the XML data, starting from the first character in the stream as a string Table 5–15 OracleXmlStream Instance Methods Methods Description BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleXmlStream object Close Closes the current stream and releases any resources associated with it OracleXmlStream Members 5-24 Oracle Data Provider for .NET Developer’s Guide Dispose Releases resources allocated by this object EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object Flush Not Supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Read Reads a specified amount from the current stream instance and populates the array buffer (Overloaded) ReadByte Inherited from Stream Seek Sets the position within the current stream and returns the new position within the current stream SetLength Not Supported ToString Inherited from Object Write Not Supported WriteByte Not Supported See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class Table 5–15 (Cont.) OracleXmlStream Instance Methods Methods Description OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-25 OracleXmlStream Constructor This constructor creates an instance of an OracleXmlStream object which provides a Stream representation of the XML data stored in an OracleXmlType object. Declaration // C# public OracleXmlStream(OracleXmlType xmlType); Parameters ■ xmlType The OracleXmlType object. Remarks The OracleXmlStream implicitly uses the OracleConnection object from the OracleXmlType object from which it was constructed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Static Methods 5-26 Oracle Data Provider for .NET Developer’s Guide OracleXmlStream Static Methods The OracleXmlStream static methods are listed in Table 5–16. Table 5–16 OracleXmlStream Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-27 OracleXmlStream Instance Properties The OracleXmlStream instance properties are listed in Table 5–17. CanRead Overrides Stream This property indicates whether the XML stream can be read. Declaration // C# public override bool CanRead{get;} Property Value If the XML stream is can be read, returns true; otherwise, returns false. CanSeek Overrides Stream This property indicates whether forward and backward seek operation can be performed. Declaration // C# Table 5–17 OracleXmlStream Instance Properties Properties Description CanRead Indicates whether the XML stream can be read CanSeek Indicates whether forward and backward seek operation can be performed CanWrite Not Supported Connection Indicates the OracleConnection that is used to retrieve the XML data Length Indicates the number of bytes in the XML stream Position Gets or sets the byte position within the stream Value Returns the XML data, starting from the first character in the stream as a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Instance Properties 5-28 Oracle Data Provider for .NET Developer’s Guide public override bool CanSeek{get;} Property Value If forward and backward seek operations can be performed, this property returns true. Otherwise, returns false. Connection This instance property indicates the OracleConnection that is used to retrieve the XML data. Declaration // C# public OracleConnection Connection {get;} Property Value An OracleConnection. Exceptions ObjectDisposedException - The object is already disposed. Length Overrides Stream This property indicates the number of bytes in the XML stream. Declaration // C# public override Int64 Length{get;} Property Value An Int64 value representing the number of bytes in the XML stream. An empty stream has a length of 0 bytes. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-29 Position Overrides Stream This property gets or sets the byte position within the stream. Declaration // C# public override Int64 Position{get; set;} Property Value An Int64 that indicates the current position in the stream. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The Position is less than 0. Remarks The beginning of the stream is represented by position 0. Seeking to any location beyond the length of the stream is supported. Value This property returns the XML data, starting from the first character of the stream as a string. Declaration // C# public string Value{get; set;} Property Value A string. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Instance Properties 5-30 Oracle Data Provider for .NET Developer’s Guide Remarks The value of Position is neither used nor changed by using this property. The maximum length of the string that can be returned by this property is 2 GB. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-31 OracleXmlStream Instance Methods The OracleXmlStream instance methods are listed in Table 5–18. Clone This method creates a copy of an OracleXmlStream object. Declaration // C# public object Clone(); Table 5–18 OracleXmlStream Instance Methods Methods Description BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleXmlStream object Close Closes the current stream and releases any resources associated with it Dispose Releases resources allocated by this object EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object Flush Not Supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject Read Reads a specified amount from the current XML stream instance and populates the array buffer (Overloaded) ReadByte Inherited from Stream Seek Sets the position within the current stream and returns the new position within the current stream SetLength Not Supported ToString Inherited from Object Write Not Supported WriteByte Not Supported See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Instance Methods 5-32 Oracle Data Provider for .NET Developer’s Guide Return Value An OracleXmlStream object. Implements ICloneable Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The cloned object has the same property values as that of the object being cloned. Close Overrides Stream This method closes the current stream and releases any resources associated with it. Declaration // C# public override void Close(); Dispose This public method releases resources allocated by this object. Declaration // C# public void Dispose(); Implements IDisposable Remarks The object cannot be reused after being disposed. Although some properties can still be accessed, their values cannot be accountable. Since resources are freed, method calls can lead to exceptions. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-33 Read This method reads a specified amount from the current XML stream instance and populates the array buffer. Overload List: ■ Read(byte[ ], int, int) This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, and populates the byte array buffer. ■ Read(char[ ], int, int) This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer. Read(byte[ ], int, int) Overrides Stream This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, and populates the byte array buffer. Declaration // C# public override int Read(byte[ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer that is populated. ■ offset The zero-based offset (in bytes) at which the buffer is populated. ■ count The maximum amount of bytes to be read. Return Value The number of unicode bytes read into the given byte[] buffer or 0 if the end of the stream has been reached. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Instance Methods 5-34 Oracle Data Provider for .NET Developer’s Guide Remarks This method reads a maximum of count bytes from the current stream and stores them in buffer beginning at offset. The current position within the stream is advanced by the number of bytes read. However, if an exception occurs, the current position within the stream remains unchanged. The XML data is read starting from the position specified by the Position property. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Read(char[ ], int, int) Overrides Stream This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer. Declaration // C# public override int Read(char[ ] buffer, int offset, int count); Parameters ■ buffer The character array buffer to be populated. ■ offset The zero-based offset (in characters) in the buffer at which the buffer is populated. ■ count The maximum amount of characters to be read from the stream. Return Value The return value indicates the number of characters read from the stream or 0 if the end of the stream has been reached. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks This method requires that the Position on the stream instance be zero or an even number. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlStream Class Oracle Data Provider for .NET XML-Related Classes 5-35 The XML data is read starting from the position specified by the Position property. Seek Overrides Stream. This method sets the position within the current stream and returns the new position within the current stream. Declaration // C# public long Seek(long offset, SeekOrigin origin); Parameters ■ offset A byte offset relative to origin. ■ If offset is negative, the new position precedes the position specified by origin by the number of bytes specified by offset. ■ If offset is zero, the new position is the position specified by origin. ■ If offset is positive, the new position follows the position specified by origin by the number of bytes specified by offset. ■ origin A value of type SeekOrigin indicating the reference point used to obtain the new position. Return Value The new Position within the current stream. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object Remarks Use the CanSeek property to determine whether the current instance supports seeking. Seeking to any location beyond the length of the stream is supported. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlStream Class ■ OracleXmlStream Members OracleXmlType Class 5-36 Oracle Data Provider for .NET Developer’s Guide OracleXmlType Class An OracleXmlType object represents an Oracle XMLType instance. Class Inheritance Object OracleXmlType Declaration // C# public sealed class OracleXmlType : IDisposable, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleXmlType objects can be used for well-formed XML documents with or without XML schemas or XML fragments. Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll This class can only be used with Oracle9i Release 2 (9.2) or higher. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Members ■ OracleXmlType Constructors ■ OracleXmlType Static Methods ■ OracleXmlType Instance Properties ■ OracleXmlType Instance Methods OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-37 OracleXmlType Members OracleXmlType members are listed in the following tables: OracleXmlType Constructors The OracleXmlType constructors are listed in Table 5–19. OracleXmlType Static Methods The OracleXmlType static methods are listed in Table 5–20. OracleXmlType Instance Properties The OracleXmlType instance properties are listed in Table 5–21. OracleXmlType Instance Methods The OracleXmlType instance methods are listed in Table 5–22. Table 5–19 OracleXmlType Constructors Constructor Description OracleXmlType Constructors Creates an instance of the OracleXmlType class (Overloaded) Table 5–20 OracleXmlType Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 5–21 OracleXmlType Instance Properties Properties Description Connection Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType IsEmpty Indicates whether or not the OracleXmlType is empty IsFragment Indicates whether the XML data is a collection of XML elements or a well-formed XML document IsSchemaBased Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema RootElement Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType Schema Represents the XML schema of the XML data contained in the OracleXmlType SchemaUrl Represents in the database for the XML schema of the XML data contained in the OracleXmlType. Value Returns the XML data starting from the first character in the current instance as a string Table 5–22 OracleXmlType Instance Methods Methods Description Clone Creates a copy of the OracleXmlType instance Dispose Releases the resources allocated by this OracleXmlType object OracleXmlType Members 5-38 Oracle Data Provider for .NET Developer’s Guide Equals Inherited from Object Extract Extracts a subset from the XML data using the given XPath expression (Overloaded) GetHashCode Inherited from Object GetStream Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance GetType Inherited from Object GetXmlDocument Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance GetXmlReader Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods IsExists Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) ToString Inherited from Object Transform Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) Update Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) Validate Validates whether the XML data in the OracleXmlType object conforms to the given XML schema. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class Table 5–22 (Cont.) OracleXmlType Instance Methods Methods Description OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-39 OracleXmlType Constructors OracleXmlType constructors create instances of the OracleXmlType class. Overload List: ■ OracleXmlType(OracleClob) This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object. ■ OracleXmlType(OracleConnection, string) This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String. ■ OracleXmlType(OracleConnection, XmlReader) This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object. ■ OracleXmlType(OracleConnection, XmlDocument) This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object. OracleXmlType(OracleClob) This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object. Declaration // C# public OracleXmlType(OracleClob oraClob); Parameters ■ oraClob An OracleClob object. Exceptions ArgumentNullException - The OracleClob object is null. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The CLOB data depends on a valid connection object and the new OracleXMLType uses the OracleConnection in the OracleClob object to store data for the current instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Constructors 5-40 Oracle Data Provider for .NET Developer’s Guide OracleXmlType(OracleConnection, string) This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String. Declaration // C# public OracleXmlType(OracleConnection con, string xmlData); Parameters ■ con An OracleConnection object. ■ xmlData A string containing the XML data. Exceptions ArgumentNullException - The OracleConnection object is null. ArgumentException - The xmlData argument is an empty string. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The new OracleXmlType uses the given OracleConnection object to store data for the current instance. OracleXmlType(OracleConnection, XmlReader) This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object. Declaration // C# public OracleXmlType(OracleConnection con, XmlReader reader); Parameters ■ con An OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-41 ■ reader An XmlReader object. Exceptions ArgumentNullException - The OracleConnection object is null. ArgumentException - The reader argument contains no data. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The new OracleXMLType uses the given OracleConnection object to store data for the current instance. OracleXmlType(OracleConnection, XmlDocument) This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object. Declaration // C# public OracleXmlType(OracleConnection con, XmlDocument domDoc); Parameters ■ con An OracleConnection object. ■ domDoc An XML document. Exceptions ArgumentNullException - The OracleConnection object is null. ArgumentException - The domDoc argument contains no data. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The new OracleXMLType uses the given OracleConnection object to store data for the current instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Static Methods 5-42 Oracle Data Provider for .NET Developer’s Guide OracleXmlType Static Methods The OracleXmlType static methods are listed in Table 5–23. Table 5–23 OracleXmlType Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-43 OracleXmlType Instance Properties The OracleXmlType instance properties are listed in Table 5–24. Connection This property indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType. Declaration // C# public OracleConnection Connection {get;} Property Value An OracleConnection object. Exceptions ObjectDisposedException - The object is already disposed. Remarks The connection must explicitly be opened by the user before creating or using OracleXmlType. Table 5–24 OracleXmlType Instance Properties Properties Description Connection Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType IsEmpty Indicates whether or not the OracleXmlType is empty IsFragment Indicates whether the XML data is a collection of XML elements or a well-formed XML document IsSchemaBased Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema RootElement Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType Schema Represents the XML schema of the XML data contained in the OracleXmlType SchemaUrl Represents URL in the database for the XML schema of the XML data contained in the OracleXmlType Value Returns the XML data starting from the first character in the current instance as a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Properties 5-44 Oracle Data Provider for .NET Developer’s Guide IsEmpty This property indicates whether or not the OracleXmlType is empty. Declaration // C# public bool IsEmpty {get;} Property Value Returns true if the OracleXmlType represents an empty XML document. Returns false otherwise. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. IsFragment This property indicates whether the XML data is a collection of XML elements or a well-formed XML document. Declaration // C# public bool IsFragment {get;} Property Value Returns true if the XML data contained in the OracleXmlType object is a collection of XML elements with no root element. Returns false otherwise. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-45 IsSchemaBased This property indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema. Declaration // C# public bool IsSchemaBased {get;} Property Value Returns true if the XML data represented by the OracleXmlType is based on an XML schema. Returns false otherwise. Exceptions ObjectDisposedException - The object is already disposed. RootElement This property represents the name of the top-level or root element of the schema-based XML data contained in the OracleXmlType. Declaration // C# public string RootElement{get;} Property Value A string that represents the name of the top-level or root element of the XML data contained in the OracleXmlType. Exceptions ObjectDisposedException - The object is already disposed. Remarks If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string. Schema This property represents the XML schema for the XML data contained in the OracleXmlType. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Properties 5-46 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public OracleXmlType Schema {get;} Property Value An OracleXmlType instance that represents the XML schema for the XML data contained in the OracleXmlType. Exceptions ObjectDisposedException - The object is already disposed. Remarks If the OracleXmlType instance contains non-schema based XML data, this property returns an OracleXmlType instance representing an empty XML document. SchemaUrl This property represents the XML schema in the database for the XML schema of the XML data contained in the OracleXmlType. Declaration // C# public string SchemaUrl {get;} Property Value A string that represents the URL in the database for the XML schema of the XML data. Exceptions ObjectDisposedException - The object is already disposed. Remarks If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string. Value This property returns the XML data starting from the first character in the current instance as a string. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-47 Declaration // C# public string RootElement{get;} Property Value The entire XML data as a string. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-48 Oracle Data Provider for .NET Developer’s Guide OracleXmlType Instance Methods The OracleXmlType instance methods are listed in Table 5–25. Clone This method creates a copy of this OracleXmlType instance. Declaration // C# public object Clone(); Implements ICloneable Table 5–25 OracleXmlType Instance Methods Methods Description Clone Creates a copy of the OracleXmlType instance Dispose Releases the resources allocated by this OracleXmlType object Equals Inherited from Object Extract Extracts a subset from the XML data using the given XPath expression (Overloaded) GetHashCode Inherited from Object GetStream Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance GetType Inherited from Object GetXmlDocument Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance GetXmlReader Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods IsExists Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) ToString Inherited from Object Transform Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) Update Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) Validate Validates whether the XML data in the OracleXmlType object conforms to the given XML schema. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-49 Return Value An OracleXmlType object. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Dispose This method releases the resources allocated by this object. Declaration // C# public void Dispose(); Implements IDisposable Extract This method extracts a subset from the XML data using the given XPath expression. Overload List: ■ Extract(string, string) This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution. ■ Extract(string, XmlNameSpaceManager) This method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-50 Oracle Data Provider for .NET Developer’s Guide Extract(string, string) This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution. Declaration // C# public OracleXmlType Extract(string xpathExpr, string nsMap); Parameters ■ xpathExpr The XPath expression. ■ nsMap The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example: xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com" Return Value An OracleXmlType object. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Extract(string, XmlNameSpaceManager) This public method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution. Declaration // C# public OracleXmlType Extract(string xpathExpr, XmlNameSpaceManager nsMgr); Parameters ■ xpathExpr The XPath expression. ■ nsMgr See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-51 The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null. Return Value An OracleXmlType. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. GetStream This public method returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance. Declaration // C# public Stream GetStream(); Return Value A Stream object. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. GetXmlDocument This public method returns a XmlDocument object containing the XML data stored in this OracleXmlType instance. Declaration // C# public XmlDocument GetXmlDocument(); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-52 Oracle Data Provider for .NET Developer’s Guide Return Value An XmlDocument object. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The XML data in the XmlDocument object is a copy of the XML data in the OracleXmlType instance and modifying it does not automatically modify the XML data in the OracleXmlType instance. The XmlDocument instance returned has the PreserveWhitespace property set to true. GetXmlReader This public method returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods. Declaration // C# public XmlTextReader GetXmlReader(); Return Value An XmlTextReader object. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The XmlTextReader is a read-only, forward-only representation of the XML data stored in the OracleXmlType instance. IsExists IsExists checks for the existence of a particular set of nodes identified by the XPath expression in the XML data. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-53 Overload List: ■ IsExists(string, string) This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution. ■ IsExists(string, XmlNameSpaceManager) This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution. IsExists(string, string) This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution. Declaration // C# public bool IsExists(string xpathExpr, string nsMap); Parameters ■ xpathExpr The XPath expression. ■ nsMap The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. Return Value Returns true if the required set of nodes exists; otherwise, returns false. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-54 Oracle Data Provider for .NET Developer’s Guide IsExists(string, XmlNameSpaceManager) This method checks the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution. Declaration // C# public bool IsExists(string xpathExpr, XmlNameSpaceManager nsMgr); Parameters ■ xpathExpr The XPath expression. ■ nsMgr The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null. Return Value Returns true if the required set of nodes exists; otherwise, returns false. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. Transform This method transforms the OracleXmlType into another OracleXmlType instance using the given XSL document. Overload List: ■ Transform(OracleXmlType, string) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-55 This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document (as an OracleXmlType object) and a string of XSLT parameters. ■ Transform(string, string) This public method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters. Transform(OracleXmlType, string) This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters. Declaration // C# public OracleXmlType Transform(OracleXmlType xsldoc, string paramMap); Parameters ■ xsldoc The XSL document as an OracleXmlType object. ■ paramMap A string which provides the parameters for the XSL document. For this release, paramMap is ignored. Return Value An OracleXmlType object containing the transformed XML document. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xsldoc parameter is null. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-56 Oracle Data Provider for .NET Developer’s Guide Transform(string, string) This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters. Declaration // C# public OracleXmlType Transform(string xsldoc, string paramMap); Parameters ■ xsldoc The XSL document to be used for XSLT. ■ paramMap A string which provides the parameters for the XSL document. For this release, paramMap is ignored. Return Value An OracleXmlType object containing the transformed XML document. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xsldoc parameter is null. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Update This method updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance. Overload List: ■ Update(string, string, string) This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution. ■ Update(string, XmlNameSpaceManager, string) This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution. ■ Update(string, string, OracleXmlType) This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-57 ■ Update(string, XmlNameSpaceManager, OracleXmlType) This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution. Update(string, string, string) This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution. Declaration // C# public void Update(string xpathExpr, string nsMap, string value); Parameters ■ xpathExpr The XPath expression that identifies the nodes to update. ■ nsMap The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example: xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com" ■ value The new value as a string. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-58 Oracle Data Provider for .NET Developer’s Guide Update(string, XmlNameSpaceManager, string) This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution. Declaration // C# public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, string value); Parameters ■ xpathExpr The XPath expression that identifies the nodes to update. ■ nsMgr The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null. ■ value The new value as a string. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. Update(string, string, OracleXmlType) This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution. Declaration // C# public void Update(string xpathExpr, string nsMap, OracleXmlType value); Parameters ■ xpathExpr The XPath expression that identifies the nodes to update. ■ nsMap See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Class Oracle Data Provider for .NET XML-Related Classes 5-59 The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. ■ value The new value as an OracleXmlType object. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. Update(string, XmlNameSpaceManager, OracleXmlType) This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution. Declaration // C# public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, OracleXmlType value); Parameters ■ xpathExpr The XPath expression that identifies the nodes to update. ■ nsMgr The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null. ■ value The new value as an OracleXmlType object. Exceptions ObjectDisposedException - The object is already disposed. ArgumentNullException - The xpathExpr is null or zero-length. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The default namespace is ignored if its value is an empty string. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members OracleXmlType Instance Methods 5-60 Oracle Data Provider for .NET Developer’s Guide Validate This methods validates whether the XML data in the OracleXmlType object conforms to the given XML schema. Declaration // C# public bool Validate(String schemaUrl); Parameters ■ schemaUrl A string representing the URL in the database of the XML schema. Return Value Returns true if the XML data conforms to the XML schema; otherwise, returns false. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentNullException - The schemaUrl argument is null or an empty string. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleXmlType Class ■ OracleXmlType Members Oracle Data Provider for .NET Globalization Classes 6-1 6 Oracle Data Provider for .NET Globalization Classes This chapter describes the Oracle Data Provider for .NET globalization classes. This chapter contains these topics: ■ OracleGlobalization Class OracleGlobalization Class 6-2 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization Class The OracleGlobalization class is used to obtain and set the Oracle globalization settings of the session, thread, and local computer (read-only). Class Inheritance Object OracleGlobalization Declaration public sealed class OracleGlobalization : ICloneable, IDisposable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks An exception is thrown for invalid property values. All newly set property values are validated, except the TimeZone property. Changing the OracleGlobalization object properties does not change the globalization settings of the session or the thread. Either the SetSessionInfo method of the OracleConnection object or the SetThreadInfo method of the OracleGlobalization object must be called to alter the session's and thread's globalization settings, respectively. Example // C# using System; using Oracle.DataAccess.Client; class OracleGlobalizationSample { static void Main() { // Get thread's globalization info OracleGlobalization glob = OracleGlobalization.GetThreadInfo(); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); // Set language on thread's globalization info glob.Language = "FRENCH"; OracleGlobalization.SetThreadInfo(glob); OracleGlobalization.GetThreadInfo(glob); // Prints "glob.Language = FRENCH" Console.WriteLine("glob.Language = " + glob.Language); glob.Dispose(); } } OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-3 Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Members ■ OracleGlobalization Static Methods ■ OracleGlobalization Properties ■ OracleGlobalization Public Methods ■ Oracle Database SQL Reference ■ Oracle Database Globalization Support Guide OracleGlobalization Members 6-4 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization Members OracleGlobalization members are listed in the following tables: OracleGlobalization Static Methods The OracleGlobalization static methods are listed in Table 6–1. OracleGlobalization Properties The OracleGlobalization properties are listed in Table 6–2. Table 6–1 OracleGlobalization Static Methods Name Description GetClientInfo Returns an OracleGlobalization object that represents the Oracle globalization settings of the local computer (Overloaded) GetThreadInfo Returns or refreshes an OracleGlobalization instance that represents Oracle globalization settings of the current thread (Overloaded) SetThreadInfo Sets Oracle globalization parameters to the current thread Table 6–2 OracleGlobalization Properties Name Description Calendar Specifies the calendar system ClientCharacterSet Specifies a client character set Comparison Specifies a method of comparison for WHERE clauses and comparison in PL/SQL blocks Currency Specifies the string to use as a local currency symbol for the L number format element DateFormat Specifies the date format for Oracle Date type as a string DateLanguage Specifies the language used to spell day and month names and date abbreviations DualCurrency Specifies the dual currency symbol, such as Euro, for the U number format element ISOCurrency Specifies the string to use as an international currency symbol for the C number format element Language Specifies the default language of the database LengthSemantics Enables creation of CHAR and VARCHAR2 columns using either byte or character (default) length semantics NCharConversionException Determines whether data loss during an implicit or explicit character type conversion reports an error NumericCharacters Specifies the characters used for the decimal character and the group separator character for numeric values in strings Sort Specifies the collating sequence for ORDER by clause Territory Specifies the name of the territory TimeStampFormat Specifies the string format for TimeStamp types TimeStampTZFormat Specifies the string format for TimeStampTZ types TimeZone Specifies the time zone region name OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-5 OracleGlobalization Public Methods OracleGlobalization public methods are listed in Table 6–6. Table 6–3 OracleGlobalization Public Methods Public Method Description Clone Creates a copy of an OracleGlobalization object Dispose Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Static Methods 6-6 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization Static Methods The OracleGlobalization static methods are listed in Table 6–4. GetClientInfo GetClientInfo returns an OracleGlobalization object instance that represents the Oracle globalization settings of the local computer. Overload List: ■ GetClientInfo() This method returns an OracleGlobalization instance that represents the globalization settings of the local computer. ■ GetClientInfo(OracleGlobalization) This method refreshes the provided OracleGlobalization object with the globalization settings of the local computer. GetClientInfo() This method returns an OracleGlobalization instance that represents the globalization settings of the local computer. Declaration // C# public static OracleGlobalization GetClientInfo(); Return Value An OracleGlobalization instance. Table 6–4 OracleGlobalization Static Methods Name Description GetClientInfo Returns an OracleGlobalization object that represents the Oracle globalization settings of the local computer (Overloaded) GetThreadInfo Returns or refreshes an OracleGlobalization instance that represents Oracle globalization settings of the current thread (Overloaded) SetThreadInfo Sets Oracle globalization parameters to the current thread See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-7 Example // C# using System; using Oracle.DataAccess.Client; class GetClientInfoSample { static void Main() { // Get client's globalization info OracleGlobalization glob = OracleGlobalization.GetClientInfo(); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); glob.Dispose(); } } GetClientInfo(OracleGlobalization) This method refreshes the provided OracleGlobalization object with the globalization settings of the local computer. Declaration // C# public static void GetClientInfo(OracleGlobalization oraGlob); Parameters ■ oraGlob The OracleGlobalization object being updated. Example // C# using System; using Oracle.DataAccess.Client; class GetClientInfoSample { static void Main() { // Get client's globalization info OracleGlobalization glob = OracleGlobalization.GetClientInfo(); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); // Get client's globalization info using overload OracleGlobalization.GetClientInfo(glob); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Static Methods 6-8 Oracle Data Provider for .NET Developer’s Guide // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); glob.Dispose(); } } GetThreadInfo GetThreadInfo returns or refreshes an OracleGlobalization instance. Overload List: ■ GetThreadInfo() This method returns an OracleGlobalization object instance of the current thread. ■ GetThreadInfo(OracleGlobalization) This method refreshes the OracleGlobalization object instance with the globalization settings of the current thread. GetThreadInfo() This method returns an OracleGlobalization instance of the current thread. Declaration // C# public static OracleGlobalization GetThreadInfo(); Return Value An OracleGlobalization instance. Remarks Initially, GetThreadInfo() returns an OracleGlobalization object that has the same property values as that returned by GetClientInfo(), unless the application changes it by invoking SetThreadInfo(). Example // C# using System; using Oracle.DataAccess.Client; See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-9 class GetThreadInfoSample { static void Main() { // Get thread's globalization info OracleGlobalization glob = OracleGlobalization.GetThreadInfo(); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); // Get thread's globalization info using overloaded OracleGlobalization.GetThreadInfo(glob); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); glob.Dispose(); } } GetThreadInfo(OracleGlobalization) This method refreshes the OracleGlobalization object with the globalization settings of the current thread. Declaration // C# public static void GetThreadInfo(OracleGlobalization oraGlob); Parameters ■ oraGlob The OracleGlobalization object being updated. Remarks Initially GetThreadInfo() returns an OracleGlobalization object that has the same property values as that returned by GetClientInfo(), unless the application changes it by invoking SetThreadInfo(). Example // C# using System; using Oracle.DataAccess.Client; class GetThreadInfoSample { static void Main() { // Get thread's globalization info See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Static Methods 6-10 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization glob = OracleGlobalization.GetThreadInfo(); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); // Get thread's globalization info using overloaded OracleGlobalization.GetThreadInfo(glob); // Prints "glob.Language = AMERICAN" Console.WriteLine("glob.Language = " + glob.Language); glob.Dispose(); } } SetThreadInfo This method sets Oracle globalization parameters to the current thread. Declaration // C# public static void SetThreadInfo(OracleGlobalization oraGlob); Parameters ■ oraGlob An OracleGlobalization object. Remarks Any .NET string conversions to and from ODP.NET Types, as well as ODP.NET Type constructors, use the globalization property values where applicable. For example, when constructing an OracleDate structure from a .NET string, that string is expected to be in the format specified by the OracleGlobalization.DateFormat property of the thread. Example // C# using System; using Oracle.DataAccess.Client; class SetThreadInfoSample { static void Main() { // Get thread's globalization info OracleGlobalization glob1 = OracleGlobalization.GetThreadInfo(); // Prints "glob1.Language = AMERICAN" Console.WriteLine("glob1.Language = " + glob1.Language); See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-11 // Set language on thread's globalization info glob1.Language = "FRENCH"; OracleGlobalization.SetThreadInfo(glob1); OracleGlobalization glob2 = OracleGlobalization.GetThreadInfo(); // Prints "glob2.Language = FRENCH" Console.WriteLine("glob2.Language = " + glob2.Language); glob1.Dispose(); glob2.Dispose(); } } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Properties 6-12 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization Properties The OracleGlobalization properties are listed in Table 6–5. Calendar This property specifies the calendar system. Declaration // C# public string Calendar {get; set;} Table 6–5 OracleGlobalization Properties Name Description Calendar Specifies the calendar system ClientCharacterSet Specifies a client character set Comparison Specifies a method of comparison for WHERE clauses and comparison in PL/SQL blocks Currency Specifies the string to use as a local currency symbol for the L number format element DateFormat Specifies the date format for Oracle Date type as a string DateLanguage Specifies the language used to spell day and month names and date abbreviations DualCurrency Specifies the dual currency symbol, such as Euro, for the U number format element ISOCurrency Specifies the string to use as an international currency symbol for the C number format element Language Specifies the default language of the database LengthSemantics Enables creation of CHAR and VARCHAR2 columns using either byte or character (default) length semantics NCharConversionException Determines whether data loss during an implicit or explicit character type conversion reports an error NumericCharacters Specifies the characters used for the decimal character and the group separator character for numeric values in strings Sort Specifies the collating sequence for ORDER by clause Territory Specifies the name of the territory TimeStampFormat Specifies the string format for TimeStamp types TimeStampTZFormat Specifies the string format for TimeStampTZ types TimeZone Specifies the time zone region name See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-13 Property Value A string representing the Calendar. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_CALENDAR setting of the local computer. This value is the same regardless of whether the OracleGlobalization object represents the settings of the client, thread, or session. ClientCharacterSet This property specifies a client character set. Declaration // C# public string ClientCharacterSet {get;} Property Value A string that the provides the name of the character set of the local computer. Remarks The default value is the character set of the local computer. Comparison This property represents a method of comparison for WHERE clauses and comparison in PL/SQL blocks. Declaration // C# public string Comparison {get; set;} Property Value A string that provides the name of the method of comparison. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Properties 6-14 Oracle Data Provider for .NET Developer’s Guide Remarks The default value is the NLS_COMP setting of the local computer. Currency This property specifies the string to use as a local currency symbol for the L number format element. Declaration // C# public string Currency {get; set;} Property Value The string to use as a local currency symbol for the L number format element. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_CURRENCY setting of the local computer. DateFormat This property specifies the date format for Oracle Date type as a string. Declaration // C# public string DateFormat {get; set;} Property Value The date format for Oracle Date type as a string Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_DATE_FORMAT setting of the local computer. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members ■ Oracle Database SQL Reference for further information on the L number format element OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-15 DateLanguage This property specifies the language used to spell names of days and months, and date abbreviations (for example: a.m., p.m., AD, BC). Declaration // C# public string DateLanguage {get; set;} Property Value A string specifying the language. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_DATE_LANGUAGE setting of the local computer. DualCurrency This property specifies the dual currency symbol, such as Euro, for the U number format element. Declaration // C# public string DualCurrency {get; set;} Property Value A string that provides the dual currency symbol. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_DUAL_CURRENCY setting of the local computer. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Properties 6-16 Oracle Data Provider for .NET Developer’s Guide ISOCurrency This property specifies the string to use as an international currency symbol for the C number format element. Declaration // C# public string ISOCurrency {get; set;} Property Value The string used as an international currency symbol. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_ISO_CURRENCY setting of the local computer. Language This property specifies the default language of the database. Declaration // C# public string Language {get; set;} Property Value The default language of the database. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_LANGUAGE setting of the local computer. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members ■ Oracle Database SQL Reference for further information on the U number format element See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members ■ Oracle Database SQL Reference for further information on the C number format element OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-17 Language is used for messages, day and month names, and sorting algorithms. It also determines NLS_DATE_LANGUAGE and NLS_SORT parameter values. LengthSemantics This property indicates whether CHAR and VARCHAR2 columns use byte or character (default) length semantics. Declaration // C# public string LengthSemantics {get; set;} Property Value A string that indicates either byte or character length semantics. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_LENGTH_SEMANTICS setting of the local computer. NCharConversionException This property determines whether data loss during an implicit or explicit character type conversion reports an error. Declaration // C# public bool NCharConversionException {get; set;} Property Value A string that indicates whether or not a character type conversion causes an error message. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value of NLS_NCHAR_CONV_EXCP is False, unless it is overridden by a setting in the INIT.ORA file. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Properties 6-18 Oracle Data Provider for .NET Developer’s Guide NumericCharacters This property specifies the characters used for the decimal character and the group separator character for numeric values in strings. Declaration // C# public string NumericCharacters {get; set;} Property Value A string that represents the characters used. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_NUMERIC_CHARACTERS setting of the local computer. Sort This property specifies the collating sequence for ORDER by clause. Declaration // C# public string Sort {get; set;} Property Value A string that indicates the collating sequence. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_SORT setting of the local computer. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-19 Territory This property specifies the name of the territory. Declaration // C# public string Territory {get; set;} Property Value A string that provides the name of the territory. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_TERRITORY setting of the local computer. Changing this property changes other globalization properties. TimeStampFormat This property specifies the string format for TimeStamp types. Declaration // C# public string TimeStampFormat {get; set;} Property Value The string format for TimeStamp types. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_TIMESTAMP_FORMAT setting of the local computer. TimeStampTZFormat This property specifies the string format for TimeStampTZ types. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members ■ Oracle Database Globalization Support Guide. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Properties 6-20 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public string TimeStampTZFormat {get; set;} Property Value The string format for TimeStampTZ types. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the NLS_TIMESTAMP_TZ_FORMAT setting of the local computer. TimeZone This property specifies the time zone region name or hour offset. Declaration // C# public string TimeZone {get; set;} Property Value The string represents the time zone region name or the time zone offset. Exceptions ObjectDisposedException - The object is already disposed. Remarks The default value is the time zone region name of the local computer TimeZone is only used when the thread constructs one of the TimeStamp structures. TimeZone has no effect on the session. TimeZone can be either an hour offset, for example, 7:00, or a valid time zone region name that is provided in V$TIMEZONE_NAMES, such as US/Pacific. Time zone abbreviations are not supported. This property returns an empty string if the OracleGlobalization object is obtained using GetSessionInfo() or GetSessionInfo(OracleGlobalization). Initially, by default, the time zone of the session is identical to the time zone of the thread. Therefore, given that the session time zone is not changed by invoking ALTER SESSION calls, the session time zone can be fetched from the client's globalization settings. See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members Note: PST is a time zone region name as well as a time zone abbreviation; therefore it is accepted by OracleGlobalization. OracleGlobalization Class Oracle Data Provider for .NET Globalization Classes 6-21 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members OracleGlobalization Public Methods 6-22 Oracle Data Provider for .NET Developer’s Guide OracleGlobalization Public Methods OracleGlobalization public methods are listed in Table 6–6. Clone This method creates a copy of an OracleGlobalization object. Declaration // C# public object Clone(); Return Value An OracleGlobalization object. Implements ICloneable Remarks The cloned object has the same property values as that of the object being cloned. Table 6–6 OracleGlobalization Public Methods Public Method Description Clone Creates a copy of an OracleGlobalization object Dispose Inherited from Component See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleGlobalization Class ■ OracleGlobalization Members Oracle Data Provider for .NET Failover Classes 7-1 7 Oracle Data Provider for .NET Failover Classes This chapter describes the Oracle Data Provider for .NET failover classes and enumerations. This chapter contains these topics: ■ OracleFailoverEventArgs Class ■ OracleFailoverEventHandler Delegate ■ FailoverEvent Enumeration ■ FailoverReturnCode Enumeration ■ FailoverType Enumeration OracleFailoverEventArgs Class 7-2 Oracle Data Provider for .NET Developer’s Guide OracleFailoverEventArgs Class The OracleFailoverEventArgs class provides event data for the OracleConnection.Failover event. When database failover occurs, the OracleConnection.Failover event is triggered along with the OracleFailoverEventArgs object that stores the event data. Class Inheritance Object EventArgs OracleFailoverEventArgs Declaration // C# public sealed class OracleFailoverEventArgs Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // Transparent Application Failover (TAF) Setup // Refer Oracle® Database Net Services Administrator's Guide // C# using System; using System.Threading; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleFailoverEventArgsSample { static void Main(string[] args) { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Register the event handler OnFailover con.Failover += new OracleFailoverEventHandler(OnFailover); con.Close(); con.Dispose(); } // TAF callback function static FailoverReturnCode OnFailover(object sender, OracleFailoverEventArgs eventArgs) { switch (eventArgs.FailoverEvent) { case FailoverEvent.Begin: { OracleFailoverEventArgs Class Oracle Data Provider for .NET Failover Classes 7-3 Console.WriteLine("FailoverEvent.Begin - Failover is starting"); Console.WriteLine("FailoverType = " + eventArgs.FailoverType); break; } case FailoverEvent.End: { Console.WriteLine("FailoverEvent.End - Failover was successful"); break; } case FailoverEvent.Reauth: { Console.WriteLine("FailoverEvent.Reauth - User reauthenticated"); break; } case FailoverEvent.Error: { Console.WriteLine("FailoverEvent.Error - Failover was unsuccessful"); // Sleep for 3 sec and Retry Thread.Sleep(3000); return FailoverReturnCode.Retry; } case FailoverEvent.Abort: { Console.WriteLine("FailoverEvent.Abort - Failover was unsuccessful"); break; } default: { Console.WriteLine("Invalid FailoverEvent : " + eventArgs.FailoverEvent); break; } } return FailoverReturnCode.Success; } } Requirements Namespace: Oracle.DataAccess.Client Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Members ■ OracleFailoverEventArgs Static Methods ■ OracleFailoverEventArgs Properties ■ OracleFailoverEventArgs Public Methods ■ "OracleConnection Class" on page 4-54 OracleFailoverEventArgs Members 7-4 Oracle Data Provider for .NET Developer’s Guide OracleFailoverEventArgs Members OracleFailoverEventArgs members are listed in the following tables: OracleFailoverEventArgs Static Methods The OracleFailoverEventArgs static methods are listed in Table 7–1. OracleFailoverEventArgs Properties The OracleFailoverEventArgs properties are listed in Table 7–2. OracleFailoverEventArgs Public Methods The OracleFailoverEventArgs public methods are listed in Table 7–3. Table 7–1 OracleFailoverEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 7–2 OracleFailoverEventArgs Properties Name Description FailoverType Specifies the type of failover the client has requested FailoverEvent Indicates the state of the failover Table 7–3 OracleFailoverEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ "FailoverType Enumeration" on page 7-12 OracleFailoverEventArgs Class Oracle Data Provider for .NET Failover Classes 7-5 OracleFailoverEventArgs Static Methods The OracleFailoverEventArgs static methods are listed in Table 7–1. Table 7–4 OracleFailoverEventArgs Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members OracleFailoverEventArgs Properties 7-6 Oracle Data Provider for .NET Developer’s Guide OracleFailoverEventArgs Properties The OracleFailoverEventArgs properties are listed in Table 7–5. FailoverType This property indicates the state of the failover. Declaration // C# public FailoverType FailoverType {get;} Property Value A FailoverType enumeration value. FailoverEvent This property indicates the state of the failover. Declaration // C# public FailoverEvent FailoverEvent {get;} Property Value A FailoverEvent enumerated value. Table 7–5 OracleFailoverEventArgs Properties Name Description FailoverType Specifies the type of failover the client has requested FailoverEvent Indicates the state of the failover See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members ■ "FailoverType Enumeration" on page 7-12 See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members ■ "FailoverEvent Enumeration" on page 7-10 OracleFailoverEventArgs Class Oracle Data Provider for .NET Failover Classes 7-7 OracleFailoverEventArgs Public Methods The OracleFailoverEventArgs public methods are listed in Table 7–6. Table 7–6 OracleFailoverEventArgs Public Methods Name Description Equals Inherited from Object (Overloaded) GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members OracleFailoverEventHandler Delegate 7-8 Oracle Data Provider for .NET Developer’s Guide OracleFailoverEventHandler Delegate The OracleFailoverEventHandler represents the signature of the method that handles the OracleConnection.Failover event. Declaration // C# public delegate FailoverReturnCode OracleFailoverEventHandler(object sender, OracleFailoverEventArgs eventArgs); Parameter ■ sender The source of the event. ■ eventArgs The OracleFailoverEventArgs object that contains the event data. Return Type An int. Remarks To receive failover notifications, a callback function can be registered as follows: ConObj.Failover += new OracleFailoverEventHandler(OnFailover); The definition of the callback function OnFailover can be as follows: public FailoverReturnCode OnFailover(object sender, OracleFailoverEventArgs eventArgs) Example // Transparent Application Failover (TAF) Setup // Refer Oracle® Database Net Services Administrator's Guide // C# using System; using System.Threading; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleFailoverEventHandlerSample { static void Main(string[] args) { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Register the event handler OnFailover con.Failover += new OracleFailoverEventHandler(OnFailover); con.Close(); con.Dispose(); OracleFailoverEventHandler Delegate Oracle Data Provider for .NET Failover Classes 7-9 } // TAF callback function static FailoverReturnCode OnFailover(object sender, OracleFailoverEventArgs eventArgs) { switch (eventArgs.FailoverEvent) { case FailoverEvent.Begin: { Console.WriteLine("FailoverEvent.Begin - Failover is starting"); Console.WriteLine("FailoverType = " + eventArgs.FailoverType); break; } case FailoverEvent.End: { Console.WriteLine("FailoverEvent.End - Failover was successful"); break; } case FailoverEvent.Reauth: { Console.WriteLine("FailoverEvent.Reauth - User reauthenticated"); break; } case FailoverEvent.Error: { Console.WriteLine("FailoverEvent.Error - Failover was unsuccessful"); // Sleep for 3 sec and Retry Thread.Sleep(3000); return FailoverReturnCode.Retry; } case FailoverEvent.Abort: { Console.WriteLine("FailoverEvent.Abort - Failover was unsuccessful"); break; } default: { Console.WriteLine("Invalid FailoverEvent : " + eventArgs.FailoverEvent); break; } } return FailoverReturnCode.Success; } } See Also: ■ "Oracle.DataAccess.Client Namespace" on page 1-1 ■ OracleFailoverEventArgs Class ■ OracleFailoverEventArgs Members FailoverEvent Enumeration 7-10 Oracle Data Provider for .NET Developer’s Guide FailoverEvent Enumeration FailoverEvent enumerated values are used to explicitly specify the state of the failover. Table 7–7 lists all the FailoverEvent enumeration values with a description of each enumerated value. Table 7–7 FailoverEvent Enumeration Values Member Names Description FailoverEvent.Begin Indicates that failover has detected a lost connection and that failover is starting. FailoverEvent.End Indicates successful completion of failover. FailoverEvent.Abort Indicates that failover was unsuccessful, and there is no option of retrying. FailoverEvent.Error Indicates that failover was unsuccessful, and it gives the application the opportunity to handle the error and retry failover. The application can retry failover by returning FailoverReturnCode.Retry for the event notification. FailoverEvent.Reauth Indicates that a user handle has been reauthenticated. This applies to the situation where a client has multiple user sessions on a single server connection. During the initial failover, only the active user session is failed over. Other sessions are failed over when the application tries to use them. This is the value passed to the callback during these subsequent failovers. See Also: ■ FailoverEvent Enumeration on page 7-10 ■ "OracleFailoverEventArgs Class" on page 7-2 ■ "FailoverEvent" on page 7-6 ■ Oracle Real Application Clusters Quick Start ■ Oracle Net Services Reference Guide FailoverReturnCode Enumeration Oracle Data Provider for .NET Failover Classes 7-11 FailoverReturnCode Enumeration FailoverReturnCode enumerated values 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. Table 7–8 lists the FailoverReturnCode enumeration values with a description of each enumerated value. Table 7–8 FailoverReturnCode Enumeration Values Member Names Description FailoverReturnCode.Retry Requests ODP.NET to retry failover in case FailoverEvent.Error is passed to the application FailoverReturnCode.Success Requests ODP.NET to proceed so that the application receive more notifications, if any See Also: ■ FailoverEvent Enumeration on page 7-10 ■ "OracleFailoverEventArgs Class" on page 7-2 ■ "FailoverEvent" on page 7-6 ■ Oracle Real Application Clusters Quick Start ■ Oracle Net Services Reference Guide FailoverType Enumeration 7-12 Oracle Data Provider for .NET Developer’s Guide FailoverType Enumeration FailoverType enumerated values are used to indicate the type of failover event that was raised. Table 7–9 lists all the FailoverType enumeration values with a description of each enumerated value. Table 7–9 FailoverType Enumeration Values Member Names Description FailoverType.Session Indicates that the user has requested only session failover. FailoverType.Select Indicates that the user has requested select and session failover. See Also: ■ FailoverEvent Enumeration on page 7-10 ■ "OracleFailoverEventArgs Class" on page 7-2 ■ "FailoverType" on page 7-6 ■ Oracle Real Application Clusters Quick Start ■ Oracle Net Services Reference Guide Oracle Data Provider for .NET Types Classes 8-1 8 Oracle Data Provider for .NET Types Classes This chapter describes the large object and REF CURSOR objects provided by Oracle Data Provider for .NET. This chapter contains these topics: ■ ODP.NET Types (ODP.NET LOB objects) consisting of these object classes: ■ OracleBFile Class ■ OracleBlob Class ■ OracleClob Class ■ OracleRefCursor Class All offsets are 0-based for all ODP.NET LOB object parameters. OracleBFile Class 8-2 Oracle Data Provider for .NET Developer’s Guide OracleBFile Class An OracleBFile is an object that has a reference to BFILE data. It provides methods for performing operations on BFiles. Class Inheritance Object MarshalByRefObject Stream OracleBFile Declaration // C# public sealed class OracleBFile : Stream, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleBFile is supported for applications running against Oracle8.x and higher. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleBFileSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); Note: OracleBFile is supported for applications running against Oracle8.x and higher. OracleBFile Class Oracle Data Provider for .NET Types Classes 8-3 OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt"); // Open the OracleBFile bFile.OpenFile(); // Read 7 bytes into readBuffer, starting at buffer offset 0 byte[] readBuffer = new byte[7]; int bytesRead = bFile.Read(readBuffer, 0, 7); // Prints "bytesRead = 7" Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 65666768656667" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Search for the 2nd occurrence of a byte pattern {66,67} // starting from byte offset 1 in the OracleBFile byte[] pattern = new byte[2] {66, 67}; long posFound = bFile.Search(pattern, 1, 2); // Prints "posFound = 6" Console.WriteLine("posFound = " + posFound); // Close the OracleBFile bFile.CloseFile(); bFile.Close(); bFile.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Members ■ OracleBFile Constructors ■ OracleBFile Static Fields ■ OracleBFile Static Methods ■ OracleBFile Instance Properties ■ OracleBFile Instance Methods OracleBFile Members 8-4 Oracle Data Provider for .NET Developer’s Guide OracleBFile Members OracleBFile members are listed in the following tables: OracleBFile Constructors OracleBFile constructors are listed in Table 8–1. OracleBFile Static Fields OracleBFile static fields are listed in Table 8–2. OracleBFile Static Methods OracleBFile static methods are listed in Table 8–3. OracleBFile Instance Properties OracleBFile instance properties are listed in Table 8–4. Table 8–1 OracleBFile Constructors Constructor Description OracleBFile Constructors Creates an instance of the OracleBFile class (Overloaded) Table 8–2 OracleBFile Static Fields Field Description MaxSize The static field holds the maximum number of bytes a BFILE can hold, which is 4,294,967,295 (2^32 - 1) bytes Table 8–3 OracleBFile Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 8–4 OracleBFile Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations can be performed CanWrite Indicates whether the LOB object supports writing Connection Indicates the connection used to read from a BFILE DirectoryName Indicates the directory alias of the BFILE FileExists Indicates whether or not the specified BFILE exists FileName Indicates the name of the BFILE IsEmpty Indicates whether the BFILE is empty or not IsOpen Indicates whether the BFILE has been opened by this instance or not Length Indicates the size of the BFILE data in bytes OracleBFile Class Oracle Data Provider for .NET Types Classes 8-5 OracleBFile Instance Methods OracleBFile instance methods are listed in Table 8–5. Position Indicates the current read position in the LOB stream Value Returns the data, starting from the first byte in BFILE, as a byte array Table 8–5 OracleBFile Instance Methods Methods Description BeginRead Inherited from Stream BeginWrite Not Supported Clone Creates a copy of an OracleBFile object Close Closes the current stream and releases any resources associated with the stream CloseFile Closes the BFILE referenced by the current BFILE instance Compare Compares data referenced by the two OracleBFiles CreateObjRef Inherited from MarshalByRefObject CopyTo Copies data as specified (Overloaded) Dispose Releases resources allocated by this object EndRead Inherited from Stream EndWrite Not Supported Equals Inherited from Object (Overloaded) Flush Not Supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB references OpenFile Opens the BFILE specified by the FileName and DirectoryName Read Reads a specified amount of bytes from the OracleBFile instance and populates the buffer ReadByte Inherited from Stream Search Searches for a binary pattern in the current instance of an OracleBFile Seek Sets the position on the current LOB stream SetLength Not Supported ToString Inherited from Object Table 8–4 (Cont.) OracleBFile Instance Properties Properties Description OracleBFile Members 8-6 Oracle Data Provider for .NET Developer’s Guide Write Not Supported WriteByte Not Supported See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Members Table 8–5 (Cont.) OracleBFile Instance Methods Methods Description OracleBFile Class Oracle Data Provider for .NET Types Classes 8-7 OracleBFile Constructors OracleBFile constructors create new instances of the OracleBFile class. Overload List: ■ OracleBFile(OracleConnection) This constructor creates an instance of the OracleBFile class with an OracleConnection object. ■ OracleBFile(OracleConnection, string, string) This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE. OracleBFile(OracleConnection) This constructor creates an instance of the OracleBFile class with an OracleConnection object. Declaration // C# public OracleBFile(OracleConnection con); Parameters ■ con The OracleConnection object. Exceptions InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The connection must be opened explicitly by the application. OracleBFile does not open the connection implicitly. OracleBFile(OracleConnection, string, string) This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Constructors 8-8 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public OracleBFile(OracleConnection con, string directoryName, string fileName); Parameters ■ con The OracleConnection object. ■ directoryName The directory alias created by the CREATE DIRECTORY SQL statement. ■ fileName The name of the external LOB. Exceptions InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The OracleConnection must be opened explicitly by the application. OracleBFile does not open the connection implicitly. To initialize a BFILE column using an OracleBFile instance as an input parameter of a SQL INSERT statement, directoryName and fileName must be properly set. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-9 OracleBFile Static Fields OracleBFile static fields are listed in Table 8–6. MaxSize This static field holds the maximum number of bytes a BFILE can hold, which is 4,294,967,295 (2^32 - 1) bytes. Declaration // C# public static readonly Int64 MaxSize = 4294967295; Remarks This field is useful in code that checks whether the operation exceeds the maximum length allowed. Table 8–6 OracleBFile Static Fields Field Description MaxSize The static field holds the maximum number of bytes a BFILE can hold, which is 4,294,967,295 (2^32 - 1) bytes See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Static Methods 8-10 Oracle Data Provider for .NET Developer’s Guide OracleBFile Static Methods OracleBFile static methods are listed in Table 8–7. Table 8–7 OracleBFile Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-11 OracleBFile Instance Properties OracleBFile instance properties are listed in Table 8–8. CanRead Overrides Stream This instance property indicates whether the LOB stream can be read. Declaration // C# public override bool CanRead{get;} Property Value If the LOB stream can be read, returns true; otherwise, returns false. CanSeek Overrides Stream Table 8–8 OracleBFile Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations can be performed CanWrite Indicates whether the LOB object supports writing Connection Indicates the connection used to read from a BFILE DirectoryName Indicates the directory alias of the BFILE FileExists Indicates whether or not the specified BFILE exists FileName Indicates the name of the BFILE IsEmpty Indicates whether the BFILE is empty or not IsOpen Indicates whether the BFILE has been opened by this instance or not Length Indicates the size of the BFILE data in bytes Position Indicates the current read position in the LOB stream Value Returns the data, starting from the first byte in BFILE, as a byte array See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Properties 8-12 Oracle Data Provider for .NET Developer’s Guide This instance property indicates whether forward and backward seek operations can be performed. Declaration // C# public override bool CanSeek{get;} Property Value If forward and backward seek operations can be performed, returns true; otherwise, returns false. CanWrite Overrides Stream This instance property indicates whether the LOB object supports writing. Declaration // C# public override bool CanWrite{get;} Property Value BFILE is read only. Remarks BFILE is read-only, therefore, the boolean value is always false. Connection This instance property indicates the connection used to read from a BFILE. Declaration // C# public OracleConnection Connection {get;} Property Value An object of OracleConnection. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-13 DirectoryName This instance property indicates the directory alias of the BFILE. Declaration // C# public string DirectoryName {get;set;} Property Value A string. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The value of the DirectoryName changed while the BFILE is open. Remarks The maximum length of a DirectoryName is 30 bytes. FileExists This instance property indicates whether or not the BFILE specified by the DirectoryName and FileName exists. Declaration // C# public bool FileExists {get;} Property Value bool Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Unless a connection, file name, and directory name are provided, this property is set to false by default. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Properties 8-14 Oracle Data Provider for .NET Developer’s Guide FileName This instance property indicates the name of the BFILE. Declaration // C# public string FileName {get;set} Property Value A string that contains the BFILE name. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The value of the DirectoryName changed while the BFILE is open. Remarks The maximum length of a FileName is 255 bytes. Changing the FileName property while the BFILE object is opened causes an exception. IsEmpty This instance property indicates whether the BFILE is empty or not. Declaration // C# public bool IsEmpty {get;} Property Value bool Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-15 IsOpen This instance property indicates whether the BFILE has been opened by this instance or not. Declaration // C# public bool IsOpen {get;} Property Value A bool. Length Overrides Stream This instance property indicates the size of the BFILE data in bytes. Declaration // C# public override Int64 Length {get;} Property Value Int64 Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Position Overrides Stream This instance property indicates the current read position in the LOB stream. Declaration // C# public override Int64 Position{get; set;} Property Value An Int64 value that indicates the read position. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Properties 8-16 Oracle Data Provider for .NET Developer’s Guide Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The value is less than 0. Value This instance property returns the data, starting from the first byte in BFILE, as a byte array. Declaration // C# public byte[] Value{get;} Property Value A byte array. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The length of data is bound by the maximum length of the byte array. The current value of the Position property is not used or changed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-17 OracleBFile Instance Methods OracleBFile instance methods are listed in Table 8–9. Table 8–9 OracleBFile Instance Methods Methods Description BeginRead Inherited from Stream BeginWrite Not Supported Clone Creates a copy of an OracleBFile object Close Closes the current stream and releases any resources associated with the stream CloseFile Closes the BFILE referenced by the current BFILE instance Compare Compares data referenced by the two OracleBFiles CreateObjRef Inherited from MarshalByRefObject CopyTo Copies data as specified (Overloaded) Dispose Releases resources allocated by this object EndRead Inherited from Stream EndWrite Not Supported Equals Inherited from Object (Overloaded) Flush Not Supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB references OpenFile Opens the BFILE specified by the FileName and DirectoryName Read Reads a specified amount of bytes from the OracleBFile instance and populates the buffer ReadByte Inherited from Stream Search Searches for a binary pattern in the current instance of an OracleBFile Seek Sets the position on the current LOB stream SetLength Not Supported ToString Inherited from Object Write Not Supported WriteByte Not Supported OracleBFile Instance Methods 8-18 Oracle Data Provider for .NET Developer’s Guide Clone This instance method creates a copy of an OracleBFile object. Declaration // C# public object Clone(); Return Value An OracleBFile object. Implements ICloneable Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The cloned object has the same property values as that of the object being cloned. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CloneSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt"); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-19 // Prints "bFile1.Position = 0" Console.WriteLine("bFile1.Position = " + bFile1.Position); // Set the Position before calling Clone() bFile1.Position = 1; // Clone the OracleBFile OracleBFile bFile2 = (OracleBFile) bFile1.Clone(); // Prints "bFile2.Position = 1" Console.WriteLine("bFile2.Position = " + bFile2.Position); bFile1.Close(); bFile1.Dispose(); bFile2.Close(); bFile2.Dispose(); con.Close(); con.Dispose(); } } Close Overrides Stream This instance method closes the current stream and releases any resources associated with it. Declaration // C# public override void Close(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. CloseFile This instance method closes the BFILE referenced by the current BFILE instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-20 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public void CloseFile(); Remarks No error is returned if the BFILE exists, but is not opened. Compare This instance method compares data referenced by the two OracleBFiles. Declaration // C# public int Compare(Int64 src_offset, OracleBFile obj, Int64 dst_offset, Int64 amount); Parameters ■ src_offset The offset of the current instance. ■ obj The provided OracleBFile object. ■ dst_offset The offset of the OracleBFile object. ■ amount The number of bytes to compare. Return Value Returns a number that is: ■ Less than zero: if the BFILE data of the current instance is less than that of the provided BFILE data. ■ Zero: if both the BFILEs store the same data. ■ Greater than zero: if the BFILE data of the current instance is greater than that of the provided BFILE data. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-21 Remarks The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. The BFILE needs to be opened using OpenFile before the operation. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CompareSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt"); OracleBFile bFile2 = new OracleBFile(con, "MYDIR", "MyFile.txt"); // Open the OracleBFiles bFile1.OpenFile(); bFile2.OpenFile(); // Compare 2 bytes from the 1st byte of bFile1 and // the 5th byte of bFile2 onwards int result = bFile1.Compare(1, bFile2, 5, 2); // Prints "result = 0" (Indicates the data is identical) Console.WriteLine("result = " + result); // Close the OracleBFiles bFile1.CloseFile(); bFile2.CloseFile(); bFile1.Close(); bFile1.Dispose(); bFile2.Close(); bFile2.Dispose(); con.Close(); con.Dispose(); } } OracleBFile Instance Methods 8-22 Oracle Data Provider for .NET Developer’s Guide CopyTo CopyTo copies data from the current instance to the provided object. Overload List: ■ CopyTo(OracleBlob) This instance method copies data from the current instance to the provided OracleBlob object. ■ CopyTo(OracleBlob, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified destination offset. ■ CopyTo(Int64, OracleBlob, Int64, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts. ■ CopyTo(OracleClob) This instance method copies data from the current OracleBFile instance to the provided OracleClob object. ■ CopyTo(OracleClob, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified destination offset. ■ CopyTo(Int64, OracleClob, Int64, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified source offset, destination offset, and amount of characters. CopyTo(OracleBlob) This instance method copies data from the current instance to the provided OracleBlob object. Declaration // C# public Int64 CopyTo(OracleBlob obj); Parameters ■ obj See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-23 The OracleBlob object to which the data is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. CopyTo(OracleBlob, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified destination offset. Declaration // C# public Int64 CopyTo(OracleBlob obj, Int64 dst_offset); Parameters ■ obj The OracleBlob object to which the data is copied. ■ dst_offset The offset (in bytes) at which the OracleBlob object is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The dst_offset is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-24 Oracle Data Provider for .NET Developer’s Guide ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. CopyTo(Int64, OracleBlob, Int64, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts. Declaration // C# public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset, Int64 amount); Parameters ■ src_offset The offset (in bytes) in the current instance, from which the data is read. ■ obj An OracleBlob object to which the data is copied. ■ dst_offset The offset (in bytes) to which the OracleBlob object is copied. ■ amount The amount of data to be copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-25 ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. CopyTo(OracleClob) This instance method copies data from the current OracleBFile instance to the provided OracleClob object. Declaration // C# public Int64 CopyTo(OracleClob obj); Parameters ■ obj The OracleClob object to which the data is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-26 Oracle Data Provider for .NET Developer’s Guide CopyTo(OracleClob, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified destination offset. Declaration // C# public Int64 CopyTo(OracleClob obj, Int64 dst_offset); Parameters ■ obj The OracleClob object that the data is copied to. ■ dst_offset The offset (in characters) at which the OracleClob object is copied to. Return Value The amount copied. Exceptions Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The dst_offset is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the OracleClob data, spaces are written into the OracleClob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. CopyTo(Int64, OracleClob, Int64, Int64) This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified source offset, destination offset, and amount of characters. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-27 Declaration // C# public Int64 CopyTo(Int64 src_offset,OracleClob obj,Int64 dst_offset, Int64 amount); Parameters ■ src_offset The offset (in characters) in the current instance, from which the data is read. ■ obj An OracleClob object that the data is copied to. ■ dst_offset The offset (in characters) at which the OracleClob object is copied to. ■ amount The amount of data to be copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the current OracleClob data, spaces are written into the OracleClob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. Dispose This instance method releases resources allocated by this object. Declaration // C# See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-28 Oracle Data Provider for .NET Developer’s Guide public void Dispose(); Implements IDisposable Remarks Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls may lead to exceptions. The object cannot be reused after being disposed. IsEqual This instance method compares the LOB references. Declaration // C# public bool IsEqual(OracleBFile obj); Parameters ■ obj The provided OracleBFile object. Return Value Returns true if the current OracleBFile and the provided OracleBFile object refer to the same external LOB. Returns false otherwise. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Note that this method can return true even if the two OracleBFile objects return false for == or Equals() since two different OracleBFile instances can refer to the same external LOB. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-29 OpenFile This instance method opens the BFILE specified by the FileName and DirectoryName. Declaration // C# public void OpenFile(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Many operations, such as Compare(), CopyTo(), Read(), and Search() require that the BFILE be opened using OpenFile before the operation. Calling OpenFile on an opened BFILE is not operational. Read Overrides Stream This instance method reads a specified amount of bytes from the OracleBFile instance and populates the buffer. Declaration // C# public override int Read(byte[ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer to be populated. ■ offset The offset of the byte array buffer to be populated. ■ count The amount of bytes to read. Return Value The return value indicates the number of bytes read from the BFILE, that is, the external LOB. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-30 Oracle Data Provider for .NET Developer’s Guide InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - Either the offset or the count parameter is less than 0 or the offset is greater than or equal to the buffer.Length or the offset and the count together are greater than buffer.Length. Remarks The LOB data is read starting from the position specified by the Position property. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class ReadSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt"); // Open the OracleBFile bFile.OpenFile(); // Read 7 bytes into readBuffer, starting at buffer offset 0 byte[] readBuffer = new byte[7]; int bytesRead = bFile.Read(readBuffer, 0, 7); // Prints "bytesRead = 7" Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 65666768656667" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Close the OracleBFile bFile.CloseFile(); OracleBFile Class Oracle Data Provider for .NET Types Classes 8-31 bFile.Close(); bFile.Dispose(); con.Close(); con.Dispose(); } } Search This instance method searches for a binary pattern in the current instance of an OracleBFile. Declaration // C# public int Search(byte[ ] val, Int64 offset, Int64 nth); Parameters ■ val The binary pattern being searched for. ■ offset The 0-based offset (in bytes) starting from which the OracleBFile is searched. ■ nth The specific occurrence (1-based) of the match for which the offset is returned. Return Value Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - Either the offset is less than 0 or nth is less than or equal to 0 or val.Length is greater than 16383 or nth is greater than or equal to OracleBFile.MaxSize or offset is greater than or equal to OracleBFile.MaxSize. Remarks The limit of the search pattern is 16383 bytes. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Instance Methods 8-32 Oracle Data Provider for .NET Developer’s Guide CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class SearchSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt"); // Open the OracleBFile bFile.OpenFile(); // Search for the 2nd occurrence of a byte pattern {66,67} // starting from byte offset 1 in the OracleBFile byte[] pattern = new byte[2] {66, 67}; long posFound = bFile.Search(pattern, 1, 2); // Prints "posFound = 6" Console.WriteLine("posFound = " + posFound); // Close the OracleBFile bFile.CloseFile(); bFile.Close(); bFile.Dispose(); con.Close(); con.Dispose(); } } Seek Overrides Stream This instance method sets the position on the current LOB stream. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBFile Class Oracle Data Provider for .NET Types Classes 8-33 Declaration // C# public override Int64 Seek(Int64 offset, SeekOrigin origin); Parameters ■ offset A byte offset relative to origin. ■ origin A value of type System.IO.SeekOrigin indicating the reference point used to obtain the new position. Return Value Returns an Int64 that indicates the position. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks If offset is negative, the new position precedes the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position is the position specified by origin. If offset is positive, the new position follows the position specified by origin by the number of bytes specified by offset. SeekOrigin.Begin specifies the beginning of a stream. SeekOrigin.Current specifies the current position within a stream. SeekOrigin.End specifies the end of a stream. Example // Database Setup /* -- User must have CREATE ANY DIRECTORY privilege CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP'; / */ // C# using System; using System.IO; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class SeekSample { static void Main() { // Create MYDIR directory object as indicated above and create a file // MyFile.txt with the text ABCDABC under MYDIR. // Note that the byte representation of the ABCDABC is 65666768656667 OracleBFile Instance Methods 8-34 Oracle Data Provider for .NET Developer’s Guide string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt"); // Open the OracleBFile bFile.OpenFile(); // Set the Position to 2 with respect to SeekOrigin.Begin long newPosition = bFile.Seek(2, SeekOrigin.Begin); // Prints "newPosition = 2" Console.WriteLine("newPosition = " + newPosition); // Prints "bFile.Position = 2" Console.WriteLine("bFile.Position = " + bFile.Position); // Read 2 bytes into readBuffer, starting at buffer offset 1 byte[] readBuffer = new byte[4]; int bytesRead = bFile.Read(readBuffer, 1, 2); // Prints "bytesRead = 2" Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 067680" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Close the OracleBFile bFile.CloseFile(); bFile.Close(); bFile.Dispose(); con.Close(); con.Dispose(); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBFile Class ■ OracleBFile Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-35 OracleBlob Class An OracleBlob object is an object that has a reference to BLOB data. It provides methods for performing operations on BLOBs. Class Inheritance Object MarshalByRefObject Stream OracleBlob Declaration // C# public sealed class OracleBlob : Stream, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleBlobSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob = new OracleBlob(con); // Write 4 bytes from writeBuffer, starting at buffer offset 0 byte[] writeBuffer = new byte[4] {1, 2, 3, 4}; blob.Write(writeBuffer, 0, 4); // Append first 2 bytes from writeBuffer {1, 2} to the oracleBlob blob.Append(writeBuffer, 0, 2); // Prints "blob.Length = 6" Console.WriteLine("blob.Length = " + blob.Length); // Reset the Position for the Read blob.Position = 0; // Read 6 bytes into readBuffer, starting at buffer offset 0 byte[] readBuffer = new byte[6]; int bytesRead = blob.Read(readBuffer, 0, 6); // Prints "bytesRead = 6" OracleBlob Class 8-36 Oracle Data Provider for .NET Developer’s Guide Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 123412" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Search for the 2nd occurrence of a byte pattern '12' // starting from byte offset 0 in the OracleBlob byte[] pattern = new byte[2] {1, 2}; long posFound = blob.Search(pattern, 0, 2); // Prints "posFound = 5" Console.WriteLine("posFound = " + posFound); // Erase 4 bytes of data starting at byte offset 1 // Sets bytes to zero blob.Erase(1, 4); byte[] erasedBuffer = blob.Value; //Prints "erasedBuffer = 100002" Console.Write("erasedBuffer = "); for(int index = 0; index < erasedBuffer.Length; index++) { Console.Write(erasedBuffer[index]); } Console.WriteLine(); blob.Close(); blob.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Members ■ OracleBlob Constructors ■ OracleBlob Static Fields ■ OracleBlob Static Methods ■ OracleBlob Instance Properties ■ OracleBlob Instance Methods OracleBlob Class Oracle Data Provider for .NET Types Classes 8-37 OracleBlob Members OracleBlob members are listed in the following tables: OracleBlob Constructors OracleBlob constructors are listed in Table 8–10. OracleBlob Static Fields OracleBlob static fields are listed in Table 8–11. OracleBlob Static Methods OracleBlob static methods are listed in Table 8–12. OracleBlob Instance Properties OracleBlob instance properties are listed in Table 8–13. Table 8–10 OracleBlob Constructors Constructor Description OracleBlob Constructors Creates an instance of the OracleBlob class (Overloaded) Table 8–11 OracleBlob Static Fields Field Description MaxSize Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes Table 8–12 OracleBlob Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 8–13 OracleBlob Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations be performed CanWrite Indicates whether the LOB object supports writing Connection Indicates the OracleConnection that is used to retrieve and write BLOB data IsEmpty Indicates whether the BLOB is empty or not IsInChunkWriteMode Indicates whether the BLOB has been opened to defer index updates IsTemporary Indicates whether or not the current instance is bound to a temporary BLOB Length Indicates the size of the BLOB data OptimumChunkSize Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation OracleBlob Members 8-38 Oracle Data Provider for .NET Developer’s Guide OracleBlob Instance Methods OracleBlob instance methods are listed in Table 8–14. Position Indicates the current read or write position in the LOB stream Value Returns the data, starting from the first byte in BLOB, as a byte array Table 8–14 OracleBlob Instance Methods Methods Description Append Appends the supplied data to the current OracleBlob instance (Overloaded) BeginChunkWrite Opens the BLOB BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleBlob object Close Closes the current stream and releases any resources associated with it Compare Compares data referenced by the current instance and that of the supplied object CopyTo Copies from the current OracleBlob instance to an OracleBlob object (Overloaded) CreateObjRef Inherited from MarshalByRefObject Dispose Releases resources allocated by this object EndChunkWrite Closes the BLOB referenced by the current OracleBlob instance EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object (Overloaded) Erase Erases data (Overloaded) Flush Not supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializedLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB data referenced by the two OracleBlobs Read Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer ReadByte Inherited from Stream Table 8–13 (Cont.) OracleBlob Instance Properties Properties Description OracleBlob Class Oracle Data Provider for .NET Types Classes 8-39 Search Searches for a binary pattern in the current instance of an OracleBlob Seek Sets the position in the current LOB stream SetLength Trims or truncates the BLOB value to the specified length ToString Inherited from Object Write Writes the supplied buffer into the OracleBlob WriteByte Inherited from Stream See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Members Table 8–14 (Cont.) OracleBlob Instance Methods Methods Description OracleBlob Constructors 8-40 Oracle Data Provider for .NET Developer’s Guide OracleBlob Constructors OracleBlob constructors are listed in Table 8–10. Overload List: ■ OracleBlob(OracleConnection) This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object. ■ OracleBlob(OracleConnection, bool) This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching. OracleBlob(OracleConnection) This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object. Declaration // C# public OracleBlob(OracleConnection con); Parameters ■ con The OracleConnection object. Exceptions InvalidOperationException - The OracleConnection is not opened. Remarks The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly. The temporary BLOB utilizes the provided connection to store BLOB data. Caching is not turned on by this constructor. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-41 OracleBlob(OracleConnection, bool) This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching. Declaration // C# public OracleBlob(OracleConnection con, bool bCaching); Parameters ■ con The OracleConnection object. ■ bCaching A flag for enabling or disabling server-side caching. Exceptions InvalidOperationException - The OracleConnection is not opened. Remarks The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly. The temporary BLOB uses the provided connection to store BLOB data. The bCaching input parameter determines whether or not server-side caching is used. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Static Fields 8-42 Oracle Data Provider for .NET Developer’s Guide OracleBlob Static Fields OracleBlob static fields are listed in Table 8–15. MaxSize The MaxSize field holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes. Declaration // C# public static readonly Int64 MaxSize = 4294967295; Remarks This field can be useful in code that checks whether the operation exceeds the maximum length allowed. Table 8–15 OracleBlob Static Fields Field Description MaxSize Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-43 OracleBlob Static Methods OracleBlob static methods are listed in Table 8–16. Table 8–16 OracleBlob Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Properties 8-44 Oracle Data Provider for .NET Developer’s Guide OracleBlob Instance Properties OracleBlob instance properties are listed in Table 8–17. CanRead Overrides Stream This instance property indicates whether the LOB stream can be read. Declaration // C# public override bool CanRead{get;} Property Value If the LOB stream can be read, returns true; otherwise, returns false. Table 8–17 OracleBlob Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations be performed CanWrite Indicates whether the LOB object supports writing Connection Indicates the OracleConnection that is used to retrieve and write BLOB data IsEmpty Indicates whether the BLOB is empty or not IsInChunkWriteMode Indicates whether the BLOB has been opened to defer index updates IsTemporary Indicates whether or not the current instance is bound to a temporary BLOB Length Indicates the size of the BLOB data OptimumChunkSize Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation Position Indicates the current read or write position in the LOB stream Value Returns the data, starting from the first byte in BLOB, as a byte array See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-45 CanSeek Overrides Stream This instance property indicates whether forward and backward seek operations can be performed. Declaration // C# public override bool CanSeek{get;} Property Value If forward and backward seek operations can be performed, returns true; otherwise, returns false. CanWrite Overrides Stream This instance property indicates whether the LOB object supports writing. Declaration // C# public override bool CanWrite{get;} Property Value If the LOB stream can be written, returns true; otherwise, returns false. Connection This instance property indicates the OracleConnection that is used to retrieve and write BLOB data. Declaration // C# public OracleConnection Connection {get;} Property Value An object of OracleConnection. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Properties 8-46 Oracle Data Provider for .NET Developer’s Guide IsEmpty This instance property indicates whether the BLOB is empty or not. Declaration // C# public bool IsEmpty {get;} Property Value A bool that indicates whether the BLOB is empty. Exceptions ObjectDisposedException - The object is already disposed. IsInChunkWriteMode This instance property indicates whether the BLOB has been opened to defer index updates. Declaration // C# public bool IsInChunkWriteMode{get;} Property Value If the BLOB has been opened, returns true; otherwise, returns false. IsTemporary This instance property indicates whether or not the current instance is bound to a temporary BLOB. Declaration // C# public bool IsTemporary {get;} See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-47 Property Value bool Length Overrides Stream This instance property indicates the size of the BLOB data in bytes. Declaration // C# public override Int64 Length {get;} Property Value A number indicating the size of the BLOB data in bytes. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. OptimumChunkSize This instance property indicates the minimum number of bytes to retrieve or send from the server during a read or write operation. Declaration // C# public int OptimumChunkSize{get;} Property Value A number representing the minimum bytes to retrieve or send. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Properties 8-48 Oracle Data Provider for .NET Developer’s Guide Position Overrides Stream This instance property indicates the current read or write position in the LOB stream. Declaration // C# public override Int64 Position{get; set;} Property Value An Int64 that indicates the read or write position. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The Position is less than 0. Value This instance property returns the data, starting from the first byte in the BLOB, as a byte array. Declaration // C# public Byte[] Value{get;} Property Value A byte array. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The Value is less than 0. Remarks The value of Position is not used or changed by using this property. 2 GB is the maximum byte array length that can be returned by this property. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-49 OracleBlob Instance Methods OracleBlob instance methods are listed in Table 8–18. Table 8–18 OracleBlob Instance Methods Methods Description Append Appends the supplied data to the current OracleBlob instance (Overloaded) BeginChunkWrite Opens the BLOB BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleBlob object Close Closes the current stream and releases any resources associated with it Compare Compares data referenced by the current instance and that of the supplied object CopyTo Copies from the current OracleBlob instance to an OracleBlob object (Overloaded) CreateObjRef Inherited from MarshalByRefObject Dispose Releases resources allocated by this object EndChunkWrite Closes the BLOB referenced by the current OracleBlob instance EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object (Overloaded) Erase Erases data (Overloaded) Flush Not supported GetHashCode Inherited from Object GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializedLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB data referenced by the two OracleBlobs Read Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer ReadByte Inherited from Stream Search Searches for a binary pattern in the current instance of an OracleBlob Seek Sets the position in the current LOB stream SetLength Trims or truncates the BLOB value to the specified length ToString Inherited from Object Write Writes the supplied buffer into the OracleBlob WriteByte Inherited from Stream OracleBlob Instance Methods 8-50 Oracle Data Provider for .NET Developer’s Guide Append Append appends the supplied data to the end of the current OracleBlob instance. Overload List: ■ Append(OracleBlob) This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance. ■ Append(byte[ ], int, int) This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance. Append(OracleBlob) This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance. Declaration // C# public void Append(OracleBlob obj); Parameters ■ obj An object of OracleBlob. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. Remarks No character set conversions are made. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-51 Append(byte[ ], int, int) This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance. Declaration // C# public void Append(byte[] buffer, int offset, int count); Parameters ■ buffer An array of bytes. ■ offset The zero-based byte offset in the buffer from which data is read. ■ count The number of bytes to be appended. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleBlobSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob = new OracleBlob(con); // Write 4 bytes from writeBuffer, starting at buffer offset 0 byte[] writeBuffer = new byte[4] {1, 2, 3, 4}; blob.Write(writeBuffer, 0, 4); // Append first 2 bytes from writeBuffer {1, 2} to the oracleBlob blob.Append(writeBuffer, 0, 2); // Prints "blob.Length = 6" See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-52 Oracle Data Provider for .NET Developer’s Guide Console.WriteLine("blob.Length = " + blob.Length); // Reset the Position for the Read blob.Position = 0; // Read 6 bytes into readBuffer, starting at buffer offset 0 byte[] readBuffer = new byte[6]; int bytesRead = blob.Read(readBuffer, 0, 6); // Prints "bytesRead = 6" Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 123412" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Search for the 2nd occurrence of a byte pattern '12' // starting from byte offset 0 in the OracleBlob byte[] pattern = new byte[2] {1, 2}; long posFound = blob.Search(pattern, 0, 2); // Prints "posFound = 5" Console.WriteLine("posFound = " + posFound); // Erase 4 bytes of data starting at byte offset 1 // Sets bytes to zero blob.Erase(1, 4); byte[] erasedBuffer = blob.Value; //Prints "erasedBuffer = 100002" Console.Write("erasedBuffer = "); for(int index = 0; index < erasedBuffer.Length; index++) { Console.Write(erasedBuffer[index]); } Console.WriteLine(); blob.Close(); blob.Dispose(); con.Close(); con.Dispose(); } } BeginChunkWrite This instance method opens the BLOB. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-53 Declaration // C# public void BeginChunkWrite(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks BeginChunkWrite does not need to be called before manipulating the BLOB data. This is provided for performance reasons. After this method is called, write operations do not cause the domain or function-based index on the column to be updated. Index updates occur only once after EndChunkWrite is called. Clone This instance method creates a copy of an OracleBlob object. Declaration // C# public object Clone(); Return Value An OracleBlob object. Implements ICloneable Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The cloned object has the same property values as that of the object being cloned. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CloneSample See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-54 Oracle Data Provider for .NET Developer’s Guide { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob1 = new OracleBlob(con); // Prints "blob1.Position = 0" Console.WriteLine("blob1.Position = " + blob1.Position); // Set the Position before calling Clone() blob1.Position = 1; // Clone the OracleBlob OracleBlob blob2 = (OracleBlob)blob1.Clone(); // Prints "blob2.Position = 1" Console.WriteLine("blob2.Position = " + blob2.Position); blob1.Close(); blob1.Dispose(); blob2.Close(); blob2.Dispose(); con.Close(); con.Dispose(); } } Close Overrides Stream This instance method closes the current stream and releases any resources associated with it. Declaration // C# public override void Close(); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-55 Compare This instance method compares data referenced by the current instance and that of the supplied object. Declaration // C# public int Compare(Int64 src_offset, OracleBlob obj, Int64 dst_offset, Int64 amount); Parameters ■ src_offset The comparison starting point (in bytes) for the current instance. ■ obj The provided OracleBlob object. ■ dst_offset The comparison starting point (in bytes) for the provided OracleBlob. ■ amount The number of bytes to compare. Return Value Returns a value that is: ■ Less than zero: if the data referenced by the current instance is less than that of the supplied instance ■ Zero: if both objects reference the same data ■ Greater than zero: if the data referenced by the current instance is greater than that of the supplied instance Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0. Remarks The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-56 Oracle Data Provider for .NET Developer’s Guide CopyTo CopyTo copies data from the current instance to the provided OracleBlob object. Overload List: ■ CopyTo(OracleBlob) This instance method copies data from the current instance to the provided OracleBlob object. ■ CopyTo(OracleBlob, Int64) This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset. ■ CopyTo(Int64, OracleBlob, Int64, Int64) This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts. CopyTo(OracleBlob) This instance method copies data from the current instance to the provided OracleBlob object. Declaration // C# public Int64 CopyTo(OracleBlob obj); Parameters ■ obj The OracleBlob object to which the data is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-57 CopyTo(OracleBlob, Int64) This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset. Declaration // C# public Int64 CopyTo(OracleBlob obj, Int64 dst_offset); Parameters ■ obj The OracleBlob object to which the data is copied. ■ dst_offset The offset (in bytes) at which the OracleBlob object is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The dst_offset is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-58 Oracle Data Provider for .NET Developer’s Guide CopyTo(Int64, OracleBlob, Int64, Int64) This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts. Declaration // C# public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset, Int64 amount); Parameters ■ src_offset The offset (in bytes) in the current instance, from which the data is read. ■ obj The OracleBlob object to which the data is copied. ■ dst_offset The offset (in bytes) at which the OracleBlob object is copied. ■ amount The amount of data to be copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0. Remarks If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CopyToSample { static void Main() OracleBlob Class Oracle Data Provider for .NET Types Classes 8-59 { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob1 = new OracleBlob(con); OracleBlob blob2 = new OracleBlob(con); // Write 4 bytes, starting at buffer offset 0 byte[] buffer = new byte[4] {1, 2, 3, 4}; blob1.Write(buffer, 0, 4); // Copy 2 bytes from byte 0 of blob1 to byte 1 of blob2 blob1.CopyTo(0, blob2, 1, 2); byte[] copyBuffer = blob2.Value; //Prints "Value = 012" Console.Write("Value = "); for(int index = 0; index < copyBuffer.Length; index++) { Console.Write(copyBuffer[index]); } Console.WriteLine(); blob1.Close(); blob1.Dispose(); blob2.Close(); blob2.Dispose(); con.Close(); con.Dispose(); } } Dispose This instance method releases resources allocated by this object. Declaration // C# public void Dispose(); Implements IDisposable Remarks Once Dispose() is called, the object of OracleBlob is in an uninitialized state. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-60 Oracle Data Provider for .NET Developer’s Guide Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls may lead to exceptions. The object cannot be reused after being disposed. EndChunkWrite This instance method closes the BLOB referenced by the current OracleBlob instance. Declaration // C# public void EndChunkWrite(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Index updates occur immediately if there is write operation(s) deferred by the BeginChunkWrite method. Erase Erase erases a portion or all data. Overload List: ■ Erase() This instance method erases all data. ■ Erase(Int64, Int64) This instance method erases a specified portion of data. Erase() This instance method erases all data. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-61 Declaration // C# public Int64 Erase(); Return Value The number of bytes erased. Remarks Erase() replaces all data with zero-byte fillers. Erase(Int64, Int64) This instance method erases a specified portion of data. Declaration // C# public Int64 Erase(Int64 offset, Int64 amount); Parameters ■ offset The offset from which to erase. ■ amount The quantity (in bytes) to erase. Return Value The number of bytes erased. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The offset or amount parameter is less than 0. Remarks Replaces the specified amount of data with zero-byte fillers. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-62 Oracle Data Provider for .NET Developer’s Guide IsEqual This instance method compares the LOB data referenced by the two OracleBlobs. Declaration // C# public bool IsEqual(OracleBlob obj); Parameters ■ obj An OracleBlob object. Return Value If the current OracleBlob and the provided OracleBlob refer to the same LOB, returns true. Returns false otherwise. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Note that this method can return true even if the two OracleBlob objects return false for == or Equals() because two different OracleBlob instances can refer to the same LOB. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. Read Overrides Stream This instance method reads a specified amount of bytes from the ODP.NET LOB instance and populates the buffer. Declaration // C# public override int Read(byte[ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer to be populated. ■ offset The starting offset (in bytes) at which the buffer is populated. ■ count See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-63 The amount of bytes to read. Return Value The return value indicates the number of bytes read from the LOB. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset or the count parameter is less than 0. ■ The offset is greater than or equal to the buffer.Length. ■ The offset and the count together are greater than the buffer.Length. Remarks The LOB data is read starting from the position specified by the Position property. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class ReadSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob = new OracleBlob(con); // Write 3 bytes, starting at buffer offset 1 byte[] writeBuffer = new byte[4] {1, 2, 3, 4}; blob.Write(writeBuffer, 1, 3); // Reset the Position for Read blob.Position = 1; // Read 2 bytes into buffer starting at buffer offset 1 byte[] readBuffer = new byte[4]; int bytesRead = blob.Read(readBuffer, 1, 2); // Prints "bytesRead = 2" Console.WriteLine("bytesRead = " + bytesRead); // Prints "readBuffer = 0340" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); OracleBlob Instance Methods 8-64 Oracle Data Provider for .NET Developer’s Guide } Console.WriteLine(); blob.Close(); blob.Dispose(); con.Close(); con.Dispose(); } } Search This instance method searches for a binary pattern in the current instance of an OracleBlob. Declaration // C# public Int64 Search(byte[] val, int64 offset, int64 nth); Parameters ■ val The binary pattern being searched for. ■ offset The 0-based offset (in bytes) starting from which the OracleBlob is searched. ■ nth The specific occurrence (1-based) of the match for which the absolute offset (in bytes) is returned. Return Value Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset is less than 0. ■ The nth is less than or equal to 0. ■ The val.Length is greater than 16383. ■ The nth is greater than or equal to OracleBlob.MaxSize. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-65 ■ The offset is greater than or equal to OracleBlob.MaxSize. Remarks The limit of the search pattern is 16383 bytes. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class SearchSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob = new OracleBlob(con); // Write 7 bytes, starting at buffer offset 0 byte[] buffer = new byte[7] {1, 2, 3, 4, 1, 2, 3}; blob.Write(buffer, 0, 7); // Search for the 2nd occurrence of a byte pattern '23' // starting at offset 1 in the OracleBlob byte[] pattern = new byte[2] {2 ,3}; long posFound = blob.Search(pattern, 1, 2); // Prints "posFound = 6" Console.WriteLine("posFound = " + posFound); blob.Close(); blob.Dispose(); con.Close(); con.Dispose(); } } Seek Overrides Stream This instance method sets the position on the current LOB stream. Declaration // C# public override Int64 Seek(Int64 offset, SeekOrigin origin); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-66 Oracle Data Provider for .NET Developer’s Guide Parameters ■ offset A byte offset relative to origin. ■ origin A value of type System.IO.SeekOrigin indicating the reference point used to obtain the new position. Return Value Returns Int64 for the position. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks If offset is negative, the new position precedes the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position is the position specified by origin. If offset is positive, the new position follows the position specified by origin by the number of bytes specified by offset. SeekOrigin.Begin specifies the beginning of a stream. SeekOrigin.Current specifies the current position within a stream. SeekOrigin.End specifies the end of a stream. SetLength Overrides Stream This instance method trims or truncates the BLOB value to the specified length (in bytes). Declaration // C# public override void SetLength(Int64 newlen); Parameters ■ newlen The desired length of the current stream in bytes. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Class Oracle Data Provider for .NET Types Classes 8-67 InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The newlen parameter is less than 0. Write Overrides Stream This instance method writes the supplied buffer into the OracleBlob. Declaration // C# public override void Write(byte[ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer that provides the data. ■ offset The 0-based offset (in bytes) from which the buffer is read. ■ count The amount of data (in bytes) that is to be written into the OracleBlob. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset or the count is less than 0. ■ The offset is greater than or equal to the buffer.Length. ■ The offset and the count together are greater than buffer.Length. Remarks Destination offset in the OracleBlob can be specified by the Position property. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class WriteSample See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleBlob Instance Methods 8-68 Oracle Data Provider for .NET Developer’s Guide { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleBlob blob = new OracleBlob(con); // Set the Position for the Write blob.Position = 0; // Begin ChunkWrite to improve performance // Index updates occur only once after EndChunkWrite blob.BeginChunkWrite(); // Write to the OracleBlob in 5 chunks of 2 bytes each byte[] b = new byte[2] {1, 2}; for(int index = 0; index < 5; index++) { blob.Write(b, 0, b.Length); } blob.EndChunkWrite(); byte[] chunkBuffer = blob.Value; // Prints "chunkBuffer = 1212121212" Console.Write("chunkBuffer = "); for(int index = 0; index < chunkBuffer.Length; index++) { Console.Write(chunkBuffer[index]); } Console.WriteLine(); blob.Close(); blob.Dispose(); con.Close(); con.Dispose(); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBlob Class ■ OracleBlob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-69 OracleClob Class An OracleClob is an object that has a reference to CLOB data. It provides methods for performing operations on CLOBs. Class Inheritance Object MarshalByRefObject Stream OracleClob Declaration // C# public sealed class OracleClob : Stream, ICloneable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleClobSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Write 4 chars from writeBuffer, starting at buffer offset 0 char[] writeBuffer = new char[4] {'a', 'b', 'c', 'd'}; clob.Write(writeBuffer, 0, 4); // Append first 2 chars from writeBuffer {'a', 'b'} to the oracleClob clob.Append(writeBuffer, 0, 2); // Prints "clob.Length = 12" Console.WriteLine("clob.Length = " + clob.Length); // Reset the Position for the Read clob.Position = 0; Note: The OracleClob object uses the client side character set when retrieving or writing CLOB data using a .NET Framework byte array. OracleClob Class 8-70 Oracle Data Provider for .NET Developer’s Guide // Read 6 chars into readBuffer, starting at buffer offset 0 char[] readBuffer = new char[6]; int charsRead = clob.Read(readBuffer, 0, 6); // Prints "charsRead = 6" Console.WriteLine("charsRead = " + charsRead); // Prints "readBuffer = abcdab" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Search for the 2nd occurrence of a char pattern 'ab' // starting from char offset 0 in the OracleClob char[] pattern = new char[2] {'a', 'b'}; long posFound = clob.Search(pattern, 0, 2); // Prints "posFound = 5" Console.WriteLine("posFound = " + posFound); // Erase 4 chars of data starting at char offset 1 // Sets chars to '' clob.Erase(1, 4); //Prints "clob.Value = a b" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Members ■ OracleClob Constructors ■ OracleClob Static Fields ■ OracleClob Static Methods ■ OracleClob Instance Properties ■ OracleClob Instance Methods OracleClob Class Oracle Data Provider for .NET Types Classes 8-71 OracleClob Members OracleClob members are listed in the following tables: OracleClob Constructors OracleClob constructors are listed in Table 8–19. OracleClob Static Fields OracleClob static fields are listed in Table 8–20. OracleClob Static Methods OracleClob static methods are listed in Table 8–21. OracleClob Instance Properties OracleClob instance properties are listed in Table 8–22. Table 8–19 OracleClob Constructors Constructor Description OracleClob Constructors Creates an instance of the OracleClob class bound to a temporary CLOB (Overloaded) Table 8–20 OracleClob Static Fields Field Description MaxSize Holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes Table 8–21 OracleClob Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 8–22 OracleClob Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations can be performed CanWrite Indicates whether the LOB stream can be written Connection Indicates the OracleConnection that is used to retrieve and write CLOB data IsEmpty Indicates whether the CLOB is empty or not IsInChunkWriteMode Indicates whether or not the CLOB has been opened IsNCLOB Indicates whether the OracleClob object represents an NCLOB. IsTemporary Indicates whether or not the current instance is bound to a temporary CLOB Length Indicates the size of the CLOB data in bytes OracleClob Members 8-72 Oracle Data Provider for .NET Developer’s Guide OracleClob Instance Methods The OracleClob instance methods are listed in Table 8–23. OptimumChunkSize Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation Position Indicates the current read or write position in the LOB stream in bytes Value Returns the data, starting from the first character in the CLOB or NCLOB, as a string Table 8–23 OracleClob Instance Methods Methods Description Append Appends data to the current OracleClob instance (Overloaded) BeginChunkWrite Opens the CLOB BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleClob object Close Closes the current stream and releases resources associated with it Compare Compares data referenced by the current instance to that of the supplied object CopyTo Copies the data to an OracleClob (Overloaded) CreateObjRef Inherited from MarshalByRefObject Dispose Releases resources allocated by this object EndChunkWrite Closes the CLOB referenced by the current OracleClob instance EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object (Overloaded) Erase Erases the specified amount of data (Overloaded) Flush Not supported GetHashCode Returns a hash code for the current instance GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB data referenced by two OracleClobs Read Reads from the current instance (Overloaded) ReadByte Inherited from Stream Table 8–22 (Cont.) OracleClob Instance Properties Properties Description OracleClob Class Oracle Data Provider for .NET Types Classes 8-73 Search Searches for a character pattern in the current instance of OracleClob (Overloaded) Seek Sets the position in the current LOB stream SetLength Trims or truncates the CLOB value ToString Inherited from Object Write Writes the provided buffer into the OracleClob (Overloaded) WriteByte Inherited from Stream See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class Table 8–23 (Cont.) OracleClob Instance Methods Methods Description OracleClob Constructors 8-74 Oracle Data Provider for .NET Developer’s Guide OracleClob Constructors OracleClob constructors create instances of the OracleClob class bound to a temporary CLOB. Overload List: ■ OracleClob(OracleConnection) This constructor creates an instance of the OracleClob class bound to a temporary CLOB with an OracleConnection object. ■ OracleClob(OracleConnection, bool, bool) This constructor creates an instance of the OracleClob class that is bound to a temporary CLOB, with an OracleConnection object, a boolean value for caching, and a boolean value for NCLOB. OracleClob(OracleConnection) This constructor creates an instance of the OracleClob class bound to a temporary CLOB with an OracleConnection object. Declaration // C# public OracleClob(OracleConnection con); Parameters ■ con The OracleConnection object. Exceptions InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The connection must be opened explicitly by the application. OracleClob does not open the connection implicitly. The temporary CLOB utilizes the provided connection to store CLOB data. Caching is not enabled by default. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-75 OracleClob(OracleConnection, bool, bool) This constructor creates an instance of the OracleClob class that is bound to a temporary CLOB, with an OracleConnection object, a boolean value for caching, and a boolean value for NCLOB. Declaration // C# public OracleClob(OracleConnection con, bool bCaching, bool bNCLOB); Parameters ■ con The OracleConnection object connection. ■ bCaching A flag that indicates whether or not server-side caching is enabled. ■ bNCLOB A flag that is set to true if the instance is a NCLOB or false if it is a CLOB. Exceptions InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks The connection must be opened explicitly by the application. OracleClob does not open the connection implicitly. The temporary CLOB or NCLOB uses the provided connection to store CLOB data. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Static Fields 8-76 Oracle Data Provider for .NET Developer’s Guide OracleClob Static Fields OracleClob static fields are listed in Table 8–24. MaxSize The MaxSize field holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes. Declaration // C# public static readonly Int64 MaxSize = 4294967295; Remarks This field is useful in code that checks whether your operation exceeds the maximum length (in bytes) allowed. Table 8–24 OracleClob Static Fields Field Description MaxSize Holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-77 OracleClob Static Methods OracleClob static methods are listed in Table 8–25. Table 8–25 OracleClob Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Properties 8-78 Oracle Data Provider for .NET Developer’s Guide OracleClob Instance Properties OracleClob instance properties are listed in Table 8–26. CanRead Overrides Stream This instance property indicates whether the LOB stream can be read. Declaration // C# public override bool CanRead{get;} Property Value If the LOB stream can be read, returns true; otherwise, returns false. Table 8–26 OracleClob Instance Properties Properties Description CanRead Indicates whether the LOB stream can be read CanSeek Indicates whether forward and backward seek operations can be performed CanWrite Indicates whether the LOB stream can be written Connection Indicates the OracleConnection that is used to retrieve and write CLOB data IsEmpty Indicates whether the CLOB is empty or not IsInChunkWriteMode Indicates whether or not the CLOB has been opened IsNCLOB Indicates whether the OracleClob object represents an NCLOB. IsTemporary Indicates whether or not the current instance is bound to a temporary CLOB Length Indicates the size of the CLOB data in bytes OptimumChunkSize Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation Position Indicates the current read or write position in the LOB stream in bytes Value Returns the data, starting from the first character in the CLOB or NCLOB, as a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-79 CanSeek Overrides Stream This instance property indicates whether forward and backward seek operations can be performed. Declaration // C# public override bool CanSeek{get;} Property Value If forward and backward seek operations can be performed, returns true; otherwise, returns false. CanWrite Overrides Stream This instance property indicates whether the LOB object supports writing. Declaration // C# public override bool CanWrite{get;} Property Value If the LOB stream can be written, returns true; otherwise, returns false. Connection This instance property indicates the OracleConnection that is used to retrieve and write CLOB data. Declaration // C# public OracleConnection Connection {get;} Property Value An OracleConnection. Exceptions ObjectDisposedException - The object is already disposed. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Properties 8-80 Oracle Data Provider for .NET Developer’s Guide IsEmpty This instance property indicates whether the CLOB is empty or not. Declaration // C# public bool IsEmpty {get;} Property Value A bool. Exceptions ObjectDisposedException - The object is already disposed. IsInChunkWriteMode This instance property indicates whether the CLOB has been opened to defer index updates. Declaration // C# public bool IsInChunkWriteMode{get;} Property Value If the CLOB has been opened, returns true; otherwise, returns false. IsNCLOB This instance property indicates whether the OracleClob object represents an NCLOB. Declaration // C# public bool IsNCLOB {get;} See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-81 Property Value A bool. IsTemporary This instance property indicates whether or not the current instance is bound to a temporary CLOB. Declaration // C# public bool IsTemporary {get;} Property Value A bool. Length Overrides Stream This instance property indicates the size of the CLOB data in bytes. Declaration // C# public override Int64 Length {get;} Property Value An Int64 that indicates the size of the CLOB in bytes. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Properties 8-82 Oracle Data Provider for .NET Developer’s Guide OptimumChunkSize This instance property indicates the minimum number of bytes to retrieve or send from the server during a read or write operation. Declaration // C# public int OptimumChunkSize{get;} Property Value A number representing the minimum bytes to retrieve or send. Exceptions ObjectDisposedException - The object is already disposed. Position Overrides Stream This instance property indicates the current read or write position in the LOB stream in bytes. Declaration // C# public override Int64 Position{get; set;} Property Value An Int64 that indicates the read or write position. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The Position is less than 0. Value This instance property returns the data, starting from the first character in the CLOB or NCLOB, as a string. Declaration // C# See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-83 public string Value{get;} Property Value A string. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The Value is less than 0. Remarks The value of Position is neither used nor changed by using this property. The maximum string length that can be returned by this property is 2 GB. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-84 Oracle Data Provider for .NET Developer’s Guide OracleClob Instance Methods The OracleClob instance methods are listed in Table 8–27. Table 8–27 OracleClob Instance Methods Methods Description Append Appends data to the current OracleClob instance (Overloaded) BeginChunkWrite Opens the CLOB BeginRead Inherited from Stream BeginWrite Inherited from Stream Clone Creates a copy of an OracleClob object Close Closes the current stream and releases resources associated with it Compare Compares data referenced by the current instance to that of the supplied object CopyTo Copies the data to an OracleClob (Overloaded) CreateObjRef Inherited from MarshalByRefObject Dispose Releases resources allocated by this object EndChunkWrite Closes the CLOB referenced by the current OracleClob instance EndRead Inherited from Stream EndWrite Inherited from Stream Equals Inherited from Object (Overloaded) Erase Erases the specified amount of data (Overloaded) Flush Not supported GetHashCode Returns a hash code for the current instance GetLifetimeService Inherited from MarshalByRefObject GetType Inherited from Object InitializeLifetimeService Inherited from MarshalByRefObject IsEqual Compares the LOB data referenced by two OracleClobs Read Reads from the current instance (Overloaded) ReadByte Inherited from Stream Search Searches for a character pattern in the current instance of OracleClob (Overloaded) Seek Sets the position in the current LOB stream SetLength Trims or truncates the CLOB value ToString Inherited from Object Write Writes the provided buffer into the OracleClob (Overloaded) WriteByte Inherited from Stream OracleClob Class Oracle Data Provider for .NET Types Classes 8-85 Append This instance method appends data to the current OracleClob instance. Overload List: ■ Append(OracleClob) This instance method appends the CLOB data referenced by the provided OracleClob object to the current OracleClob instance. ■ Append(byte [ ], int, int) This instance method appends data at the end of the CLOB, from the supplied byte array buffer, starting from offset (in bytes) of the supplied byte array buffer. ■ Append(char [ ], int, int) This instance method appends data from the supplied character array buffer to the end of the current OracleClob instance, starting at the offset (in characters) of the supplied character buffer. Append(OracleClob) This instance method appends the CLOB data referenced by the provided OracleClob object to the current OracleClob instance. Declaration // C# public void Append(OracleClob obj); Parameters ■ obj An OracleClob object. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. Remarks No character set conversions are made. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-86 Oracle Data Provider for .NET Developer’s Guide The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. Append(byte [ ], int, int) This instance method appends data at the end of the CLOB, from the supplied byte array buffer, starting from offset (in bytes) of the supplied byte array buffer. Declaration // C# public int Append(byte[] buffer, int offset, int count); Parameters ■ buffer An array of bytes, representing a Unicode string. ■ offset The zero-based byte offset in the buffer from which data is read. ■ count The number of bytes to be appended. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - Either the offset or the count parameter is not even. Remarks Both offset and count must be even numbers for CLOB and NCLOB because every two bytes represent a Unicode character. Append(char [ ], int, int) This instance method appends data from the supplied character array buffer to the end of the current OracleClob instance, starting at the offset (in characters) of the supplied character buffer. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-87 Declaration // C# public void Append(char[] buffer, int offset, int count); Parameters ■ buffer An array of characters. ■ offset The zero-based offset (in characters) in the buffer from which data is read. ■ count The number of characters to be appended. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class AppendSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Append 2 chars {'d', 'e'} to the OracleClob char[] buffer = new char[3] {'d', 'e', 'f'}; clob.Append(buffer, 0, 2); // Prints "clob.Value = de" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } } OracleClob Instance Methods 8-88 Oracle Data Provider for .NET Developer’s Guide BeginChunkWrite This instance method opens the CLOB. Declaration // C# public void BeginChunkWrite(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks BeginChunkWrite does not need to be called before manipulating the CLOB data. This is provided for performance reasons. After this method is called, write operations do not cause the domain or function-based index on the column to be updated. Index updates occur only once after EndChunkWrite is called. Clone This instance method creates a copy of an OracleClob object. Declaration // C# public object Clone(); Return Value An OracleClob object. Implements ICloneable Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-89 Remarks The cloned object has the same property values as that of the object being cloned. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CloneSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob1 = new OracleClob(con); // Prints "clob1.Position = 0" Console.WriteLine("clob1.Position = " + clob1.Position); // Set the Position before calling Clone() clob1.Position = 1; // Clone the OracleClob OracleClob clob2 = (OracleClob)clob1.Clone(); // Prints "clob2.Position = 1" Console.WriteLine("clob2.Position = " + clob2.Position); clob1.Close(); clob1.Dispose(); clob2.Close(); clob2.Dispose(); con.Close(); con.Dispose(); } } Close Overrides Stream This instance method closes the current stream and releases resources associated with it. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-90 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public override void Close(); Compare This instance method compares data referenced by the current instance to that of the supplied object. Declaration // C# public int Compare(Int64 src_offset, OracleClob obj, Int64 dst_offset, Int64 amount); Parameters ■ src_offset The comparison starting point (in characters) for the current instance. ■ obj The provided OracleClob object. ■ dst_offset The comparison starting point (in characters) for the provided OracleClob. ■ amount The number of characters to compare. Return Value The method returns a value that is: ■ Less than zero: if the data referenced by the current instance is less than that of the supplied instance. ■ Zero: if both objects reference the same data. ■ Greater than zero: if the data referenced by the current instance is greater than that of the supplied instance. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. ArgumentOutOfRangeException - Either the src_offset, dst_offset, or amount parameter is less than 0. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-91 Remarks The character set of the two OracleClob objects being compared should be the same for a meaningful comparison. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. CopyTo CopyTo copies data from the current instance to the provided OracleClob object. Overload List: ■ CopyTo(OracleClob) This instance method copies data from the current instance to the provided OracleClob object. ■ CopyTo(OracleClob, Int64) This instance method copies data from the current OracleClob instance to the provided OracleClob object with the specified destination offset. ■ CopyTo(Int64, OracleClob, Int64, Int64) This instance method copies data from the current OracleClob instance to the provided OracleClob object with the specified source offset, destination offset, and character amounts. CopyTo(OracleClob) This instance method copies data from the current instance to the provided OracleClob object. Declaration // C# public Int64 CopyTo(OracleClob obj); Parameters ■ obj The OracleClob object to which the data is copied. Return Value The return value is the amount copied. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-92 Oracle Data Provider for .NET Developer’s Guide Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. CopyTo(OracleClob, Int64) This instance method copies data from the current OracleClob instance to the provided OracleClob object with the specified destination offset. Declaration // C# public Int64 CopyTo(OracleClob obj, Int64 dst_offset); Parameters ■ obj The OracleClob object to which the data is copied. ■ dst_offset The offset (in characters) at which the OracleClob object is copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. ArgumentOutOfRangeException - The dst_offset is less than 0. InvalidOperationException - This exception is thrown if any of the following conditions exist: ■ The OracleConnection is not open or has been closed during the lifetime of the object. ■ The LOB object parameter has a different connection than the object. Remarks If the dst_offset is beyond the end of the OracleClob data, spaces are written into the OracleClob until the dst_offset is met. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-93 The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection; that is, the same OracleConnection object. CopyTo(Int64, OracleClob, Int64, Int64) This instance method copies data from the current OracleClob instance to the provided OracleClob object with the specified source offset, destination offset, and character amounts. Declaration // C# public Int64 CopyTo(Int64 src_offset,OracleClob obj,Int64 dst_offset, Int64 amount); Parameters ■ src_offset The offset (in characters) in the current instance, from which the data is read. ■ obj The OracleClob object to which the data is copied. ■ dst_offset The offset (in characters) at which the OracleClob object is copied. ■ amount The amount of data to be copied. Return Value The return value is the amount copied. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened. ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0. Remarks If the dst_offset is beyond the end of the OracleClob data, spaces are written into the OracleClob until the dst_offset is met. The offsets are 0-based. No character conversion is performed by this operation. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-94 Oracle Data Provider for .NET Developer’s Guide Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class CopyToSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob1 = new OracleClob(con); OracleClob clob2 = new OracleClob(con); // Write 4 chars, starting at buffer offset 0 char[] buffer = new char[4] {'a', 'b', 'c', 'd'}; clob1.Write(buffer, 0, 4); // Copy 2 chars from char 0 of clob1 to char 1 of clob2 clob1.CopyTo(0, clob2, 1, 2); //Prints "clob2.Value = ab" Console.WriteLine("clob2.Value = " + clob2.Value); clob1.Close(); clob1.Dispose(); clob2.Close(); clob2.Dispose(); con.Close(); con.Dispose(); } } Dispose This instance method releases resources allocated by this object. Declaration public void Dispose(); Implements IDisposable See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-95 Remarks The object cannot be reused after being disposed. Although some properties can still be accessed, their values cannot be accountable. Since resources are freed, method calls can lead to exceptions. EndChunkWrite This instance method closes the CLOB referenced by the current OracleClob instance. Declaration // C# public void EndChunkWrite(); Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Index updates occur immediately if write operation(s) are deferred by the BeginChunkWrite method. Erase Erase erases part or all data. Overload List: ■ Erase() This instance method erases all data. ■ Erase(Int64, Int64) This instance method replaces the specified amount of data (in characters) starting from the specified offset with zero-byte fillers (in characters). See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-96 Oracle Data Provider for .NET Developer’s Guide Erase() This instance method erases all data. Declaration // C# public Int64 Erase(); Return Value The number of characters erased. Erase(Int64, Int64) This instance method replaces the specified amount of data (in characters) starting from the specified offset with zero-byte fillers (in characters). Declaration // C# public Int64 Erase(Int64 offset, Int64 amount); Parameters ■ offset The offset. ■ amount The amount of data. Return Value The actual number of characters erased. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The offset or amount parameter is less than 0. GetHashCode Overrides Object See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-97 This method returns a hash code for the current instance. Declaration // C# public override int GetHashCode(); Return Value An int representing a hash code. IsEqual This instance method compares the LOB data referenced by two OracleClobs. Declaration // C# public bool IsEqual(OracleClob obj); Parameters ■ obj An OracleClob object. Return Value Returns true if the current OracleClob and the provided OracleClob refer to the same LOB. Otherwise, returns false. Remarks Note that this method can return true even if the two OracleClob objects returns false for == or Equals() because two different OracleClob instances can refer to the same LOB. The provided object and the current instance must be using the same connection, that is, the same OracleConnection object. Read Read reads a specified amount from the current instance and populates the array buffer. Overload List: ■ Read(byte [ ], int, int) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-98 Oracle Data Provider for .NET Developer’s Guide This instance method reads a specified amount of bytes from the current instance and populates the byte array buffer. ■ Read(char [ ], int, int) This instance method reads a specified amount of characters from the current instance and populates the character array buffer. Read(byte [ ], int, int) Overrides Stream This instance method reads a specified amount of bytes from the current instance and populates the byte array buffer. Declaration // C# public override int Read(byte [ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer that is populated. ■ offset The offset (in bytes) at which the buffer is populated. ■ count The amount of bytes to be read. Return Value The number of bytes read from the CLOB. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks Both offset and count must be even numbers for CLOB and NCLOB because every two bytes represent a Unicode character. The LOB data is read starting from the position specified by the Position property, which must also be an even number. OracleClob is free to return fewer bytes than requested, even if the end of the stream has not been reached. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-99 Read(char [ ], int, int) This instance method reads a specified amount of characters from the current instance and populates the character array buffer. Declaration // C# public int Read(char[ ] buffer, int offset, int count); Parameters ■ buffer The character array buffer that is populated. ■ offset The offset (in characters) at which the buffer is populated. ■ count The amount of characters to be read. Return Value The return value indicates the number of characters read from the CLOB. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset or the count is less than 0. ■ The offset is greater than or equal to the buffer.Length. ■ The offset and the count together are greater than buffer.Length. Remarks Handles all CLOB and NCLOB data as Unicode. The LOB data is read starting from the position specified by the Position property. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class ReadSample See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-100 Oracle Data Provider for .NET Developer’s Guide { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Write 3 chars, starting at buffer offset 1 char[] writeBuffer = new char[4] {'a', 'b', 'c', 'd'}; clob.Write(writeBuffer, 1, 3); // Reset the Position (in bytes) for Read clob.Position = 2; // Read 2 chars into buffer starting at buffer offset 1 char[] readBuffer = new char[4]; int charsRead = clob.Read(readBuffer, 1, 2); // Prints "charsRead = 2" Console.WriteLine("charsRead = " + charsRead); // Prints "readBuffer = cd " Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } } Search Search searches for a character pattern in the current instance of OracleClob. Overload List: ■ Search(byte[ ], Int64, Int64) This instance method searches for a character pattern, represented by the byte array, in the current instance of OracleClob. ■ Search(char[ ], Int64, Int64) This instance method searches for a character pattern in the current instance of OracleClob. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-101 Search(byte[ ], Int64, Int64) This instance method searches for a character pattern, represented by the byte array, in the current instance of OracleClob. Declaration // C# public int Search(byte[ ] val, Int64 offset, Int64 nth); Parameters ■ val A Unicode byte array. ■ offset The 0-based offset (in characters) starting from which the OracleClob is searched. ■ nth The specific occurrence (1-based) of the match for which the absolute offset (in characters) is returned. Return Value Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset is less than 0. ■ The nth is less than or equal to 0. ■ The nth is greater than or equal to OracleClob.MaxSize. ■ The offset is greater than or equal to OracleClob.MaxSize. Remarks The byte[ ] is converted to Unicode before the search is made. The limit of the search pattern is 16383 bytes. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-102 Oracle Data Provider for .NET Developer’s Guide Search(char[ ], Int64, Int64) This instance method searches for a character pattern in the current instance of OracleClob. Declaration // C# public Int64 Search(char [ ] val, Int64 offset, Int64 nth); Parameters ■ val The Unicode string being searched for. ■ offset The 0-based offset (in characters) starting from which the OracleClob is searched. ■ nth The specific occurrence (1-based) of the match for which the absolute offset (in characters) is returned. Return Value Returns the absolute offset of the start of the matched pattern (in characters) for the nth occurrence of the match. Otherwise, 0 is returned. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset is less than 0. ■ The nth is less than or equal to 0. ■ The val.Length doubled is greater than 16383. ■ The nth is greater than or equal to OracleClob.MaxSize. ■ The offset is greater than or equal to OracleClob.MaxSize. Remarks The limit of the search pattern is 16383 bytes. Examples // C# See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-103 using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class SearchSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Write 7 chars, starting at buffer offset 0 char[] buffer = new char[7] {'a', 'b', 'c', 'd', 'a', 'b', 'c'}; clob.Write(buffer, 0, 7); // Search for the 2nd occurrence of a char pattern 'bc' // starting at offset 1 in the OracleBlob char[] pattern = new char[2] {'b', 'c'}; long posFound = clob.Search(pattern, 1, 2); // Prints "posFound = 6" Console.WriteLine("posFound = " + posFound); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } } Seek Overrides Stream This instance method sets the position on the current LOB stream. Declaration // C# public override Int64 Seek(Int64 offset, SeekOrigin origin); Parameters ■ offset A byte offset relative to origin. ■ origin A value of type System.IO.SeekOrigin indicating the reference point used to obtain the new position. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-104 Oracle Data Provider for .NET Developer’s Guide Return Value Returns an Int64 that indicates the position. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. Remarks If offset is negative, the new position precedes the position specified by origin by the number of characters specified by offset. If offset is zero, the new position is the position specified by origin. If offset is positive, the new position follows the position specified by origin by the number of characters specified by offset. SeekOrigin.Begin specifies the beginning of a stream. SeekOrigin.Current specifies the current position within a stream. SeekOrigin.End specifies the end of a stream. SetLength Overrides Stream This instance method trims or truncates the CLOB value to the specified length (in characters). Declaration // C# public override void SetLength(Int64 newlen); Parameters ■ newlen The desired length of the current stream in characters. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - The newlen parameter is greater than 0. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-105 Write This instance method writes data from the provided array buffer into the OracleClob. Overload List: ■ Write(byte[ ], int, int) This instance method writes data from the provided byte array buffer into the OracleClob. ■ Write(char[ ], int, int) This instance method writes data from the provided character array buffer into the OracleClob. Write(byte[ ], int, int) Overrides Stream This instance method writes data from the provided byte array buffer into the OracleClob. Declaration // C# public override void Write(byte[ ] buffer, int offset, int count); Parameters ■ buffer The byte array buffer that represents a Unicode string. ■ offset The offset (in bytes) from which the buffer is read. ■ count The amount of data (in bytes) from the buffer to be written into the OracleClob. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Instance Methods 8-106 Oracle Data Provider for .NET Developer’s Guide ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset or the count is less than 0. ■ The offset is greater than or equal to the buffer.Length. ■ The offset and the count together are greater than the buffer.Length. ■ The offset, the count, or the Position is not even. Remarks Both offset and count must be even numbers for CLOB and NCLOB because every two bytes represent a Unicode character. The LOB data is read starting from the position specified by the Position property. The Position property must be an even number. If necessary, proper data conversion is carried out from the client character set to the database character set. Write(char[ ], int, int) This instance method writes data from the provided character array buffer into the OracleClob. Declaration // C# public void Write(char[ ] buffer, int offset, int count); Parameters ■ buffer The character array buffer that is written to the OracleClob. ■ offset The offset (in characters) from which the buffer is read. ■ count The amount (in characters) from the buffer that is to be written into the OracleClob. Exceptions ObjectDisposedException - The object is already disposed. InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object. ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist: ■ The offset or the count is less than 0. ■ The offset is greater than or equal to the buffer.Length. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleClob Class Oracle Data Provider for .NET Types Classes 8-107 ■ The offset and the count together are greater than buffer.Length. ■ The Position is not even. Remarks Handles all CLOB and NCLOB data as Unicode. The LOB data is read starting from the position specified by the Position property. If necessary, proper data conversion is carried out from the client character set to the database character set. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class WriteSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Set the Position for the Write; clob.Position = 0; // Begin ChunkWrite to improve performance // Index updates occur only once after EndChunkWrite clob.BeginChunkWrite(); // Write to the OracleClob in 5 chunks of 2 chars each char[] c = new char[2] {'a', 'b'}; for (int index = 0; index < 5; index++) { clob.Write(c, 0, c.Length); } clob.EndChunkWrite(); // Prints "clob.Value = ababababab" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } } OracleClob Instance Methods 8-108 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleClob Class ■ OracleClob Members OracleRefCursor Class Oracle Data Provider for .NET Types Classes 8-109 OracleRefCursor Class An OracleRefCursor object represents an Oracle REF CURSOR. Class Inheritance Object MarshalRefByObject OracleRefCursor Declaration // C# public sealed class OracleRefCursor : MarshalRefByObject, IDisposable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // Database Setup /* CREATE OR REPLACE FUNCTION MyFunc(refcur_out OUT SYS_REFCURSOR) RETURN SYS_REFCURSOR IS refcur_ret SYS_REFCURSOR; BEGIN OPEN refcur_ret FOR SELECT * FROM EMP; OPEN refcur_out FOR SELECT * FROM DEPT; RETURN refcur_ret; END MyFunc; / */ // C# using System; using System.Data; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleRefCursorSample { static void Main() { // Example demonstrates how to use REF CURSORs returned from // PL/SQL Stored Procedures or Functions // Create the PL/SQL Function MyFunc as defined above string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); // Create an OracleCommand OracleCommand cmd = new OracleCommand("MyFunc", con); cmd.CommandType = CommandType.StoredProcedure; // Bind the parameters OracleRefCursor Class 8-110 Oracle Data Provider for .NET Developer’s Guide // p1 is the RETURN REF CURSOR bound to SELECT * FROM EMP; OracleParameter p1 = cmd.Parameters.Add("refcur_ret", OracleDbType.RefCursor); p1.Direction = ParameterDirection.ReturnValue; // p2 is the OUT REF CURSOR bound to SELECT * FROM DEPT OracleParameter p2 = cmd.Parameters.Add("refcur_out", OracleDbType.RefCursor); p2.Direction = ParameterDirection.Output; // Execute the command cmd.ExecuteNonQuery(); // Construct an OracleDataReader from the REF CURSOR OracleDataReader reader1 = ((OracleRefCursor)p1.Value).GetDataReader(); // Prints "reader1.GetName(0) = EMPNO" Console.WriteLine("reader1.GetName(0) = " + reader1.GetName(0)); // Construct an OracleDataReader from the REF CURSOR OracleDataReader reader2 = ((OracleRefCursor)p2.Value).GetDataReader(); // Prints "reader2.GetName(0) = DEPTNO" Console.WriteLine("reader2.GetName(0) = " + reader2.GetName(0)); reader1.Close(); reader1.Dispose(); reader2.Close(); reader2.Dispose(); p1.Dispose(); p2.Dispose(); cmd.Dispose(); con.Close(); con.Dispose(); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Members ■ OracleRefCursor Static Methods ■ OracleRefCursor Properties ■ OracleRefCursor Instance Methods OracleRefCursor Class Oracle Data Provider for .NET Types Classes 8-111 OracleRefCursor Members OracleRefCursor members are listed in the following tables: OracleRefCursor Static Methods OracleRefCursor static methods are listed in Table 8–28. OracleRefCursor Properties OracleRefCursor properties are listed in Table 8–29. OracleRefCursor Instance Methods OracleRefCursor instance methods are listed in Table 8–30. Table 8–28 OracleRefCursor Static Methods Methods Description Equals Inherited from Object (Overloaded) Table 8–29 OracleRefCursor Properties Properties Description Connection A reference to the OracleConnection used to fetch the REF CURSOR data Table 8–30 OracleRefCursor Instance Methods Methods Description Dispose Disposes the resources allocated by the OracleRefCursor object Equals Inherited from Object (Overloaded) GetDataReader Returns an OracleDataReader object for the REF CURSOR GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class OracleRefCursor Static Methods 8-112 Oracle Data Provider for .NET Developer’s Guide OracleRefCursor Static Methods OracleRefCursor static methods are listed in Table 8–31. Table 8–31 OracleRefCursor Static Methods Methods Description Equals Inherited from Object (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members OracleRefCursor Class Oracle Data Provider for .NET Types Classes 8-113 OracleRefCursor Properties OracleRefCursor properties are listed in Table 8–32. Connection This property refers to the OracleConnection used to fetch the REF CURSOR data. Declaration // C# public OracleConnection Connection {get;} Property Value An OracleConnection. Exceptions ObjectDisposedException - The object is already disposed. Remarks This property is bound to a REF CURSOR once it is set. After the OracleRefCursor object is created by the constructor, this property is initially null. An OracleRefCursor object can be bound to a REF CURSOR after a command execution. If the connection is closed or returned to the connection pool, the OracleRefCursor is placed in an uninitialized state and no operation can be carried out from it. However, the uninitialized OracleRefCursor can be reassigned to another REF CURSOR. Table 8–32 OracleRefCursor Properties Properties Description Connection A reference to the OracleConnection used to fetch the REF CURSOR data See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members OracleRefCursor Instance Methods 8-114 Oracle Data Provider for .NET Developer’s Guide OracleRefCursor Instance Methods OracleRefCursor instance methods are listed in Table 8–33. Dispose This instance method disposes of the resources allocated by the OracleRefCursor object. Declaration // C# public void Dispose(); Implements IDisposable Remarks The object cannot be reused after being disposed. Once Dispose() is called, the object of OracleRefCursor is in an uninitialized state. Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls can lead to exceptions. GetDataReader This instance method returns an OracleDataReader object for the REF CURSOR. Declaration // C# Table 8–33 OracleRefCursor Instance Methods Methods Description Dispose Disposes the resources allocated by the OracleRefCursor object Equals Inherited from Object (Overloaded) GetDataReader Returns an OracleDataReader object for the REF CURSOR GetHashCode Inherited from Object GetType Inherited from Object ToString Inherited from Object See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members OracleRefCursor Class Oracle Data Provider for .NET Types Classes 8-115 public OracleDataReader GetDataReader(); Return Value OracleDataReader Remarks Using the OracleDataReader, rows can be fetched from the REF CURSOR. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleRefCursor Class ■ OracleRefCursor Members OracleRefCursor Instance Methods 8-116 Oracle Data Provider for .NET Developer’s Guide Oracle Data Provider for .NET Types Structures 9-1 9 Oracle Data Provider for .NET Types Structures This chapter describes the Oracle Data Provider for .NET Types structures. This chapter contains these topics: ■ OracleBinary Structure ■ OracleDate Structure ■ OracleDecimal Structure ■ OracleIntervalDS Structure ■ OracleIntervalYM Structure ■ OracleString Structure ■ OracleTimeStamp Structure ■ OracleTimeStampLTZ Structure ■ OracleTimeStampTZ Structure OracleBinary Structure 9-2 Oracle Data Provider for .NET Developer’s Guide OracleBinary Structure The OracleBinary structure represents a variable-length stream of binary data to be stored in or retrieved from a database. Class Inheritance Object ValueType OracleBinary Declaration // C# public struct OracleBinary : IComparable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using Oracle.DataAccess.Types; class OracleBinarySample { static void Main(string[] args) { // Initialize the OracleBinary structures OracleBinary binary1= new OracleBinary(new byte[] {1,2,3,4,5}); OracleBinary binary2 = new OracleBinary(new byte[] {1,2,3}); OracleBinary binary3 = new OracleBinary(new byte[] {4,5}); OracleBinary binary4 = binary2 + binary3; // Compare binary1 and binary4; they're equal if (binary1 == binary4) Console.WriteLine("The two OracleBinary structs are equal"); else Console.WriteLine("The two OracleBinary structs are different"); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-3 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Members ■ OracleBinary Constructor ■ OracleBinary Static Fields ■ OracleBinary Static Methods ■ OracleBinary Static Operators ■ OracleBinary Static Type Conversion Operators ■ OracleBinary Properties ■ OracleBinary Instance Methods OracleBinary Members 9-4 Oracle Data Provider for .NET Developer’s Guide OracleBinary Members OracleBinary members are listed in the following tables: OracleBinary Constructors OracleBinary constructors are listed in Table 9–1 OracleBinary Static Fields The OracleBinary static fields are listed in Table 9–2. OracleBinary Static Methods The OracleBinary static methods are listed in Table 9–3. OracleBinary Static Operators The OracleBinary static operators are listed in Table 9–4. Table 9–1 OracleBinary Constructors Constructor Description OracleBinary Constructor Instantiates a new instance of OracleBinary structure Table 9–2 OracleBinary Static Fields Field Description Null Represents a null value that can be assigned to an instance of the OracleBinary structure Table 9–3 OracleBinary Static Methods Methods Description Concat Returns the concatenation of two OracleBinary structures Equals Determines if two OracleBinary values are equal (Overloaded) GreaterThan Determines if the first of two OracleBinary values is greater than the second GreaterThanOrEqual Determines if the first of two OracleBinary values is greater than or equal to the second LessThan Determines if the first of two OracleBinary values is less than the second LessThanOrEqual Determines if the first of two OracleBinary values is less than or equal to the second NotEquals Determines if two OracleBinary values are not equal Table 9–4 OracleBinary Static Operators Operator Description operator + Concatenates two OracleBinary values operator == Determines if two OracleBinary values are equal OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-5 OracleBinary Static Type Conversion Operators The OracleBinary static type conversion operators are listed in Table 9–5. OracleBinary Properties The OracleBinary properties are listed in Table 9–6. OracleBinary Instance Methods The OracleBinary instance methods are listed in Table 9–7. operator > Determines if the first of two OracleBinary values is greater than the second operator >= Determines if the first of two OracleBinary values is greater than or equal to the second operator != Determines if two OracleBinary values are not equal operator < Determines if the first of two OracleBinary value is less than the second operator <= Determines if the first of two OracleBinary value is less than or equal to the second Table 9–5 OracleBinary Static Type Conversion Operators Operator Description explicit operator byte[ ] Converts an instance value to a byte array implicit operator OracleBinary Converts an instance value to an OracleBinary structure Table 9–6 OracleBinary Properties Properties Description IsNull Indicates whether the current instance has a null value Item Obtains the particular byte in an OracleBinary structure using an index Length Returns the length of the binary data Value Returns the binary data that is stored in an OracleBinary structure Table 9–7 OracleBinary Instance Methods Methods Description CompareTo Compares the current instance to an object and returns an integer that represents their relative values Equals Determines if two objects contain the same binary data (Overloaded) GetHashCode Returns a hash code for the current instance GetType Inherited from Object ToString Converts the current OracleBinary structure to a string Table 9–4 (Cont.) OracleBinary Static Operators Operator Description OracleBinary Members 9-6 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-7 OracleBinary Constructor The OracleBinary constructor instantiates a new instance of the OracleBinary structure and sets its value to the provided array of bytes. Declaration // C# public OracleBinary(byte[ ] bytes); Parameters ■ bytes A byte array. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Fields 9-8 Oracle Data Provider for .NET Developer’s Guide OracleBinary Static Fields The OracleBinary static fields are listed in Table 9–8. Null This static field represents a null value that can be assigned to an instance of the OracleBinary structure. Declaration // C# public static readonly OracleBinary Null; Table 9–8 OracleBinary Static Fields Field Description Null Represents a null value that can be assigned to an instance of the OracleBinary structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-9 OracleBinary Static Methods The OracleBinary static methods are listed in Table 9–9. Concat This method returns the concatenation of two OracleBinary structures. Declaration // C# public static OracleBinary Concat(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value An OracleBinary. Remarks If either argument has a null value, the returned OracleBinary structure has a null value. Table 9–9 OracleBinary Static Methods Methods Description Concat Returns the concatenation of two OracleBinary structures Equals Determines if two OracleBinary values are equal (Overloaded) GreaterThan Determines if the first of two OracleBinary values is greater than the second GreaterThanOrEqual Determines if the first of two OracleBinary values is greater than or equal to the second LessThan Determines if the first of two OracleBinary values is less than the second LessThanOrEqual Determines if the first of two OracleBinary values is less than or equal to the second NotEquals Determines if two OracleBinary values are not equal See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Methods 9-10 Oracle Data Provider for .NET Developer’s Guide Equals This method determines if two OracleBinary values are equal. Declaration // C# public static bool Equals(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if two OracleBinary values are equal; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. GreaterThan This method determines whether the first of two OracleBinary values is greater than the second. Declaration // C# public static bool GreaterThan(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-11 Return Value Returns true if the first of two OracleBinary values is greater than the second; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. Example // C# using System; using Oracle.DataAccess.Types; class GreaterThanSample { static void Main(string[] args) { OracleBinary binary1 = OracleBinary.Null; OracleBinary binary2 = new OracleBinary(new byte[] {1}); // Compare two OracleBinary structs; binary1 < binary2 if (OracleBinary.GreaterThan(binary1, binary2)) Console.WriteLine("binary1 > binary2"); else Console.WriteLine("binary1 < binary2"); } } GreaterThanOrEqual This method determines whether the first of two OracleBinary values is greater than or equal to the second. Declaration // C# public static bool GreaterThanOrEqual(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Methods 9-12 Oracle Data Provider for .NET Developer’s Guide Return Value Returns true if the first of two OracleBinary values is greater than or equal to the second; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. LessThan This method determines whether the first of two OracleBinary values is less than the second. Declaration // C# public static bool LessThan(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if the first of two OracleBinary values is less than the second; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-13 LessThanOrEqual This method determines whether the first of two OracleBinary values is less than or equal to the second. Declaration // C# public static bool LessThanOrEqual(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if the first of two OracleBinary values is less than or equal to the second; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. NotEquals This method determines whether two OracleBinary values are not equal. Declaration // C# public static bool NotEquals(OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if two OracleBinary values are not equal; otherwise returns false. Remarks The following rules apply to the behavior of this method. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Methods 9-14 Oracle Data Provider for .NET Developer’s Guide ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-15 OracleBinary Static Operators The OracleBinary static operators are listed in Table 9–10. operator + This method concatenates two OracleBinary values. Declaration // C# public static OracleBinary operator + (OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value OracleBinary Remarks If either argument has a null value, the returned OacleBinary structure has a null value. Table 9–10 OracleBinary Static Operators Operator Description operator + Concatenates two OracleBinary values operator == Determines if two OracleBinary values are equal operator > Determines if the first of two OracleBinary values is greater than the second operator >= Determines if the first of two OracleBinary values is greater than or equal to the second operator != Determines if two OracleBinary values are not equal operator < Determines if the first of two OracleBinary value is less than the second operator <= Determines if the first of two OracleBinary value is less than or equal to the second See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Operators 9-16 Oracle Data Provider for .NET Developer’s Guide operator == This method determines if two OracleBinary values are equal. Declaration // C# public static bool operator == (OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if they are the same; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. operator > This method determines if the first of two OracleBinary values is greater than the second. Declaration // C# public static bool operator > (OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-17 Return Value Returns true if the first of two OracleBinary values is greater than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. Example // C# using System; using Oracle.DataAccess.Types; class OperatorSample { static void Main(string[] args) { OracleBinary binary1 = OracleBinary.Null; OracleBinary binary2 = new OracleBinary(new byte[] {1}); // Compare two OracleBinary structs; binary1 < binary2 if (binary1 > binary2) Console.WriteLine("binary1 > binary2"); else Console.WriteLine("binary1 < binary2"); } } operator >= This method determines if the first of two OracleBinary values is greater than or equal to the second. Declaration // C# public static bool operator >= (OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Operators 9-18 Oracle Data Provider for .NET Developer’s Guide Return Value Returns true if the first of two OracleBinary values is greater than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. operator != This method determines if two OracleBinary values are not equal. Declaration // C# public static bool operator != (OracleBinary value1, OracleBinary value2); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if the two OracleBinary values are not equal; otherwise, returns false. operator < This method determines if the first of two OracleBinary values is less than the second. Declaration // C# public static bool operator < ( OracleBinary value1, OracleBinary value2); Parameters ■ value1 See Also: ■ ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-19 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if the first of two OracleBinary values is less than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. operator <= This method determines if the first of two OracleBinary values is less than or equal to the second. Declaration // C# public static bool operator <= (OracleBinary value1, OracleBinary value1); Parameters ■ value1 First OracleBinary. ■ value2 Second OracleBinary. Return Value Returns true if the first of two OracleBinary values is less than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Operators 9-20 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-21 OracleBinary Static Type Conversion Operators The OracleBinary static type conversion operators are listed in Table 9–11. explicit operator byte[ ] This method converts an OracleBinary value to a byte array. Declaration // C# public static explicit operator byte[ ] (OracleBinary val); Parameters ■ val An OracleBinary. Return Value A byte array. Exceptions OracleNullValueException - The OracleBinary structure has a null value. implicit operator OracleBinary This method converts a byte array to an OracleBinary structure. Declaration // C# public static implicit operator OracleBinary(byte[ ] bytes); Parameters ■ bytes Table 9–11 OracleBinary Static Type Conversion Operators Operator Description explicit operator byte[ ] Converts an instance value to a byte array implicit operator OracleBinary Converts an instance value to an OracleBinary structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Static Type Conversion Operators 9-22 Oracle Data Provider for .NET Developer’s Guide A byte array. Return Value OracleBinary See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-23 OracleBinary Properties The OracleBinary properties are listed in Table 9–12. IsNull This property indicates whether the current instance has a null value. Declaration // C# public bool IsNull {get;} Property Value Returns true if the current instance has a null value; otherwise returns false. Item This property obtains the particular byte in an OracleBinary structure using an index. Declaration // C# public byte this[int index] {get;} Property Value A byte in the specified index. Exceptions OracleNullValueException - The current instance has a null value. Table 9–12 OracleBinary Properties Properties Description IsNull Indicates whether the current instance has a null value Item Obtains the particular byte in an OracleBinary structure using an index Length Returns the length of the binary data Value Returns the binary data that is stored in an OracleBinary structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Properties 9-24 Oracle Data Provider for .NET Developer’s Guide Example // C# using System; using Oracle.DataAccess.Types; class ItemSample { static void Main(string[] args) { OracleBinary binary = new OracleBinary(new byte[] {1,2,3,4}); // Prints the value 4 Console.WriteLine(binary[binary.Length - 1]); } } Length This property returns the length of the binary data. Declaration // C# public int length {get;} Property Value Length of the binary data. Exceptions OracleNullValueException - The current instance has a null value. Example // C# using System; using Oracle.DataAccess.Types; class LengthSample { static void Main(string[] args) { OracleBinary binary = new OracleBinary(new byte[] {1,2,3,4}); // Prints the value 4 Console.WriteLine(binary.Length); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-25 Value This property returns the binary data that is stored in the OracleBinary structure. Declaration // C# public byte[] Value {get;} Property Value Binary data. Exceptions OracleNullValueException - The current instance has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Instance Methods 9-26 Oracle Data Provider for .NET Developer’s Guide OracleBinary Instance Methods The OracleBinary instance methods are listed in Table 9–13. CompareTo This method compares the current instance to an object and returns an integer that represents their relative values Declaration // C# public int CompareTo(object obj); Parameters ■ obj The object being compared. Return Value The method returns a number that is: ■ Less than zero: if the current OracleBinary instance value is less than obj. ■ Zero: if the current OracleBinary instance and obj values have the same binary data. ■ Greater than zero: if the current OracleBinary instance value is greater than obj. Implements IComparable Exceptions ArgumentException - The parameter is not of type OracleBinary. Table 9–13 OracleBinary Instance Methods Methods Description CompareTo Compares the current instance to an object and returns an integer that represents their relative values Equals Determines if two objects contain the same binary data (Overloaded) GetHashCode Returns a hash code for the current instance GetType Inherited from Object ToString Converts the current OracleBinary structure to a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Structure Oracle Data Provider for .NET Types Structures 9-27 Remarks The following rules apply to the behavior of this method. ■ The comparison must be between OracleBinarys. For example, comparing an OracleBinary instance with an OracleTimeStamp instance is not allowed. When an OracleBinary is compared with a different type, an ArgumentException is thrown. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. Example // C# using System; using Oracle.DataAccess.Types; class CompareToSample { static void Main(string[] args) { OracleBinary binary1 = new OracleBinary(new byte[] {1,2,3}); OracleBinary binary2 = new OracleBinary(new byte[] {1,2,3,4}); // Compare if (binary1.CompareTo(binary2) == 0) Console.WriteLine("binary1 is the same as binary2"); else Console.WriteLine("binary1 is different from binary2"); } } Equals This method determines whether an object is an instance of OracleBinary, and has the same binary data as the current instance. Declaration // C# public override bool Equals(object obj); Parameters ■ obj The object being compared. Return Value Returns true if obj is an instance of OracleBinary, and has the same binary data as the current instance; otherwise, returns false. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleBinary Instance Methods 9-28 Oracle Data Provider for .NET Developer’s Guide Remarks The following rules apply to the behavior of this method. ■ Any OracleBinary that has a value is greater than an OracleBinary that has a null value. ■ Two OracleBinarys that contain a null value are equal. GetHashCode Overrides Object This method returns a hash code for the OracleBinary instance. Declaration // C# public override int GetHashCode(); Return Value An int that represents the hash. ToString Overrides Object This method converts an OracleBinary instance to a string instance. Declaration // C# public override string ToString(); Return Value string Remarks If the current OracleBinary instance has a null value, the returned string "null". See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleBinary Structure ■ OracleBinary Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-29 OracleDate Structure The OracleDate structure represents the Oracle DATE datatype to be stored in or retrieved from a database. Each OracleDate stores the following information: year, month, day, hour, minute, and second. Class Inheritance Object ValueType OracleDate Declaration // C# public struct OracleDate : IComparable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using Oracle.DataAccess.Types; using Oracle.DataAccess.Client; class OracleDateSample { static void Main(string[] args) { // Initialize the dates to the lower and upper boundaries OracleDate date1 = OracleDate.MinValue; OracleDate date2 = OracleDate.MaxValue; OracleDate date3 = new OracleDate(DateTime.MinValue); OracleDate date4 = new OracleDate(DateTime.MaxValue); // Set the thread's DateFormat for output OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "DD-MON-YYYY BC"; OracleGlobalization.SetThreadInfo(info); // Print the lower and upper boundaries Console.WriteLine("OracleDate ranges from\n{0}\nto\n{1}\n", date1, date2); Console.WriteLine(".NET DateTime ranges from\n{0}\nto\n{1}\n", date3, date4); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll OracleDate Structure 9-30 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Members ■ OracleDate Constructors ■ OracleDate Static Fields ■ OracleDate Static Methods ■ OracleDate Static Operators ■ OracleDate Static Type Conversions ■ OracleDate Properties ■ OracleDate Methods OracleDate Structure Oracle Data Provider for .NET Types Structures 9-31 OracleDate Members OracleDate members are listed in the following tables: OracleDate Constructors OracleDate constructors are listed in Table 9–14 OracleDate Static Fields The OracleDate static fields are listed in Table 9–15. OracleDate Static Methods The OracleDate static methods are listed in Table 9–16. OracleDate Static Operators The OracleDate static operators are listed in Table 9–17. Table 9–14 OracleDate Constructors Constructor Description OracleDate Constructors Instantiates a new instance of OracleDate structure (Overloaded) Table 9–15 OracleDate Static Fields Field Description MaxValue Represents the maximum valid date for an OracleDate structure, which is December 31, 9999 23:59:59 MinValue Represents the minimum valid date for an OracleDate structure, which is January 1, -4712 0:0:0 Null Represents a null value that can be assigned to the value of an OracleDate structure instance Table 9–16 OracleDate Static Methods Methods Description Equals Determines if two OracleDate values are equal (Overloaded) GreaterThan Determines if the first of two OracleDate values is greater than the second GreaterThanOrEqual Determines if the first of two OracleDate values is greater than or equal to the second LessThan Determines if the first of two OracleDate values is less than the second LessThanOrEqual Determines if the first of two OracleDate values is less than or equal to the second NotEquals Determines if two OracleDate values are not equal GetSysDate Returns an OracleDate structure that represents the current date and time Parse Returns an OracleDate structure and sets its value using a string OracleDate Members 9-32 Oracle Data Provider for .NET Developer’s Guide OracleDate Static Type Conversions The OracleDate static type conversions are listed in Table 9–18. OracleDate Properties The OracleDate properties are listed in Table 9–19. OracleDate Methods The OracleDate methods are listed in Table 9–20. Table 9–17 OracleDate Static Operators Operator Description operator == Determines if two OracleDate values are the same operator > Determines if the first of two OracleDate values is greater than the second operator >= Determines if the first of two OracleDate values is greater than or equal to the second operator != Determines if the two OracleDate values are not equal operator < Determines if the first of two OracleDate values is less than the second operator <= Determines if the first of two OracleDate values is less than or equal to the second Table 9–18 OracleDate Static Type Conversions Operator Description explicit operator DateTime Converts a structure to a DateTime structure explicit operator OracleDate Converts a structure to an OracleDate structure (Overloaded) Table 9–19 OracleDate Properties Properties Description BinData Gets an array of bytes that represents an Oracle DATE in Oracle internal format Day Gets the day component of an OracleDate method IsNull Indicates whether the current instance has a null value Hour Gets the hour component of an OracleDate Minute Gets the minute component of an OracleDate Month Gets the month component of an OracleDate Second Gets the second component of an OracleDate Value Gets the date and time that is stored in the OracleDate structure Year Gets the year component of an OracleDate OracleDate Structure Oracle Data Provider for .NET Types Structures 9-33 Table 9–20 OracleDate Methods Methods Description CompareTo Compares the current OracleDate instance to an object, and returns an integer that represents their relative values Equals Determines whether an object has the same date and time as the current OracleDate instance (Overloaded) GetHashCode Returns a hash code for the OracleDate instance GetDaysBetween Calculates the number of days between the current OracleDate instance and an OracleDate structure GetType Inherited from Object ToOracleTimeStamp Converts the current OracleDate structure to an OracleTimeStamp structure ToString Converts the current OracleDate structure to a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure OracleDate Constructors 9-34 Oracle Data Provider for .NET Developer’s Guide OracleDate Constructors The OracleDate constructors instantiates a new instance of the OracleDate structure. Overload List: ■ OracleDate(DateTime) This constructor creates a new instance of the OracleDate structure and sets its value for date and time using the supplied DateTime value. ■ OracleDate(string) This constructor creates a new instance of the OracleDate structure and sets its value using the supplied string. ■ OracleDate(int, int, int) This constructor creates a new instance of the OracleDate structure and set its value for date using the supplied year, month, and day. ■ OracleDate(int, int, int, int, int, int) This constructor creates a new instance of the OracleDate structure and set its value for time using the supplied year, month, day, hour, minute, and second. ■ OracleDate(byte [ ]) This constructor creates a new instance of the OracleDate structure and sets its value to the provided byte array, which is in the internal Oracle DATE format. OracleDate(DateTime) This constructor creates a new instance of the OracleDate structure and sets its value for date and time using the supplied DateTime value. Declaration // C# public OracleDate (DateTime dt); Parameters ■ dt The provided DateTime value. Remarks The OracleDate structure only supports up to a second precision. The time value in the provided DateTime structure that has a precision smaller than second is ignored. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-35 OracleDate(string) This constructor creates a new instance of the OracleDate structure and sets its value using the supplied string. Declaration // C# public OracleDate (string dateStr); Parameters ■ dateStr A string that represents an Oracle DATE. Exceptions ArgumentException - The dateStr is an invalid string representation of an Oracle DATE or the dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents Oracle's NLS_ DATE_FORMAT parameter. ArgumentNullException - The dateStr is null. Remarks The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used. Example // C# using System; using Oracle.DataAccess.Types; using Oracle.DataAccess.Client; class OracleDateSample { static void Main(string[] args) { // Set the thread's DateFormat for the OracleDate constructor OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "YYYY-MON-DD"; OracleGlobalization.SetThreadInfo(info); // construct OracleDate from a string using the DateFormat specified. OracleDate date = new OracleDate("1999-DEC-01"); // Set a different DateFormat for the thread info.DateFormat = "MM/DD/YYYY"; OracleGlobalization.SetThreadInfo(info); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Constructors 9-36 Oracle Data Provider for .NET Developer’s Guide // Print "12/01/1999" Console.WriteLine(date.ToString()); } } OracleDate(int, int, int) This constructor creates a new instance of the OracleDate structure and set its value for date using the supplied year, month, and day. Declaration // C# public OracleDate (int year, int month, int day); Parameters ■ year The supplied year. Range of year is (-4712 to 9999). ■ month The supplied month. Range of month is (1 to 12). ■ day The supplied day. Range of day is (1 to 31). Exceptions ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range. ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleDate (that is, the day is out of range for the month). OracleDate(int, int, int, int, int, int) This constructor creates a new instance of the OracleDate structure and set its value for time using the supplied year, month, day, hour, minute, and second. Declaration // C# See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members ■ "OracleGlobalization Class" on page 6-2 ■ Oracle Database SQL Reference for further information on date format elements See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-37 public OracleDate (int year, int month, int day, int hour, int minute, int second); Parameters ■ year The supplied year. Range of year is (-4712 to 9999). ■ month The supplied month. Range of month is (1 to 12). ■ day The supplied day. Range of day is (1 to 31). ■ hour The supplied hour. Range of hour is (0 to 23). ■ minute The supplied minute. Range of minute is (0 to 59). ■ second The supplied second. Range of second is (0 to 59). Exceptions ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range. ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleDate (that is, the day is out of range for the month). OracleDate(byte [ ]) This constructor creates a new instance of the OracleDate structure and sets its value to the provided byte array, which is in the internal Oracle DATE format. Declaration // C# public OracleDate(byte [] bytes); Parameters ■ bytes A byte array that represents Oracle DATE in the internal Oracle DATE format. Exceptions ArgumentException - bytes is null or bytes is not in internal Oracle DATE format or bytes is not a valid Oracle DATE. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Constructors 9-38 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-39 OracleDate Static Fields The OracleDate static fields are listed in Table 9–21. MaxValue This static field represents the maximum valid date for an OracleDate structure, which is December 31, 9999 23:59:59. Declaration // C# public static readonly OracleDate MaxValue; MinValue This static field represents the minimum valid date for an OracleDate structure, which is January 1, -4712. Declaration // C# public static readonly OracleDate MinValue; Table 9–21 OracleDate Static Fields Field Description MaxValue Represents the maximum valid date for an OracleDate structure, which is December 31, 9999 23:59:59 MinValue Represents the minimum valid date for an OracleDate structure, which is January 1, -4712 0:0:0 Null Represents a null value that can be assigned to the value of an OracleDate structure instance See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Fields 9-40 Oracle Data Provider for .NET Developer’s Guide Null This static field represents a null value that can be assigned to the value of an OracleDate instance. Declaration // C# public static readonly OracleDate Null; See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-41 OracleDate Static Methods The OracleDate static methods are listed in Table 9–22. Equals Overloads Object This method determines if two OracleDate values are equal. Declaration // C# public static bool Equals(OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if two OracleDate values are equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. Table 9–22 OracleDate Static Methods Methods Description Equals Determines if two OracleDate values are equal (Overloaded) GreaterThan Determines if the first of two OracleDate values is greater than the second GreaterThanOrEqual Determines if the first of two OracleDate values is greater than or equal to the second LessThan Determines if the first of two OracleDate values is less than the second LessThanOrEqual Determines if the first of two OracleDate values is less than or equal to the second NotEquals Determines if two OracleDate values are not equal GetSysDate Returns an OracleDate structure that represents the current date and time Parse Returns an OracleDate structure and sets its value using a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Methods 9-42 Oracle Data Provider for .NET Developer’s Guide ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. GreaterThan This method determines if the first of two OracleDate values is greater than the second. Declaration // C# public static bool GreaterThan(OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is greater than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. GreaterThanOrEqual This method determines if the first of two OracleDate values is greater than or equal to the second. Declaration // C# public static bool GreaterThanOrEqual(OracleDate value1, OracleDate value2); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-43 Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is greater than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. LessThan This method determines if the first of two OracleDate values is less than the second. Declaration // C# public static bool LessThan(OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is less than the second. Otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Methods 9-44 Oracle Data Provider for .NET Developer’s Guide LessThanOrEqual This method determines if the first of two OracleDate values is less than or equal to the second. Declaration // C# public static bool LessThanOrEqual(OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is less than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. NotEquals This method determines if two OracleDate values are not equal. Declaration // C# public static bool NotEquals(OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-45 Second OracleDate. Return Value Returns true if two OracleDate values are not equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. GetSysDate This method gets an OracleDate structure that represents the current date and time. Declaration // C# public static OracleDate GetSysDate (); Return Value An OracleDate structure that represents the current date and time. Parse This method gets an OracleDate structure and sets its value for date and time using the supplied string. Declaration // C# public static OracleDate Parse (string dateStr); Parameters ■ dateStr A string that represents an Oracle DATE. Return Value An OracleDate structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Methods 9-46 Oracle Data Provider for .NET Developer’s Guide Exceptions ArgumentException - The dateStr is an invalid string representation of an Oracle DATE or the dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents Oracle's NLS_ DATE_FORMAT parameter. ArgumentNullException - The dateStr is null. Remarks The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used. Example // C# using System; using Oracle.DataAccess.Types; using Oracle.DataAccess.Client; class ParseSample { static void Main(string[] args) { // Set the thread's DateFormat for the OracleDate constructor OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "YYYY-MON-DD"; OracleGlobalization.SetThreadInfo(info); // Construct OracleDate from a string using the DateFormat specified OracleDate date = OracleDate.Parse("1999-DEC-01"); // Set a different DateFormat on the thread for ToString() info.DateFormat = "MM-DD-YY"; OracleGlobalization.SetThreadInfo(info); // Print "12-01-1999" Console.WriteLine(date.ToString()); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 ■ Oracle Database SQL Reference for further information on datetime format elements OracleDate Structure Oracle Data Provider for .NET Types Structures 9-47 OracleDate Static Operators The OracleDate static operators are listed in Table 9–23. operator == This method determines if two OracleDate values are the same. Declaration // C# public static bool operator == (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if they are the same; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. Table 9–23 OracleDate Static Operators Operator Description operator == Determines if two OracleDate values are the same operator > Determines if the first of two OracleDate values is greater than the second operator >= Determines if the first of two OracleDate values is greater than or equal to the second operator != Determines if the two OracleDate values are not equal operator < Determines if the first of two OracleDate values is less than the second operator <= Determines if the first of two OracleDate values is less than or equal to the second See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Operators 9-48 Oracle Data Provider for .NET Developer’s Guide operator > This method determines if the first of two OracleDate values is greater than the second. Declaration // C# public static bool operator > (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is greater than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. operator >= This method determines if the first of two OracleDate values is greater than or equal to the second. Declaration // C# public static bool operator >= (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-49 Second OracleDate. Return Value Returns true if the first of two OracleDate values is greater than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. operator != This method determines if the two OracleDate values are not equal. Declaration // C# public static bool operator != (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the two OracleDate values are not equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. operator < This method determines if the first of two OracleDate values is less than the second. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Operators 9-50 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public static bool operator < (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is less than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. operator <= This method determines if the first of two OracleDate values is less than or equal to the second. Declaration // C# public static bool operator <= (OracleDate value1, OracleDate value2); Parameters ■ value1 First OracleDate. ■ value2 Second OracleDate. Return Value Returns true if the first of two OracleDate values is less than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-51 ■ Two OracleDates that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Type Conversions 9-52 Oracle Data Provider for .NET Developer’s Guide OracleDate Static Type Conversions The OracleDate static type conversions are listed in Table 9–24. explicit operator DateTime This method converts an OracleDate structure to a DateTime structure. Declaration // C# public static explicit operator DateTime(OracleDate val); Parameters ■ val An OracleDate structure. Return Value A DateTime structure. explicit operator OracleDate explicit operator OracleDate converts the provided structure to a OracleDate structure. Overload List: ■ explicit operator OracleDate(DateTime) This method converts a DateTime structure to an OracleDate structure. ■ explicit operator OracleDate(OracleTimeStamp) This method converts an OracleTimeStamp structure to an OracleDate structure. ■ explicit operator OracleDate(string) Table 9–24 OracleDate Static Type Conversions Operator Description explicit operator DateTime Converts a structure to a DateTime structure explicit operator OracleDate Converts a structure to an OracleDate structure (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-53 This method converts the supplied string to an OracleDate structure. explicit operator OracleDate(DateTime) This method converts a DateTime structure to an OracleDate structure. Declaration // C# public static explicit operator OracleDate(DateTime dt); Parameters ■ dt A DateTime structure. Return Value An OracleDate structure. explicit operator OracleDate(OracleTimeStamp) This method converts an OracleTimeStamp structure to an OracleDate structure. Declaration // C# public explicit operator OracleDate(OracleTimeStamp ts); Parameters ■ ts OracleTimeStamp Return Value The returned OracleDate structure contains the date and time in the OracleTimeStamp structure. Remarks The precision of the OracleTimeStamp value can be lost during the conversion. If the OracleTimeStamp structure has a null value, the returned OracleDate structure also has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Static Type Conversions 9-54 Oracle Data Provider for .NET Developer’s Guide explicit operator OracleDate(string) This method converts the supplied string to an OracleDate structure. Declaration // C# public explicit operator OracleDate (string dateStr); Parameters ■ dateStr A string representation of an Oracle DATE. Return Value The returned OracleDate structure contains the date and time in the string dateStr. Exceptions ArgumentNullException - The dateStr is null. ArgumentException - This exception is thrown if any of the following conditions exist: ■ The dateStr is an invalid string representation of an Oracle DATE. ■ The dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents Oracle's NLS_ DATE_FORMAT parameter. Remarks The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleDateSample { static void Main(string[] args) { // Set the thread's DateFormat to a specific format OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "YYYY-MON-DD"; OracleGlobalization.SetThreadInfo(info); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-55 // Construct OracleDate from a string using the DateFormat specified OracleDate date = (OracleDate)"1999-DEC-01"; // Set a different DateFormat on the thread for ToString() info.DateFormat = "MON DD YY"; OracleGlobalization.SetThreadInfo(info); // Prints "DEC 01 99" Console.WriteLine(date.ToString()); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDate Properties 9-56 Oracle Data Provider for .NET Developer’s Guide OracleDate Properties The OracleDate properties are listed in Table 9–25. BinData This property gets a array of bytes that represents an Oracle DATE in Oracle internal format. Declaration // C# public byte[] BinData{get;} Property Value An array of bytes. Exceptions OracleNullValueException - OracleDate has a null value. Day This property gets the day component of an OracleDate. Table 9–25 OracleDate Properties Properties Description BinData Gets an array of bytes that represents an Oracle DATE in Oracle internal format Day Gets the day component of an OracleDate method IsNull Indicates whether the current instance has a null value Hour Gets the hour component of an OracleDate Minute Gets the minute component of an OracleDate Month Gets the month component of an OracleDate Second Gets the second component of an OracleDate Value Gets the date and time that is stored in the OracleDate structure Year Gets the year component of an OracleDate See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-57 Declaration // C# public int Day{get;} Property Value A number that represents the day. Range of Day is (1 to 31). Exceptions OracleNullValueException - OracleDate has a null value. IsNull This property indicates whether the current instance has a null value. Declaration // C# public bool IsNull{get;} Property Value Returns true if the current instance has a null value; otherwise, returns false. Hour This property gets the hour component of an OracleDate. Declaration // C# public int Hour {get;} Property Value A number that represents Hour. Range of Hour is (0 to 23). Exceptions OracleNullValueException - OracleDate has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Properties 9-58 Oracle Data Provider for .NET Developer’s Guide Minute This property gets the minute component of an OracleDate. Declaration // C# public int Minute {get;} Property Value A number that represents Minute. Range of Minute is (0 to 59). Exceptions OracleNullValueException - OracleDate has a null value. Month This property gets the month component of an OracleDate. Declaration // C# public int Month {get;} Property Value A number that represents Month. Range of Month is (1 to 12). Exceptions OracleNullValueException - OracleDate has a null value. Second This property gets the second component of an OracleDate. Declaration // C# public int Second {get;} Property Value A number that represents Second. Range of Second is (0 to 59). Exceptions OracleNullValueException - OracleDate has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-59 Value This property specifies the date and time that is stored in the OracleDate structure. Declaration // C# public DateTime Value {get;} Property Value A DateTime. Exceptions OracleNullValueException - OracleDate has a null value. Year This property gets the year component of an OracleDate. Declaration // C# public int Year {get;} Property Value A number that represents Year. Range of Year is (-4712 to 9999). Exceptions OracleNullValueException - OracleDate has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Methods 9-60 Oracle Data Provider for .NET Developer’s Guide OracleDate Methods The OracleDate methods are listed in Table 9–26. CompareTo This method compares the current OracleDate instance to an object, and returns an integer that represents their relative values. Declaration // C# public int CompareTo(object obj); Parameters ■ obj An object. Return Value The method returns: ■ Less than zero: if the current OracleDate instance value is less than that of obj. ■ Zero: if the current OracleDate instance and obj values are equal. ■ Greater than zero: if the current OracleDate instance value is greater than obj. Implements IComparable Exceptions ArgumentException - The obj parameter is not an instance of OracleDate. Table 9–26 OracleDate Methods Methods Description CompareTo Compares the current OracleDate instance to an object, and returns an integer that represents their relative values Equals Determines whether an object has the same date and time as the current OracleDate instance (Overloaded) GetHashCode Returns a hash code for the OracleDate instance GetDaysBetween Calculates the number of days between the current OracleDate instance and an OracleDate structure GetType Inherited from Object ToOracleTimeStamp Converts the current OracleDate structure to an OracleTimeStamp structure ToString Converts the current OracleDate structure to a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-61 Remarks The following rules apply to the behavior of this method. ■ The comparison must be between OracleDates. For example, comparing an OracleDate instance with an OracleBinary instance is not allowed. When an OracleDate is compared with a different type, an ArgumentException is thrown. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. Equals This method determines whether an object has the same date and time as the current OracleDate instance. Declaration // C# public override bool Equals( object obj); Parameters ■ obj An object. Return Value Returns true if obj has the same type as the current instance and represents the same date and time; otherwise returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDate that has a value compares greater than an OracleDate that has a null value. ■ Two OracleDates that contain a null value are equal. GetHashCode Overrides Object This method returns a hash code for the OracleDate instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Methods 9-62 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public override int GetHashCode(); Return Value A number that represents the hash code. GetDaysBetween This method calculates the number of days between the current OracleDate instance and the supplied OracleDate structure. Declaration // C# public int GetDaysBetween (OracleDate val); Parameters ■ val An OracleDate structure. Return Value The number of days between the current OracleDate instance and the OracleDate structure. Exceptions OracleNullValueException - The current instance or the supplied OracleDate structure has a null value. ToOracleTimeStamp This method converts the current OracleDate structure to an OracleTimeStamp structure. Declaration // C# public OracleTimeStamp ToOracleTimeStamp(); Return Value An OracleTimeStamp structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Structure Oracle Data Provider for .NET Types Structures 9-63 Remarks The returned OracleTimeStamp structure has date and time in the current instance. If the OracleDate instance has a null value, the returned OracleTimeStamp structure has a null value. ToString Overrides ValueType This method converts the current OracleDate structure to a string. Declaration // C# public override string ToString(); Return Value A string. Remarks The returned value is a string representation of the OracleDate in the format specified by the thread's OracleGlobalization.DateFormat property. The names and abbreviations used for months and days are in the language specified by the thread's OracleGlobalization.DateLanguage and OracleGlobalization.Calendar properties. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class ToStringSample { static void Main(string[] args) { // Set the thread's DateFormat to a specific format OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.DateFormat = "YYYY-MON-DD"; OracleGlobalization.SetThreadInfo(info); // Construct OracleDate from a string using the DateFormat specified OracleDate date = (OracleDate)"1999-DEC-01"; // Set a different DateFormat on the thread for ToString() info.DateFormat = "YYYY/MM/DD"; OracleGlobalization.SetThreadInfo(info); // Prints "1999/12/01" See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members OracleDate Methods 9-64 Oracle Data Provider for .NET Developer’s Guide Console.WriteLine(date.ToString()); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDate Structure ■ OracleDate Members ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-65 OracleDecimal Structure The OracleDecimal structure represents an Oracle NUMBER in the database or any Oracle numeric value. Class Inheritance Object ValueType OracleDecimal Declaration // C# public struct OracleDecimal : IComparable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Remarks OracleDecimal can store up to 38 precision, while the .NET Decimal datatype can only hold up to 28 precision. When accessing the OracleDecimal.Value property from an OracleDecimal that has a value greater than 28 precision, loss of precision can occur. To retrieve the actual value of OracleDecimal, use the OracleDecimal.ToString() method. Another approach is to obtain the OracleDecimal value as a byte array in an internal Oracle NUMBER format through the BinData property. Example // C# using System; using Oracle.DataAccess.Types; class OracleDecimalSample { static void Main(string[] args) { // Illustrates the range of OracleDecimal vs. .NET decimal OracleDecimal decimal1 = OracleDecimal.MinValue; OracleDecimal decimal2 = OracleDecimal.MaxValue; OracleDecimal decimal3 = new OracleDecimal(decimal.MinValue); OracleDecimal decimal4 = new OracleDecimal(decimal.MaxValue); // Print the ranges Console.WriteLine("OracleDecimal can range from\n{0}\nto\n{1}\n", decimal1, decimal2); Console.WriteLine(".NET decimal can range from\n{0}\nto\n{1}", decimal3, decimal4); } } OracleDecimal Structure 9-66 Oracle Data Provider for .NET Developer’s Guide Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Constructors ■ OracleDecimal Static Fields ■ OracleDecimal Static (Comparison) Methods ■ OracleDecimal Static (Manipulation) Methods ■ OracleDecimal Static (Logarithmic) Methods ■ OracleDecimal Static (Trigonometric) Methods ■ OracleDecimal Static (Comparison) Operators ■ OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) ■ OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) ■ OracleDecimal Properties ■ OracleDecimal Instance Methods OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-67 OracleDecimal Members OracleDecimal members are listed in the following tables: OracleDecimal Constructors OracleDecimal constructors are listed in Table 9–27 OracleDecimal Static Fields The OracleDecimal static fields are listed in Table 9–28. OracleDecimal Static (Comparison) Methods The OracleDecimal static (comparison) methods are listed in Table 9–29. Table 9–27 OracleDecimal Constructors Constructor Description OracleDecimal Constructors Instantiates a new instance of OracleDecimal structure (Overloaded) Table 9–28 OracleDecimal Static Fields Field Description MaxPrecision A constant representing the maximum precision, which is 38 MaxScale A constant representing the maximum scale, which is 127 MaxValue A constant representing the maximum value for this structure, which is 9.9…9 x 10125 MinScale A constant representing the minimum scale, which is -84 MinValue A constant representing the minimum value for this structure, which is -1.0 x 10130 NegativeOne A constant representing the negative one value Null Represents a null value that can be assigned to an OracleDecimal instance One A constant representing the positive one value Pi A constant representing the numeric Pi value Zero A constant representing the zero value Table 9–29 OracleDecimal Static (Comparison) Methods Methods Description Equals Determines if two OracleDecimal values are equal (Overloaded) GreaterThan Determines if the first of two OracleDecimal values is greater than the second GreaterThanOrEqual Determines if the first of two OracleDecimal values is greater than or equal to the second LessThan Determines if the first of two OracleDecimal values is less than the second LessThanOrEqual Determines if the first of two OracleDecimal values is less than or equal to the second. OracleDecimal Members 9-68 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static (Manipulation) Methods The OracleDecimal static (manipulation) methods are listed in Table 9–30. NotEquals Determines if two OracleDecimal values are not equal Table 9–30 OracleDecimal Static (Manipulation) Methods Methods Description Abs Returns the absolute value of an OracleDecimal Add Adds two OracleDecimal structures AdjustScale Returns a new OracleDecimal with the specified number of digits and indicates whether or not to round or truncate the number if the scale is less than original Ceiling Returns a new OracleDecimal structure with its value set to the ceiling of an OracleDecimal structure ConvertToPrecScale Returns a new OracleDecimal structure with a new precision and scale Divide Divides one OracleDecimal value by another Floor Returns a new OracleDecimal structure with its value set to the floor of an OracleDecimal structure Max Returns the maximum value of the two supplied OracleDecimal structures Min Returns the minimum value of the two supplied OracleDecimal structures Mod Returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures Multiply Returns a new OracleDecimal structure with its value set to the result of multiplying two OracleDecimal structures Negate Returns a new OracleDecimal structure with its value set to the negation of the supplied OracleDecimal structure Parse Converts a string to an OracleDecimal Round Returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure and rounded off to the specified place SetPrecision Returns a new OracleDecimal structure with a new specified precision. Shift Returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure, and its decimal place shifted to the specified number of places to the right Sign Determines the sign of an OracleDecimal structure Sqrt Returns a new OracleDecimal structure with its value set to the square root of the supplied OracleDecimal structure Subtract Returns a new OracleDecimal structure with its value set to result of subtracting one OracleDecimal structure from another Truncate Truncates the OracleDecimal at a specified position Table 9–29 (Cont.) OracleDecimal Static (Comparison) Methods Methods Description OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-69 OracleDecimal Static (Logarithmic) Methods The OracleDecimal static (logarithmic) methods are listed in Table 9–31. OracleDecimal Static (Trigonometric) Methods The OracleDecimal static (trigonometric) methods are listed in Table 9–32. OracleDecimal Static (Comparison) Operators The OracleDecimal static (comparison) operators are listed in Table 9–33. Table 9–31 OracleDecimal Static (Logarithmic) Methods Methods Description Exp Returns a new OracleDecimal structure with its value set to e raised to the supplied power Log Returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure (Overloaded) Pow Returns a new OracleDecimal structure with its value set to the supplied OracleDecimal structure raised to the supplied power (Overloaded) Table 9–32 OracleDecimal Static (Trigonometric) Methods Methods Description Acos Returns an angle in radian whose cosine is the supplied OracleDecimal structure Asin Returns an angle in radian whose sine is the supplied OracleDecimal structure Atan Returns an angle in radian whose tangent is the supplied OracleDecimal structure Atan2 Returns an angle in radian whose tangent is the quotient of the two supplied OracleDecimal structures Cos Returns the cosine of the supplied angle in radian Sin Returns the sine of the supplied angle in radian Tan Returns the tangent of the supplied angle in radian Cosh Returns the hyperbolic cosine of the supplied angle in radian Sinh Returns the hyperbolic sine of the supplied angle in radian Tanh Returns the hyperbolic tangent of the supplied angle in radian Table 9–33 OracleDecimal Static (Comparison) Operators Operator Description operator + Adds two OracleDecimal values operator / Divides one OracleDecimal value by another operator == Determines if the two OracleDecimal values are equal operator > Determines if the first of two OracleDecimal values is greater than the second operator >= Determines if the first of two OracleDecimal values is greater than or equal to the second OracleDecimal Members 9-70 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) The OracleDecimal static operators (Conversion from .NET Type to OracleDecimal) are listed in Table 9–34. OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) The OracleDecimal static operators (Conversion from OracleDecimal to .NET) are listed in Table 9–35. OracleDecimal Properties The OracleDecimal properties are listed in Table 9–36. operator != Determines if the two OracleDecimal values are not equal operator < Determines if the first of two OracleDecimal values is less than the second operator <= Determines if the first of two OracleDecimal values is less than or equal to the second operator * Multiplies two OracleDecimal structures operator - Subtracts one OracleDecimal structure from another operator - Negates an OracleDecimal structure operator% Returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures. Table 9–34 OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) Operator Description implicit operator OracleDecimal Converts an instance value to an OracleDecimal structure (Overloaded) explicit operator OracleDecimal Converts an instance value to an OracleDecimal structure (Overloaded) Table 9–35 OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) Operator Description explicit operator byte Returns the byte representation of the OracleDecimal value explicit operator decimal Returns the decimal representation of the OracleDecimal value explicit operator double Returns the double representation of the OracleDecimal value explicit operator short Returns the short representation of the OracleDecimal value explicit operator int Returns the int representation of the OracleDecimal value explicit operator long Returns the long representation of the OracleDecimal value explicit operator float Returns the float representation of the OracleDecimal value Table 9–33 (Cont.) OracleDecimal Static (Comparison) Operators Operator Description OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-71 OracleDecimal Instance Methods The OracleDecimal instance methods are listed in Table 9–37. Table 9–36 OracleDecimal Properties Properties Description BinData Returns a byte array that represents the Oracle NUMBER in Oracle internal format Format Specifies the format for ToString() IsInt Indicates whether the current instance is an integer IsNull Indicates whether the current instance has a null value IsPositive Indicates whether the current instance is greater than 0 IsZero Indicates whether the current instance has a zero value Value Returns a decimal value Table 9–37 OracleDecimal Instance Methods Method Description CompareTo Compares the current instance to the supplied object and returns an integer that represents their relative values Equals Determines whether an object is an instance of OracleDecimal, and whether the value of the object is equal to the current instance (Overloaded) GetHashCode Returns a hash code for the current instance GetType Inherited from Object ToByte Returns the byte representation of the current instance ToDouble Returns the double representation of the current instance ToInt16 Returns the Int16 representation of the current instance ToInt32 Returns the Int32 representation of the current instance ToInt64 Returns the Int64 representation of the current instance ToSingle Returns the Single representation of the current instance ToString Overloads Object.ToString() Returns the string representation of the current instance See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Structure OracleDecimal Constructors 9-72 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Constructors The OracleDecimal constructors instantiate a new instance of the OracleDecimal structure. Overload List: ■ OracleDecimal(byte [ ]) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied byte array, which is in an Oracle NUMBER format. ■ OracleDecimal(decimal) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Decimal value. ■ OracleDecimal(double) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied double value. ■ OracleDecimal(int) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Int32 value. ■ OracleDecimal(float) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Single value. ■ OracleDecimal(long) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Int64 value. ■ OracleDecimal(string) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied string value. ■ OracleDecimal(string, string) This constructor creates a new instance of the OracleDecimal structure with the supplied string value and number format. OracleDecimal(byte [ ]) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied byte array, which is in an Oracle NUMBER format. Declaration // C# public OracleDecimal(byte [] bytes); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-73 Parameters ■ bytes A byte array that represents an Oracle NUMBER in an internal Oracle format. Exceptions ArgumentException - The bytes parameter is not in a internal Oracle NUMBER format or bytes has an invalid value. ArgumentNullException - The bytes parameter is null. OracleDecimal(decimal) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Decimal value. Declaration // C# public OracleDecimal(decimal decX); Parameters ■ decX The provided Decimal value. OracleDecimal(double) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied double value. Declaration // C# public OracleDecimal(double doubleX) Parameters ■ doubleX The provided double value. Exceptions OverFlowException - The value of the supplied double is greater than the maximum value or less than the minimum value of OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Constructors 9-74 Oracle Data Provider for .NET Developer’s Guide Remarks OracleDecimal contains the following values depending on the provided double value: ■ double.PositiveInfinity: positive infinity value ■ double.NegativeInfinity: negative infinity value. ■ double.NaN: null value OracleDecimal(int) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Int32 value. Declaration // C# public OracleDecimal(int intX); Parameters ■ intX The provided Int32 value. OracleDecimal(float) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Single value. Declaration // C# public OracleDecimal(float floatX); Parameters ■ floatX The provided float value. Remarks OracleDecimal contains the following values depending on the provided float value: float.PositiveInfinity: positive infinity value float.NegativeInfinity: negative infinity value See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-75 float.NaN: null value OracleDecimal(long) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied Int64 value. Declaration // C# public OracleDecimal(long longX); Parameters ■ longX The provided Int64 value. OracleDecimal(string) This constructor creates a new instance of the OracleDecimal structure and sets its value to the supplied string value. Declaration // C# public OracleDecimal(string numStr); Parameters ■ numStr The provided string value. Exceptions ArgumentException - The numStr parameter is an invalid string representation of an OracleDecimal. ArgumentNullException - The numStr parameter is null. OverFlowException - The value of numStr is greater than the maximum value or less than the minimum value of OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Constructors 9-76 Oracle Data Provider for .NET Developer’s Guide OracleDecimal(string, string) This constructor creates a new instance of the OracleDecimal structure with the supplied string value and number format. Declaration // C# public OracleDecimal(string numStr, string format); Parameters ■ numStr The provided string value. ■ format The provided number format. Exceptions ArgumentException - The numStr parameter is an invalid string representation of an OracleDecimal or the numStr is not in the numeric format specified by format. ArgumentNullException - The numStr parameter is null. OverFlowException - The value of numStr parameter is greater than the maximum value or less than the minimum value of OracleDecimal. Remarks If the numeric format includes decimal and group separators, then the provided string must use those characters defined by the OracleGlobalization.NumericCharacters of the thread. If the numeric format includes the currency symbol, ISO currency symbol, or the dual currency symbol, then the provided string must use those symbols defined by the OracleGlobalization.Currency, OracleGlobalization.ISOCurrency, and OracleGlobalization.DualCurrency properties respectively. Example // C# using System; using Oracle.DataAccess.Client; using Oracle.DataAccess.Types; class OracleDecimalSample { static void Main(string[] args) { See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-77 // Set the nls parameters related to currency OracleGlobalization info = OracleGlobalization.GetClientInfo(); info.Currency = "$"; info.NumericCharacters = ".,"; OracleGlobalization.SetThreadInfo(info); // Construct an OracleDecimal using a valid numeric format OracleDecimal dec = new OracleDecimal("$2,222.22","L9G999D99"); // Print "$2,222.22" Console.WriteLine(dec.ToString()); } } See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDecimal Static Fields 9-78 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static Fields The OracleDecimal static fields are listed in Table 9–38. MaxPrecision This static field represents the maximum precision, which is 38. Declaration // C# public static readonly byte MaxPrecision; MaxScale This static field a constant representing the maximum scale, which is 127. Declaration // C# public static readonly byte MaxScale; Table 9–38 OracleDecimal Static Fields Field Description MaxPrecision A constant representing the maximum precision, which is 38 MaxScale A constant representing the maximum scale, which is 127 MaxValue A constant representing the maximum value for this structure, which is 9.9…9 x 10125 MinScale A constant representing the minimum scale, which is -84 MinValue A constant representing the minimum value for this structure, which is -1.0 x 10130 NegativeOne A constant representing the negative one value Null Represents a null value that can be assigned to an OracleDecimal instance One A constant representing the positive one value Pi A constant representing the numeric Pi value Zero A constant representing the zero value See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-79 MaxValue This static field indicates a constant representing the maximum value for this structure, which is 9.9…9 x 10125 (38 nines followed by 88 zeroes). Declaration // C# public static readonly OracleDecimal MaxValue; MinScale This static field indicates a constant representing the maximum scale, which is -84. Declaration // C# public static readonly int MinScale; MinValue This static field indicates a constant representing the minimum value for this structure, which is -1.0 x 10130. Declaration // C# public static readonly OracleDecimal MinValue; NegativeOne This static field indicates a constant representing the negative one value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static Fields 9-80 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public static readonly OracleDecimal NegativeOne; Null This static field represents a null value that can be assigned to an OracleDecimal instance. Declaration // C# public static readonly OracleDecimal Null; One This static field indicates a constant representing the positive one value. Declaration // C# public static readonly OracleDecimal One; Pi This static field indicates a constant representing the numeric Pi value. Declaration // C# public static readonly OracleDecimal Pi; See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-81 Zero This static field indicates a constant representing the zero value. Declaration // C# public static readonly OracleDecimal Zero; See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Methods 9-82 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static (Comparison) Methods The OracleDecimal static (comparison) methods are listed in Table 9–39. Equals This method determines if two OracleDecimal values are equal. Declaration // C# public static bool Equals(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 Second OracleDecimal. Return Value Returns true if two OracleDecimal values are equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. Table 9–39 OracleDecimal Static (Comparison) Methods Methods Description Equals Determines if two OracleDecimal values are equal (Overloaded) GreaterThan Determines if the first of two OracleDecimal values is greater than the second GreaterThanOrEqual Determines if the first of two OracleDecimal values is greater than or equal to the second LessThan Determines if the first of two OracleDecimal values is less than the second LessThanOrEqual Determines if the first of two OracleDecimal values is less than or equal to the second. NotEquals Determines if two OracleDecimal values are not equal See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-83 GreaterThan This method determines if the first of two OracleDecimal values is greater than the second. Declaration // C# public static bool GreaterThan(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is greater than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. GreaterThanOrEqual This method determines if the first of two OracleDecimal values is greater than or equal to the second. Declaration // C# public static bool GreaterThanOrEqual(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Methods 9-84 Oracle Data Provider for .NET Developer’s Guide Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is greater than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. LessThan This method determines if the first of two OracleDecimal values is less than the second. Declaration // C# public static bool LessThan(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is less than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-85 LessThanOrEqual This method determines if the first of two OracleDecimal values is less than or equal to the second. Declaration // C# public static bool LessThanOrEqual(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is less than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. NotEquals This method determines if two OracleDecimal values are not equal. Declaration // C# public static bool NotEquals(OracleDecimal value1, OracleDecimal value2); Parameters ■ value1 First OracleDecimal. ■ value2 Second OracleDecimal. Return Value Returns true if two OracleDecimal values are not equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Methods 9-86 Oracle Data Provider for .NET Developer’s Guide ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-87 OracleDecimal Static (Manipulation) Methods The OracleDecimal static (manipulation) methods are listed in Table 9–40. Table 9–40 OracleDecimal Static (Manipulation) Methods Methods Description Abs Returns the absolute value of an OracleDecimal Add Adds two OracleDecimal structures AdjustScale Returns a new OracleDecimal with the specified number of digits and indicates whether or not to round or truncate the number if the scale is less than original Ceiling Returns a new OracleDecimal structure with its value set to the ceiling of an OracleDecimal structure ConvertToPrecScale Returns a new OracleDecimal structure with a new precision and scale Divide Divides one OracleDecimal value by another Floor Returns a new OracleDecimal structure with its value set to the floor of an OracleDecimal structure Max Returns the maximum value of the two supplied OracleDecimal structures Min Returns the minimum value of the two supplied OracleDecimal structures Mod Returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures Multiply Returns a new OracleDecimal structure with its value set to the result of multiplying two OracleDecimal structures Negate Returns a new OracleDecimal structure with its value set to the negation of the supplied OracleDecimal structure Parse Converts a string to an OracleDecimal Round Returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure and rounded off to the specified place SetPrecision Returns a new OracleDecimal structure with a new specified precision. Shift Returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure, and its decimal place shifted to the specified number of places to the right Sign Determines the sign of an OracleDecimal structure Sqrt Returns a new OracleDecimal structure with its value set to the square root of the supplied OracleDecimal structure Subtract Returns a new OracleDecimal structure with its value set to result of subtracting one OracleDecimal structure from another Truncate Truncates the OracleDecimal at a specified position OracleDecimal Static (Manipulation) Methods 9-88 Oracle Data Provider for .NET Developer’s Guide Abs This method returns the absolute value of an OracleDecimal. Declaration // C# public static OracleDecimal Abs(OracleDecimal val); Parameters ■ val An OracleDecimal. Return Value The absolute value of an OracleDecimal. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Add This method adds two OracleDecimal structures. Declaration // C# public static OracleDecimal Add(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value Returns an OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-89 AdjustScale This method returns a new OracleDecimal with the specified number of digits and indicates whether or not to round or truncate the number if the scale is less than the original. Declaration // C# public static OracleDecimal AdjustScale(OracleDecimal val, int digits, bool fRound); Parameters ■ val An OracleDecimal. ■ digits The number of digits. ■ fRound Indicates whether to round or truncate the number. Setting it to true rounds the number and setting it to false truncates the number. Return Value An OracleDecimal. Remarks If the supplied OracleDecimal has a null value, the returned OracleDecimal has a null value. Example // C# using System; using Oracle.DataAccess.Types; class AdjustScaleSample { static void Main(string[] args) { OracleDecimal dec1 = new OracleDecimal(5.555); // Adjust Scale to 2 with rounding off OracleDecimal dec2 = OracleDecimal.AdjustScale(dec1, 2, true); // Prints 5.56 Console.WriteLine(dec2.ToString()); // Adjust Scale to 2 with truncation OracleDecimal dec3 = OracleDecimal.AdjustScale(dec1, 2, false); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Manipulation) Methods 9-90 Oracle Data Provider for .NET Developer’s Guide // Prints 5.55 Console.WriteLine(dec3.ToString()); } } Ceiling This method returns a new OracleDecimal structure with its value set to the ceiling of the supplied OracleDecimal. Declaration // C# public static OracleDecimal Ceiling(OracleDecimal val); Parameters ■ val An OracleDecimal. Return Value A new OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. ConvertToPrecScale This method returns a new OracleDecimal structure with a new precision and scale. Declaration // C# public static OracleDecimal ConvertToPrecScale(OracleDecimal val int precision, int scale); Parameters ■ val An OracleDecimal structure. ■ precision The precision. Range of precision is 1 to 38. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-91 ■ scale The number of digits to the right of the decimal point. Range of scale is -84 to 127. Return Value A new OracleDecimal structure. Remarks If the supplied OracleDecimal has a null value, the returned OracleDecimal has a null value. Example // C# using System; using Oracle.DataAccess.Types; class ConvertToPrecScaleSample { static void Main(string[] args) { OracleDecimal dec1 = new OracleDecimal(555.6666); // Set the precision of od to 5 and scale to 2 OracleDecimal dec2 = OracleDecimal.ConvertToPrecScale(dec1,5,2); // Prints 555.67 Console.WriteLine(dec2.ToString()); // Set the precision of od to 3 and scale to 0 OracleDecimal dec3 = OracleDecimal.ConvertToPrecScale(dec1,3,0); // Prints 556 Console.WriteLine(dec3.ToString()); } } Divide This method divides one OracleDecimal value by another. Declaration // C# public static OracleDecimal Divide(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal. ■ val2 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Manipulation) Methods 9-92 Oracle Data Provider for .NET Developer’s Guide An OracleDecimal. Return Value A new OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Floor This method returns a new OracleDecimal structure with its value set to the floor of the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal Floor(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A new OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Max This method returns the maximum value of the two supplied OracleDecimal structures. Declaration // C# public static OracleDecimal Max(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal structure. ■ val2 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-93 An OracleDecimal structure. Return Value An OracleDecimal structure that has the greater value. Min This method returns the minimum value of the two supplied OracleDecimal structures. Declaration // C# public static OracleDecimal Min(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal structure. ■ val2 An OracleDecimal structure. Return Value An OracleDecimal structure that has the smaller value. Mod This method returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures. Declaration // C# public static OracleDecimal Mod(OracleDecimal val1, OracleDecimal divider); Parameters ■ val1 An OracleDecimal structure. ■ divider An OracleDecimal structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Manipulation) Methods 9-94 Oracle Data Provider for .NET Developer’s Guide Return Value An OracleDecimal. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Multiply This method returns a new OracleDecimal structure with its value set to the result of multiplying two OracleDecimal structures. Declaration // C# public static OracleDecimal Multiply(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal structure. ■ val2 An OracleDecimal structure. Return Value A new OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Negate This method returns a new OracleDecimal structure with its value set to the negation of the supplied OracleDecimal structures. Declaration // C# public static OracleDecimal Negate(OracleDecimal val); Parameters ■ val An OracleDecimal structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-95 Return Value A new OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Parse This method converts a string to an OracleDecimal. Declaration // C# public static OracleDecimal Parse (string str); Parameters ■ str The string being converted. Return Value A new OracleDecimal structure. Exceptions ArgumentException - The numStr parameter is an invalid string representation of an OracleDecimal. ArgumentNullException - The numStr parameter is null. OverFlowException - The value of numStr is greater than the maximum value or less than the minimum value of OracleDecimal. Round This method returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure and rounded off to the specified place. Declaration // C# public static OracleDecimal Round(OracleDecimal val, int decplace); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDecimal Static (Manipulation) Methods 9-96 Oracle Data Provider for .NET Developer’s Guide Parameters ■ val An OracleDecimal structure. ■ decplace The specified decimal place. If the value is positive, the function rounds the OracleDecimal structure to the right of the decimal point. If the value is negative, the function rounds to the left of the decimal point. Return Value An OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. SetPrecision This method returns a new OracleDecimal structure with a new specified precision. Declaration // C# public static OracleDecimal SetPrecision(OracleDecimal val, int precision); Parameters ■ val An OracleDecimal structure. ■ precision The specified precision. Range of precision is 1 to 38. Return Value An OracleDecimal structure. Remarks The returned OracleDecimal is rounded off if the specified precision is smaller than the precision of val. If val has a null value, the returned OracleDecimal has a null value. Example // C# using System; using Oracle.DataAccess.Types; class SetPrecisionSample See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-97 { static void Main(string[] args) { OracleDecimal dec1 = new OracleDecimal(555.6666); // Set the precision of dec1 to 3 OracleDecimal dec2 = OracleDecimal.SetPrecision(dec1, 3); // Prints 556 Console.WriteLine(dec2.ToString()); // Set the precision of dec1 to 4 OracleDecimal dec3 = OracleDecimal.SetPrecision(dec1, 4); // Prints 555.7 Console.WriteLine(dec3.ToString()); } } Shift This method returns a new OracleDecimal structure with its value set to that of the supplied OracleDecimal structure, and its decimal place shifted to the specified number of places to the right. Declaration // C# public static OracleDecimal Shift(OracleDecimal val, int decplaces); Parameters ■ val An OracleDecimal structure. ■ decplaces The specified number of places to be shifted. Return Value An OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. If decplaces is negative, the shift is to the left. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Manipulation) Methods 9-98 Oracle Data Provider for .NET Developer’s Guide Sign This method determines the sign of an OracleDecimal structure. Declaration // C# public static int Sign(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value ■ -1: if the supplied OracleDecimal < 0 ■ 0: if the supplied OracleDecimal == 0 ■ 1: if the supplied OracleDecimal > 0 Exceptions OracleNullValueException - The argument has a null value. Sqrt This method returns a new OracleDecimal structure with its value set to the square root of the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal Sqrt(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value An OracleDecimal structure. Exceptions ArgumentOutOfRangeException - The provided OracleDecimal structure is less than zero. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-99 Remarks If either argument has a null value, the returned OracleDecimal has a null value. Subtract This method returns a new OracleDecimal structure with its value set to result of subtracting one OracleDecimal structure from another. Declaration // C# public static OracleDecimal Subtract(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal structure. ■ val2 An OracleDecimal structure. Return Value An OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Truncate This method truncates the OracleDecimal at a specified position. Declaration // C# public static OracleDecimal Truncate(OracleDecimal val, int pos); Parameters ■ val An OracleDecimal structure. ■ pos The specified position. If the value is positive, the function truncates the OracleDecimal structure to the right of the decimal point. If the value is See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Manipulation) Methods 9-100 Oracle Data Provider for .NET Developer’s Guide negative, it truncates the OracleDecimal structure to the left of the decimal point. Return Value An OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-101 OracleDecimal Static (Logarithmic) Methods The OracleDecimal static (logarithmic) methods are listed in Table 9–41. Exp This method returns a new OracleDecimal structure with its value set to e raised to the supplied OracleDecimal. Declaration // C# public static OracleDecimal Exp(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value An OracleDecimal structure. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Log Log returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure. Overload List: ■ Log(OracleDecimal) Table 9–41 OracleDecimal Static (Logarithmic) Methods Methods Description Exp Returns a new OracleDecimal structure with its value set to e raised to the supplied power Log Returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure (Overloaded) Pow Returns a new OracleDecimal structure with its value set to the supplied OracleDecimal structure raised to the supplied power (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Logarithmic) Methods 9-102 Oracle Data Provider for .NET Developer’s Guide This method returns a new OracleDecimal structure with its value set to the natural logarithm (base e) of the supplied OracleDecimal structure. ■ Log(OracleDecimal, int) This method returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure in the supplied base. ■ Log(OracleDecimal, OracleDecimal) This method returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure in the supplied base. Log(OracleDecimal) This method returns a new OracleDecimal structure with its value set to the natural logarithm (base e) of the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal Log(OracleDecimal val); Parameters ■ val An OracleDecimal structure whose logarithm is to be calculated. Return Value Returns a new OracleDecimal structure with its value set to the natural logarithm (base e) of val. Exceptions ArgumentOutOfRangeException - The supplied OracleDecimal value is less than zero. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. If the supplied OracleDecimal structure has zero value, the result is undefined, and the returned OracleDecimal structure has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-103 Log(OracleDecimal, int) This method returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure in the supplied base. Declaration // C# public static OracleDecimal Log(OracleDecimal val, int logBase); Parameters ■ val An OracleDecimal structure whose logarithm is to be calculated. ■ logBase An int that specifies the base of the logarithm. Return Value A new OracleDecimal structure with its value set to the logarithm of val in the supplied base. Exceptions ArgumentOutOfRangeException - Either argument is less than zero. Remarks If either argument has a null value, the returned OracleDecimal has a null value. If both arguments have zero value, the result is undefined, and the returned OracleDecimal structure has a null value. Log(OracleDecimal, OracleDecimal) This method returns the supplied OracleDecimal structure with its value set to the logarithm of the supplied OracleDecimal structure in the supplied base. Declaration // C# public static OracleDecimal Log(OracleDecimal val, OracleDecimal logBase); Parameters ■ val An OracleDecimal structure whose logarithm is to be calculated. ■ logBase An OracleDecimal structure that specifies the base of the logarithm. Return Value Returns the logarithm of val in the supplied base. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Logarithmic) Methods 9-104 Oracle Data Provider for .NET Developer’s Guide Exceptions ArgumentOutOfRangeException - Either the val or logBase parameter is less than zero. Remarks If either argument has a null value, the returned OracleDecimal has a null value. If both arguments have zero value, the result is undefined, and the returned OracleDecimal structure has a null value. Pow Pow returns a new OracleDecimal structure with its value set to the supplied OracleDecimal structure raised to the supplied power. Overload List: ■ Pow(OracleDecimal, int) This method returns a new OracleDecimal structure with its value set to the supplied OracleDecimal value raised to the supplied Int32 power. ■ Pow(OracleDecimal, OracleDecimal) This method returns a new OracleDecimal structure with its value set to the supplied OracleDecimal structure raised to the supplied OracleDecimal power. Pow(OracleDecimal, int) This method returns a new OracleDecimal structure with its value set to the supplied OracleDecimal value raised to the supplied Int32 power. Declaration // C# public static OracleDecimal Pow(OracleDecimal val, int power); Parameters ■ val An OracleDecimal structure. ■ power An int value that specifies the power. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-105 Return Value An OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. Pow(OracleDecimal, OracleDecimal) This method returns a new OracleDecimal structure with its value set to the supplied OracleDecimal structure raised to the supplied OracleDecimal power. Declaration // C# public static OracleDecimal Pow(OracleDecimal val, OracleDecimal power); Parameters ■ val An OracleDecimal structure. ■ power An OracleDecimal structure that specifies the power. Return Value An OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Trigonometric) Methods 9-106 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static (Trigonometric) Methods The OracleDecimal static (trigonometric) methods are listed in Table 9–42. Acos This method returns an angle in radian whose cosine is the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal Acos(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Range is (-1 to 1). Return Value An OracleDecimal structure that represents an angle in radian. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Table 9–42 OracleDecimal Static (Trigonometric) Methods Methods Description Acos Returns an angle in radian whose cosine is the supplied OracleDecimal structure Asin Returns an angle in radian whose sine is the supplied OracleDecimal structure Atan Returns an angle in radian whose tangent is the supplied OracleDecimal structure Atan2 Returns an angle in radian whose tangent is the quotient of the two supplied OracleDecimal structures Cos Returns the cosine of the supplied angle in radian Sin Returns the sine of the supplied angle in radian Tan Returns the tangent of the supplied angle in radian Cosh Returns the hyperbolic cosine of the supplied angle in radian Sinh Returns the hyperbolic sine of the supplied angle in radian Tanh Returns the hyperbolic tangent of the supplied angle in radian See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-107 Asin This method returns an angle in radian whose sine is the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal Asin(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Range is (-1 to 1). Return Value An OracleDecimal structure that represents an angle in radian. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Atan This method returns an angle in radian whose tangent is the supplied OracleDecimal structure Declaration // C# public static OracleDecimal Atan(OracleDecimal val); Parameters ■ val An OracleDecimal. Return Value An OracleDecimal structure that represents an angle in radian. Remarks If the argument has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Trigonometric) Methods 9-108 Oracle Data Provider for .NET Developer’s Guide Atan2 This method returns an angle in radian whose tangent is the quotient of the two supplied OracleDecimal structures. Declaration // C# public static OracleDecimal Atan2(OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 An OracleDecimal structure that represents the y-coordinate. ■ val2 An OracleDecimal structure that represents the x-coordinate. Return Value An OracleDecimal structure that represents an angle in radian. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Cos This method returns the cosine of the supplied angle in radian. Declaration // C# public static OracleDecimal Cos(OracleDecimal val); Parameters ■ val An OracleDecimal structure that represents an angle in radian. Return Value An OracleDecimal instance. Exceptions ArgumentOutOfRangeException - The val parameter is positive or negative infinity. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-109 Remarks If either argument has a null value, the returned OracleDecimal has a null value. Sin This method returns the sine of the supplied angle in radian. Declaration // C# public static OracleDecimal Sin(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value An OracleDecimal structure that represents an angle in radian. Exceptions ArgumentOutOfRangeException - The val parameter is positive or negative infinity. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Tan This method returns the tangent of the supplied angle in radian. Declaration // C# public static OracleDecimal Tan(OracleDecimal val); Parameters ■ val An OracleDecimal structure that represents an angle in radian. Return Value An OracleDecimal instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Trigonometric) Methods 9-110 Oracle Data Provider for .NET Developer’s Guide Exceptions ArgumentOutOfRangeException - The val parameter is positive or negative infinity. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Cosh This method returns the hyperbolic cosine of the supplied angle in radian. Declaration // C# public static OracleDecimal Cosh(OracleDecimal val); Parameters ■ val An OracleDecimal structure that represents an angle in radian. Return Value An OracleDecimal instance. Remarks If either argument has a null value, the returned OracleDecimal has a null value. Sinh This method returns the hyperbolic sine of the supplied angle in radian. Declaration // C# public static OracleDecimal Sinh(OracleDecimal val); Parameters ■ val An OracleDecimal structure that represents an angle in radian. Return Value An OracleDecimal instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-111 Remarks If either argument has a null value, the returned OracleDecimal has a null value. Tanh This method returns the hyperbolic tangent of the supplied angle in radian. Declaration // C# public static OracleDecimal Tanh(OracleDecimal val); Parameters ■ val An OracleDecimal structure that represents an angle in radian. Return Value An OracleDecimal instance. Remarks If either argument has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Operators 9-112 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static (Comparison) Operators The OracleDecimal static (comparison) operators are listed in Table 9–43. operator + This method adds two OracleDecimal values. Declaration // C# public static OracleDecimal operator + (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value An OracleDecimal structure. Table 9–43 OracleDecimal Static (Comparison) Operators Operator Description operator + Adds two OracleDecimal values operator / Divides one OracleDecimal value by another operator == Determines if the two OracleDecimal values are equal operator > Determines if the first of two OracleDecimal values is greater than the second operator >= Determines if the first of two OracleDecimal values is greater than or equal to the second operator != Determines if the two OracleDecimal values are not equal operator < Determines if the first of two OracleDecimal values is less than the second operator <= Determines if the first of two OracleDecimal values is less than or equal to the second operator * Multiplies two OracleDecimal structures operator - Subtracts one OracleDecimal structure from another operator - Negates an OracleDecimal structure operator% Returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-113 Remarks If either operand has a null value, the returned OracleDecimal has a null value. operator / This method divides one OracleDecimalvalue by another. Declaration / C# public static OracleDecimal operator / (OracleDecimal val1, OracleDecimal val2) Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value An OracleDecimal structure. Remarks If either operand has a null value, the returned OracleDecimal has a null value. operator == This method determines if two OracleDecimal values are equal. Declaration // C# public static bool operator == (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Operators 9-114 Oracle Data Provider for .NET Developer’s Guide Return Value Returns true if their values are equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. operator > This method determines if the first of two OracleDecimal values is greater than the second. Declaration // C# public static bool operator > (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value Returns true if the two OracleDecimal values are not equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. operator >= This method determines if the first of two OracleDecimal values is greater than or equal to the second. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-115 Declaration // C# public static bool operator >= (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is greater than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. operator != This method determines if the first of two OracleDecimal values are not equal. Declaration // C# public static bool operator != (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value Returns true if the two OracleDecimal values are not equal; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Operators 9-116 Oracle Data Provider for .NET Developer’s Guide ■ Two OracleDecimals that contain a null value are equal. operator < This method determines if the first of two OracleDecimal values is less than the second. Declaration // C# public static bool operator < (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is less than the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. operator <= This method determines if the first of two OracleDecimal values is less than or equal to the second. Declaration // C# public static bool operator <= (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-117 ■ val2 Second OracleDecimal. Return Value Returns true if the first of two OracleDecimal values is less than or equal to the second; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. operator * This method multiplies two OracleDecimal structures. Declaration // C# public static OracleDecimal operator * (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value A new OracleDecimal structure. Remarks If either operand has a null value, the returned OracleDecimal has a null value. operator - This method subtracts one OracleDecimal structure from another. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static (Comparison) Operators 9-118 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public static OracleDecimal operator - (OracleDecimal val1, OracleDecimal val2); Parameters ■ val1 First OracleDecimal. ■ val2 Second OracleDecimal. Return Value A new OracleDecimal structure. Remarks If either operand has a null value, the returned OracleDecimal has a null value. operator - This method negates the supplied OracleDecimal structure. Declaration // C# public static OracleDecimal operator - (OracleDecimal val); Parameters ■ val An OracleDecimal. Return Value A new OracleDecimal structure. Remarks If the supplied OracleDecimal structure has a null value, the returned OracleDecimal has a null value. operator% This method returns a new OracleDecimal structure with its value set to the modulus of two OracleDecimal structures. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-119 Declaration // C# public static OracleDecimal operator % (OracleDecimal val, OracleDecimal divider); Parameters ■ val An OracleDecimal. ■ divider An OracleDecimal. Return Value A new OracleDecimal structure. Remarks If either operand has a null value, the returned OracleDecimal has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) 9-120 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) The OracleDecimal static operators (Conversion from .NET Type to OracleDecimal) are listed in Table 9–44. implicit operator OracleDecimal implicit operator OracleDecimal returns the OracleDecimal representation of a value. Overload List: ■ implicit operator OracleDecimal(decimal) This method returns the OracleDecimal representation of a decimal value. ■ implicit operator OracleDecimal(int) This method returns the OracleDecimal representation of an int value. ■ implicit operator OracleDecimal(long) This method returns the OracleDecimal representation of a long value. implicit operator OracleDecimal(decimal) This method returns the OracleDecimal representation of a decimal value. Declaration // C# public static implicit operator OracleDecimal(decimal val); Parameters ■ val A decimal value. Table 9–44 OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) Operator Description implicit operator OracleDecimal Converts an instance value to an OracleDecimal structure (Overloaded) explicit operator OracleDecimal Converts an instance value to an OracleDecimal structure (Overloaded) See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-121 Return Value An OracleDecimal. implicit operator OracleDecimal(int) This method returns the OracleDecimal representation of an int value. Declaration // C# public static implicit operator OracleDecimal(int val); Parameters ■ val An int value. Return Value An OracleDecimal. implicit operator OracleDecimal(long) This method returns the OracleDecimal representation of a long value. Declaration // C# public static implicit operator OracleDecimal(long val); Parameters ■ val A long value. Return Value An OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static Operators (Conversion from .NET Type to OracleDecimal) 9-122 Oracle Data Provider for .NET Developer’s Guide explicit operator OracleDecimal OracleDecimal returns the OracleDecimal representation of a value. Overload List: ■ explicit operator OracleDecimal(double) This method returns the OracleDecimal representation of a double. ■ explicit operator OracleDecimal(string) This method returns the OracleDecimal representation of a string. explicit operator OracleDecimal(double) This method returns the OracleDecimal representation of a double. Declaration // C# public static explicit operator OracleDecimal(double val); Parameters ■ val A double. Return Value An OracleDecimal. Exceptions OverFlowException - The value of the supplied double is greater than the maximum value of OracleDecimal or less than the minimum value of OracleDecimal. Remarks OracleDecimal contains the following values depending on the provided double value: ■ double.PositiveInfinity: positive infinity value ■ double.NegativeInfinity: negative infinity value. ■ double.NaN: null value See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-123 explicit operator OracleDecimal(string) This method returns the OracleDecimal representation of a string. Declaration // C# public static explicit operator OracleDecimal(string numStr); Parameters ■ numStr A string that represents a numeric value. Return Value An OracleDecimal. Exceptions ArgumentException - The numStr parameter is an invalid string representation of an OracleDecimal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) 9-124 Oracle Data Provider for .NET Developer’s Guide OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) The OracleDecimal static operators (Conversion from OracleDecimal to .NET) are listed in Table 9–45. explicit operator byte This method returns the byte representation of the OracleDecimal value. Declaration // C# public static explicit operator byte(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A byte. Exceptions OracleNullValueException - OracleDecimal has a null value. OverFlowException- The byte cannot represent the supplied OracleDecimal structure. Table 9–45 OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) Operator Description explicit operator byte Returns the byte representation of the OracleDecimal value explicit operator decimal Returns the decimal representation of the OracleDecimal value explicit operator double Returns the double representation of the OracleDecimal value explicit operator short Returns the short representation of the OracleDecimal value explicit operator int Returns the int representation of the OracleDecimal value explicit operator long Returns the long representation of the OracleDecimal value explicit operator float Returns the float representation of the OracleDecimal value See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-125 explicit operator decimal This method returns the decimal representation of the OracleDecimal value. Declaration // C# public static explicit operator decimal(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A decimal. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The decimal cannot represent the supplied OracleDecimal structure. explicit operator double This method returns the double representation of the OracleDecimal value. Declaration // C# public static explicit operator double(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A double. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The double cannot represent the supplied OracleDecimal structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) 9-126 Oracle Data Provider for .NET Developer’s Guide explicit operator short This method returns the short representation of the OracleDecimal value. Declaration // C# public static explicit operator short(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A short. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The short cannot represent the supplied OracleDecimal structure. explicit operator int This method returns the int representation of the OracleDecimal value. Declaration // C# public static explicit operator int(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value An int. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The int cannot represent the supplied OracleDecimal structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-127 explicit operator long This method returns the long representation of the OracleDecimal value. Declaration // C# public static explicit operator long(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A long. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The long cannot represent the supplied OracleDecimal structure. explicit operator float This method returns the float representation of the OracleDecimal value. Declaration // C# public static explicit operator float(OracleDecimal val); Parameters ■ val An OracleDecimal structure. Return Value A float. Exceptions OracleNullValueException - The OracleDecimal has a null value. OverFlowException - The float cannot represent the supplied OracleDecimal structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Static Operators (Conversion from OracleDecimal to .NET) 9-128 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-129 OracleDecimal Properties The OracleDecimal properties are listed in Table 9–46. BinData This property returns a byte array that represents the Oracle NUMBER in an internal Oracle format. Declaration // C# public byte[] BinData {get;} Property Value A byte array that represents the Oracle NUMBER in an internal Oracle format. Exceptions OracleNullValueException - The current instance has a null value. Format This property specifies the format for ToString(). Declaration // C# public string Format {get; set;} Table 9–46 OracleDecimal Properties Properties Description BinData Returns a byte array that represents the Oracle NUMBER in Oracle internal format Format Specifies the format for ToString() IsInt Indicates whether the current instance is an integer IsNull Indicates whether the current instance has a null value IsPositive Indicates whether the current instance is greater than 0 IsZero Indicates whether the current instance has a zero value Value Returns a decimal value See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Properties 9-130 Oracle Data Provider for .NET Developer’s Guide Property Value The string which specifies the format. Remarks Format is used when ToString() is called on an instance of an OracleDecimal. It is useful if the ToString() method needs a specific currency symbol, group, or decimal separator as part of a string. By default, this property is null which indicates that no special formatting is used. The decimal and group separator characters are specified by the thread's OracleGlobalization.NumericCharacters. The currency symbols are specified by the following thread properties: ■ OracleGlobalization.Currency ■ OracleGlobalization.ISOCurrency ■ OracleGlobalization.DualCurrency IsInt This property indicates whether the current instance is an integer value. Declaration // C# public bool IsInt {get;} Property Value A bool value that returns true if the current instance is an integer value; otherwise, returns false. Exceptions OracleNullValueException - The current instance has a null value. IsNull This property indicates whether the current instance has a null value. Declaration // C# See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-131 public bool IsNull {get;} Property Value A bool value that returns true if the current instance has a null value; otherwise, returns false. IsPositive This property indicates whether the value of the current instance is greater than 0. Declaration // C# public bool IsPositive {get;} Property Value A bool value that returns true if the current instance is greater than 0; otherwise, returns false. Exceptions OracleNullValueException - The current instance has a null value. IsZero This property indicates whether the current instance has a zero value. Declaration // C# public bool IsZero{get;} Property Value A bool value that returns true if the current instance has a zero value; otherwise, returns false. Exceptions OracleNullValueException - The current instance has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Properties 9-132 Oracle Data Provider for .NET Developer’s Guide Value This method returns a decimal value. Declaration // C# public decimal Value {get;} Property Value A decimal value. Exceptions OracleNullValueException - The current instance has a null value. OverFlowException - The decimal cannot represent the supplied OracleDecimal structure. Remarks Precision can be lost when the decimal value is obtained from an OracleDecimal. See Remarks under "OracleDecimal Structure" on page 9-65 for further information. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-133 OracleDecimal Instance Methods The OracleDecimal instance methods are listed in Table 9–47. CompareTo This method compares the current instance to the supplied object and returns an integer that represents their relative values. Declaration // C# public int CompareTo(object obj); Parameters ■ obj The supplied instance. Return Value The method returns a number: ■ Less than zero: if the value of the current instance is less than obj. ■ Zero: if the value of the current instance is equal to obj. ■ Greater than zero: if the value of the current instance is greater than obj. Table 9–47 OracleDecimal Instance Methods Method Description CompareTo Compares the current instance to the supplied object and returns an integer that represents their relative values Equals Determines whether an object is an instance of OracleDecimal, and whether the value of the object is equal to the current instance (Overloaded) GetHashCode Returns a hash code for the current instance GetType Inherited from Object ToByte Returns the byte representation of the current instance ToDouble Returns the double representation of the current instance ToInt16 Returns the Int16 representation of the current instance ToInt32 Returns the Int32 representation of the current instance ToInt64 Returns the Int64 representation of the current instance ToSingle Returns the Single representation of the current instance ToString Overloads Object.ToString() Returns the string representation of the current instance See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Instance Methods 9-134 Oracle Data Provider for .NET Developer’s Guide Implements IComparable Exceptions ArgumentException - The parameter is not of type OracleDecimal. Remarks The following rules apply to the behavior of this method. ■ The comparison must be between OracleDecimals. For example, comparing an OracleDecimal instance with an OracleBinary instance is not allowed. When an OracleDecimal is compared with a different type, an ArgumentException is thrown. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. Equals Overrides Object This method determines whether an object is an instance of OracleDecimal, and whether the value of the object is equal to the current instance. Declaration // C# public override bool Equals(object obj); Parameters ■ obj An OracleDecimal instance. Return Value Returns true if obj is an instance of OracleDecimal, and the value of obj is equal to the current instance; otherwise, returns false. Remarks The following rules apply to the behavior of this method. ■ Any OracleDecimal that has a value compares greater than an OracleDecimal that has a null value. ■ Two OracleDecimals that contain a null value are equal. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-135 GetHashCode Overrides Object This method returns a hash code for the current instance. Declaration // C# public override int GetHashCode(); Return Value Returns a hash code. ToByte This method returns the byte representation of the current instance. Declaration // C# public byte ToByte(); Return Value A byte. Exceptions OverFlowException - The byte cannot represent the current instance. OracleNullValueException - The current instance has a null value. ToDouble This method returns the double representation of the current instance. Declaration // C# public double ToDouble(); See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Instance Methods 9-136 Oracle Data Provider for .NET Developer’s Guide Return Value A double. Exceptions OverFlowException - The double cannot represent the current instance. OracleNullValueException - The current instance has a null value. ToInt16 This method returns the Int16 representation of the current instance. Declaration // C# public short ToInt16(); Return Value A short. Exceptions OverFlowException - The short cannot represent the current instance. OracleNullValueException - The current instance has a null value. ToInt32 This method returns the Int32 representation of the current instance. Declaration // C# public int ToInt32(); Return Value An int. Exceptions OverFlowException - The int cannot represent the current instance. OracleNullValueException - The current instance has a null value. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Structure Oracle Data Provider for .NET Types Structures 9-137 ToInt64 This method returns the Int64 representation of the current instance. Declaration // C# public long ToInt64(); Return Value A long. Exceptions OverFlowException - The long cannot represent the current instance. OracleNullValueException - The current instance has a null value. ToSingle This method returns the Single representation of the current instance. Declaration // C# public float ToSingle(); Return Value A float. Exceptions OverFlowException - The float cannot represent the current instance. OracleNullValueException - The current instance has a null value. ToString Overrides Object This method returns the string representation of the current instance. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure OracleDecimal Instance Methods 9-138 Oracle Data Provider for .NET Developer’s Guide Declaration // C# public override string ToString(); Return Value Returns the number in a string. Remarks If the current instance has a null value, the returned string is "null". The returned value is a string representation of an OracleDecimal in the numeric format specified by the Format property. The decimal and group separator characters are specified by the thread's OracleGlobalization.NumericCharacters. The currency symbols are specified by the following thread properties: ■ OracleGlobalization.Currency ■ OracleGlobalization.ISOCurrency ■ OracleGlobalization.DualCurrency If the numeric format is not specified, an Oracle default value is used. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleDecimal Members ■ OracleDecimal Structure ■ "OracleGlobalization Class" on page 6-2 ■ "Globalization Support" on page 3-53 OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-139 OracleIntervalDS Structure The OracleIntervalDS structure represents the Oracle INTERVAL DAY TO SECOND datatype to be stored in or retrieved from a database. Each OracleIntervalDS stores a period of time in term of days, hours, minutes, seconds, and fractional seconds. Class Inheritance Object ValueType OracleIntervalDS Declaration // C# public struct OracleIntervalDS : IComparable Thread Safety All public static methods are thread-safe, although instance methods do not guarantee thread safety. Example // C# using System; using Oracle.DataAccess.Types; class OracleIntervalDSSample { static void Main() { OracleIntervalDS iDSMax = OracleIntervalDS.MaxValue; double totalDays = iDSMax.TotalDays; totalDays -= 1; OracleIntervalDS iDSMax_1 = new OracleIntervalDS(totalDays); // Calculate the difference OracleIntervalDS iDSDiff = iDSMax - iDSMax_1; // Prints "iDSDiff.ToString() = +000000000 23:59:59.999999999" Console.WriteLine("iDSDiff.ToString() = " + iDSDiff.ToString()); } } Requirements Namespace: Oracle.DataAccess.Types Assembly: Oracle.DataAccess.dll OracleIntervalDS Structure 9-140 Oracle Data Provider for .NET Developer’s Guide See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Members ■ OracleIntervalDS Constructors ■ OracleIntervalDS Static Fields ■ OracleIntervalDS Static Methods ■ OracleIntervalDS Static Operators ■ OracleIntervalDS Type Conversions ■ OracleIntervalDS Properties ■ OracleIntervalDS Methods OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-141 OracleIntervalDS Members OracleIntervalDS members are listed in the following tables: OracleIntervalDS Constructors OracleIntervalDS constructors are listed in Table 9–48 OracleIntervalDS Static Fields The OracleIntervalDS static fields are listed in Table 9–49. OracleIntervalDS Static Methods The OracleIntervalDS static methods are listed in Table 9–50. Table 9–48 OracleIntervalDS Constructors Constructor Description OracleIntervalDS Constructors Instantiates a new instance of OracleIntervalDS structure (Overloaded) Table 9–49 OracleIntervalDS Static Fields Field Description MaxValue Represents the maximum valid time interval for an OracleIntervalDS structure MinValue Represents the minimum valid time interval for an OracleIntervalDS structure Null Represents a null value that can be assigned to an OracleIntervalDS instance Zero Represents a zero value for an OracleIntervalDS structure Table 9–50 OracleIntervalDS Static Methods Methods Description Equals Determines whether two OracleIntervalDS values are equal (Overloaded) GreaterThan Determines whether one OracleIntervalDS value is greater than another GreaterThanOrEqual Determines whether one OracleIntervalDS value is greater than or equal to another LessThan Determines whether one OracleIntervalDS value is less than another LessThanOrEqual Determines whether one OracleIntervalDS value is less than or equal to another NotEquals Determines whether two OracleIntervalDS values are not equal Parse Returns an OracleIntervalDS structure and sets its value for time interval using a string SetPrecision Returns a new instance of an OracleIntervalDS with the specified day precision and fractional second precision OracleIntervalDS Members 9-142 Oracle Data Provider for .NET Developer’s Guide OracleIntervalDS Static Operators The OracleIntervalDS static operators are listed in Table 9–51. OracleIntervalDS Type Conversions The OracleIntervalDS type conversions are listed in Table 9–52. OracleIntervalDS Properties The OracleIntervalDS properties are listed in Table 9–53. Table 9–51 OracleIntervalDS Static Operators Operator Description operator + Adds two OracleIntervalDS values operator == Determines whether two OracleIntervalDS values are equal operator > Determines whether one OracleIntervalDS value is greater than another operator >= Determines whether one OracleIntervalDS value is greater than or equal to another operator != Determines whether two OracleIntervalDS values are not equal operator < Determines whether one OracleIntervalDS value is less than another operator <= Determines whether one OracleIntervalDS value is less than or equal to another operator - Subtracts one OracleIntervalDS value from another operator - Negates an OracleIntervalDS structure operator * Multiplies an OracleIntervalDS value by a number operator / Divides an OracleIntervalDS value by a number Table 9–52 OracleIntervalDS Type Conversions Operator Description explicit operator TimeSpan Converts an OracleIntervalDS structure to a TimeSpan structure explicit operator OracleIntervalDS Converts a string to an OracleIntervalDS structure implicit operator OracleIntervalDS Converts a TimeSpan structure to an OracleIntervalDS structure Table 9–53 OracleIntervalDS Properties Properties Description BinData Returns an array of bytes that represents the Oracle INTERVAL DAY TO SECOND in Oracle internal format Days Gets the days component of an OracleIntervalDS OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-143 OracleIntervalDS Methods The OracleIntervalDS methods are listed in Table 9–54. Hours Gets the hours component of an OracleIntervalDS IsNull Indicates whether the current instance has a null value Milliseconds Gets the milliseconds component of an OracleIntervalDS Minutes Gets the minutes component of an OracleIntervalDS Nanoseconds Gets the nanoseconds component of an OracleIntervalDS Seconds Gets the seconds component of an OracleIntervalDS TotalDays Returns the total number, in days, that represent the time period in the OracleIntervalDS structure Value Specifies the time interval that is stored in the OracleIntervalDS structure Table 9–54 OracleIntervalDS Methods Methods Description CompareTo Compares the current OracleIntervalDS instance to an object, and returns an integer that represents their relative values Equals Determines whether the specified object has the same time interval as the current instance (Overloaded) GetHashCode Returns a hash code for the OracleIntervalDS instance GetType Inherited from Object ToString Converts the current OracleIntervalDS structure to a string See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure Table 9–53 (Cont.) OracleIntervalDS Properties Properties Description OracleIntervalDS Constructors 9-144 Oracle Data Provider for .NET Developer’s Guide OracleIntervalDS Constructors OracleIntervalDS constructors create a new instance of the OracleIntervalDS structure. Overload List: ■ OracleIntervalDS(TimeSpan) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using a TimeSpan structure. ■ OracleIntervalDS(string) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using a string that indicates a period of time. ■ OracleIntervalDS(double) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the total number of days. ■ OracleIntervalDS(int, int, int, int, double) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the supplied days, hours, minutes, seconds and milliseconds. ■ OracleIntervalDS(int, int, int, int, int) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the supplied days, hours, minutes, seconds, and nanoseconds. ■ OracleIntervalDS(byte[ ]) This constructor creates a new instance of the OracleIntervalDS structure and sets its value to the provided byte array, which is in an internal Oracle INTERVAL DAY TO SECOND format. OracleIntervalDS(TimeSpan) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using a TimeSpan structure. Declaration // C# public OracleIntervalDS(TimeSpan ts); Parameters ■ ts A TimeSpan structure. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-145 OracleIntervalDS(string) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using a string that indicates a period of time. Declaration // C# public OracleIntervalDS(string intervalStr); Parameters ■ intervalStr A string representing the Oracle INTERVAL DAY TO SECOND. Exceptions ArgumentException - The intervalStr parameter is not in the valid format or has an invalid value. ArgumentNullException - The intervalStr parameter is null. Remarks The value specified in the supplied intervalStr must be in Day HH:MI:SSxFF format. Example "1 2:3:4.99" means 1 day, 2 hours, 3 minutes, 4 seconds, and 990 milliseconds or 1 day, 2 hours, 3 minutes, 4 seconds, and 990000000 nanoseconds. OracleIntervalDS(double) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the total number of days. Declaration // C# public OracleIntervalDS(double totalDays); Parameters ■ totalDays The supplied total number of days for a time interval. Range of days is -1000,000,000 < totalDays < 1000,000,000. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Constructors 9-146 Oracle Data Provider for .NET Developer’s Guide Exceptions ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range. ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleIntervalDS. OracleIntervalDS(int, int, int, int, double) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the supplied days, hours, minutes, seconds, and milliseconds. Declaration // C# public OracleIntervalDS (int days, int hours, int minutes, int seconds, double milliSeconds); Parameters ■ days The days provided. Range of day is (-999,999,999 to 999,999,999). ■ hours The hours provided. Range of hour is (-23 to 23). ■ minutes The minutes provided. Range of minute is (-59 to 59). ■ seconds The seconds provided. Range of second is (-59 to 59). ■ milliSeconds The milliseconds provided. Range of millisecond is (- 999.999999 to 999.999999). Exceptions ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range. ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleIntervalDS. Remarks The sign of all the arguments must be the same. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-147 OracleIntervalDS(int, int, int, int, int) This constructor creates a new instance of the OracleIntervalDS structure and sets its value using the supplied days, hours, minutes, seconds, and nanoseconds. Declaration // C# public OracleIntervalDS (int days, int hours, int minutes, int seconds, int nanoseconds); Parameters ■ days The days provided. Range of day is (-999,999,999 to 999,999,999). ■ hours The hours provided. Range of hour is (-23 to 23). ■ minutes The minutes provided. Range of minute is (-59 to 59). ■ seconds The seconds provided. Range of second is (-59 to 59). ■ nanoseconds The nanoseconds provided. Range of nanosecond is (-999,999,999 to 999,999,999) Exceptions ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range. ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleIntervalDS. Remarks The sign of all the arguments must be the same. OracleIntervalDS(byte[ ]) This constructor creates a new instance of the OracleIntervalDS structure and sets its value to the provided byte array, which is in an internal Oracle INTERVAL DAY TO SECOND format. Declaration // C# public OracleIntervalDS (byte[ ] bytes); Parameters ■ bytes See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Constructors 9-148 Oracle Data Provider for .NET Developer’s Guide A byte array that is in an internal Oracle INTERVAL DAY TO SECOND format. Exceptions ArgumentException - bytes is not in internal Oracle INTERVAL DAY TO SECOND format, or bytes is not a valid Oracle INTERVAL DAY TO SECOND. ArgumentNullException - bytes is null. See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Structure Oracle Data Provider for .NET Types Structures 9-149 OracleIntervalDS Static Fields The OracleIntervalDS static fields are listed in Table 9–55. MaxValue This static field represents the maximum value for an OracleIntervalDS structure. Declaration // C# public static readonly OracleIntervalDS MaxValue; Remarks Maximum values: ■ Day: 999999999 ■ hour: 23 ■ minute is 59 ■ second: 59 ■ nanosecond: 999999999 MinValue This static field represents the minimum value for an OracleIntervalDS structure. Declaration // C# public static readonly OracleIntervalDS MinValue; Table 9–55 OracleIntervalDS Static Fields Field Description MaxValue Represents the maximum valid time interval for an OracleIntervalDS structure MinValue Represents the minimum valid time interval for an OracleIntervalDS structure Null Represents a null value that can be assigned to an OracleIntervalDS instance Zero Represents a zero value for an OracleIntervalDS structure See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members OracleIntervalDS Static Fields 9-150 Oracle Data Provider for .NET Developer’s Guide Remarks Minimum values: ■ Day: -999999999 ■ hour: -23 ■ minute: -59 ■ second: -59 ■ nanosecond: -999999999 Null This static field represents a null value that can be assigned to an OracleIntervalDS instance. Declaration // C# public static readonly OracleIntervalDS Null; Zero This static field represents a zero value for an OracleIntervalDS structure. Declaration // C# public static readonly OracleIntervalDS Zero; See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members See Also: ■ "Oracle.DataAccess.Types Namespace" on page 1-4 ■ OracleIntervalDS Structure ■ OracleIntervalDS Members See Also: ■ "Oracle.DataAccess.Typ